OData-tenging

Lýsir því hvernig OData v4.01 API-tenging er sett upp og notuð í Manor til að tengja ytri greiningartól á borð við Microsoft Excel, Power BI og Tableau beint við gögn í Manor.

Síðast uppfært

Yfirlit

Manor býður upp á REST API-þjónustu sem fylgir staðlinum OData v4.01 (Open Data Protocol). OData er OASIS-staðall sem skilgreinir góða starfshætti við gerð og notkun REST API-vefþjónusta. Með honum geta ytri kerfi sótt gögn og unnið með þau eftir hefðbundnum HTTP-reglum.

OData-þjónustan í Manor er eingöngu til lestrar (read-only). Ytri greiningartól og BI-hugbúnaður geta því sótt gögn um fyrirtæki, viðskiptavini, verk, fjármál og tímaskráningar. Engin hætta er á að þau breyti eða eyði færslum fyrir slysni.

Helstu eiginleikar OData-þjónustu Manor:

Forsendur

Áður en ytri verkfæri eru tengd við OData-veitu Manor þarf að setja upp þrennt í Kerfisstjórn:

  1. Sérsniðið hlutverk með OData-réttindum: Notandinn eða kerfistengingin þarf að hafa réttindin Getur notað OData vefþjónustu.
  2. Sérstakan kerfisnotanda: Þjónustuaðgang sem er ekki einstaklingur. Hann er stofnaður sérstaklega fyrir tenginguna og fær hlutverk með OData-aðgangi.
  3. Virkan API lykil: API lykil sem er gefinn út fyrir kerfisnotandann og notaður sem lykilorð í HTTP Basic-auðkenningu.

Skref 1: Veita OData-réttindi með hlutverki

Aðeins notendur með OData API-réttindi hafa aðgang að /odata-þjónustunni. Kerfisstjórar hafa þessi réttindi sjálfkrafa. Í sérsniðnum hlutverkum þarf að veita þau sérstaklega:

  1. Farðu í Kerfisstjórn → Hlutverk (/administration/role).

  2. Smelltu á Stofna nýtt hlutverk. Þú getur líka smellt á Breyta við sérsniðið hlutverk sem er þegar til. Innbyggð hlutverk eru merkt Innbyggt.

  3. Hakaðu við eftirfarandi undir réttindaflokknum OData:

    • Getur notað OData vefþjónustu. — Heimilar kerfisnotanda að nýta OData API vefþjónustu.

    OData-réttindi í hlutverkaglugganum

  4. Skoðaðu líka hina réttindaflokkana, t.d. Verk, Reikningar og Tímar. Gakktu úr skugga um að hlutverkið hafi viðeigandi lestrarréttindi að gögnunum sem nota á í skýrslugerðinni.

  5. Smelltu á Vista.

Skref 2: Stofna kerfisnotanda

Kerfisnotendur eru sérstakir aðgangar sem eru eingöngu ætlaðir fyrir API-aðgang og samtengingu kerfa. Þeir teljast ekki til greiddra notendaleyfa í áskriftinni.

  1. Farðu í Kerfisstjórn → Notendur (/administration/user).
  2. Smelltu á Stofna kerfisnotanda fyrir samtengingu kerfa efst til hægri á síðunni. Stofna kerfisnotanda fyrir samtengingu kerfa
  3. Skráðu skýrt Nafn, t.d. „Power BI skýrslur“ eða „Excel greiningarþjónusta“.
  4. Undir Hlutverk skaltu velja hlutverkið sem þú stilltir með OData-aðgangi, t.d. sérsniðna OData-hlutverkið þitt eða Kerfisstjóri.
  5. Smelltu á Vista.

Athugið: Kerfisnotandi er ekki einstaklingur. Hann er sérstakur aðgangur sem er notaður til að samtengja kerfi og gerir öðrum kerfum kleift að framkvæma aðgerðir í Manor.

Skref 3: Stofna API lykil

API lyklar eru auðkenni sem ytri kerfi nota við innskráningu:

  1. Farðu í Kerfisstjórn → API lyklar (/administration/api-key).
  2. Smelltu á Stofna lykil efst í hægra horninu. API lyklar
  3. Gluggi sem heitir Stofna lykil opnast. Skráðu lýsandi Nafn, t.d. „Power BI Desktop lykill“.
  4. Veldu kerfisnotandann úr skrefi 2 í fellilistanum Notandi.
  5. Ef þú vilt geturðu líka skráð dagsetningu í Rennur út og bætt við innri Lýsingu.
  6. Smelltu á Vista.
  7. Afritaðu lykilinn strax. Allur lykillinn er aðeins sýndur einu sinni, þegar hann er stofnaður. Af öryggisástæðum er ekki hægt að nálgast hann eftir það.

API lykillinn er byggður svona upp:

[tiltæki].[auðkenni].[leyndarmál]

Lykillinn skiptist í þrjá hluta sem eru aðskildir með punktum: forskeyti tiltækis sem auðkennir Manor-tiltækið þitt, auðkenni lykilsins og leyndarmál. Dæmi:

bigcorp.8XhJ1Ts5yDO2MeOL.4e9a8f2c9d1b7e30f6a2c4d5e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7

Athugið: Í dálkinum Lykill á síðunni API lyklar birtist aðeins auðkennishluti lykilsins, ekki allur lykillinn.

OData-vefslóð og lýsigögn

OData-veitan er hýst undir /odata á léni Manor-kerfis fyrirtækisins þíns.

Vefslóð Lýsing
https://<þitt-manor-lén>/odata Þjónustuskjal (Service Document): Sýnir alla gagnahópa (entity sets) og tilföng sem hægt er að sækja.
https://<þitt-manor-lén>/odata/$metadata Lýsigögn þjónustunnar (CSDL): XML/JSON-skjal sem skilgreinir allar einingagerðir, eiginleika, vensl og gagnatög.
https://<þitt-manor-lén>/odata/<Gagnahópur> Gagnasafn (Entity Collection): Skilar færslum tiltekins gagnahóps (t.d. /odata/Matters).

Ábending: Þú getur alltaf skoðað gagnaskipanina (schema). Opnaðu https://<þitt-manor-lén>/odata/$metadata í vafra eða API-tóli og skráðu þig inn með HTTP Basic-auðkennunum þínum.

Auðkenning

OData-þjónusta Manor notar HTTP Basic-auðkenningu:

Þegar ytra BI-verkfæri sendir beiðni les auðkenning Manor lykilinn úr Basic Auth-hausnum. Síðan finnur hún auðkennið og sannreynir tætigildi leyndarmálsins. Loks staðfestir hún að tengdi aðgangurinn sé virkur kerfisnotandi með réttindin Getur notað OData vefþjónustu. Notandanafnið í Basic Auth-hausnum er ekki sannreynt. Hvaða staðgengilsgildi sem er virkar því, svo framarlega sem lykilorðið inniheldur allan réttan API lykil.

Dæmi um HTTP-beiðnihaus

GET /odata/Matters HTTP/1.1
Host: your-subdomain.manor.app
Authorization: Basic <base64-encoded-credentials>
Accept: application/json

Aðgengileg gögn

Manor veitir víðtækan aðgang að rekstrargögnum í mörgum gagnahópum. Hér eru þeir algengustu:

Gagnahópur Undirliggjandi gögn Lýsing og umfang
Matters matters Verk og mál. Allar tímaskráningar, reikningshæfar færslur, reikningar og verkþættir tilheyra verki. Inniheldur reiknaða eiginleikann excluded_from_billable_ratio.
Clients clients Viðskiptavinir, bæði einstaklingar og fyrirtæki, sem fá reikninga fyrir vinnu.
Times times Ítarlegar tímafærslur sem starfsfólk skráir á verk og verkþætti.
Expenses expenses Útlagður kostnaður og efniskostnaður í verkum.
Invoices invoices Útgefnir reikningar, reikningsdrög, fjárhæðir, samtölur og staða reikninga.
InvoiceLines invoice_lines Einstakar reikningslínur.
Activities activities Verkþættir og áfangar sem flokka vinnu innan verka (einnig kallað Segments).
Users users Starfsfólk, sérfræðingar og kerfisnotendur fyrirtækisins.
Departments departments Deildir innan fyrirtækja.
Firms firms Lögaðilar og útibú sem eru skráð í kerfinu.
Rates rates Tímagjöld og taxtalíkön. Inniheldur reiknuðu eiginleikana latest_price og latest_cost_price.
RateCategories rate_categories Flokkar sem halda utan um taxtagerðir.
ReportingBillables reporting_billables Afstaðlað skýrslusýnd (denormalized view) sem sameinar tíma, akstur, kostnað, dagpeninga og vörur í eina töflu fyrir samræmda greiningu.
PerDiems per_diems Dagpeningar og ferðagreiðslur sem eru skráðar á verk.
Travels travels Akstur og ferðafærslur.
Products products Vörur með föstu verði og beinn útlagður kostnaður sem er skráður á verk.
Retainers retainers Samningar og áskriftarfyrirkomulag viðskiptavina.
RetainerPeriods retainer_periods Reikningstímabil og staða eftirstöðva samninga.
Labels labels Merki sem eru tengd verkum (einnig kallað Subjects).
Labellables labellables Tengsl verka og merkja.
Currencies currencies Gjaldmiðlar sem eru notaðir í reikningagerð og töxtum.
VatRates vat_rates VSK-hlutföll fyrir reikningslínur og reikningshæfar færslur.
PayPeriods pay_periods Launatímabil.
PayPeriodUser pay_period_user Tengsl notenda við einstök launatímabil.
BillableInvoiceLine billable_invoice_line Tengitafla sem tengir reikningshæfar færslur við einstakar reikningslínur.

Athugið: Viðkvæm gögn, svo sem lykilorð, persónuleg leyndarmál og auðkenningartóken, eru aldrei send út í gegnum OData.

Leiðbeiningar: Tenging við Microsoft Excel

Í Microsoft Excel er hægt að sækja OData-veitur beint inn í Power Query og gagnalíkön Power Pivot.

Skref 1: Opna OData-tengilinn

  1. Opnaðu Microsoft Excel og stofnaðu nýja vinnubók eða opnaðu vinnubók sem er þegar til.
  2. Opnaðu flipann Data á borða Excel.
  3. Smelltu á Get Data → From Other Sources → From OData Feed.

Skref 2: Skrá vefslóð veitunnar

  1. Í glugganum OData feed:
    • Veldu Basic.
    • Sláðu inn vefslóð OData-þjónustunnar: 
      https://<þitt-manor-lén>/odata
  2. Smelltu á OK.

Skref 3: Skrá auðkenni

  1. Veldu flipann Basic vinstra megin þegar innskráningarglugginn birtist.
  2. Fylltu út reitina:
    • User name: Auðkennishluti API lykilsins (eða api).
    • Password: Límdu allan API lykilinn, alla þrjá hlutana ([tiltæki].[auðkenni].[leyndarmál]).
    • Select which level to apply these settings to: Veldu https://<þitt-manor-lén>/odata.
  3. Smelltu á Connect.

Skref 4: Velja töflur og hlaða inn

  1. Glugginn Navigator opnast og sýnir alla aðgengilega gagnahópa í Manor (Matters, Times, Invoices, Clients o.s.frv.).
  2. Hakaðu við Select multiple items ef þú vilt sækja fleiri en eina töflu í einu.
  3. Veldu gagnahópana sem þú þarft. Forskoðun færslnanna birtist hægra megin.
  4. Smelltu á Load til að hlaða gögnunum beint inn í Excel-töflur. Þú getur líka smellt á Transform Data til að opna Power Query Editor. Þar geturðu síað dálka, breytt gagnatögum og búið til reiknuð svæði.

Tenging við Power BI og önnur BI-verkfæri

Microsoft Power BI Desktop

  1. Opnaðu Power BI Desktop.
  2. Smelltu á Get Data → OData feed á flipanum Home. Einnig er hægt að fara í Get Data → More... → Other → OData Feed.
  3. Sláðu inn vefslóðina https://<þitt-manor-lén>/odata og smelltu á OK.
  4. Í innskráningarglugganum:
    • Smelltu á flipann Basic vinstra megin.
    • Skráðu User name (auðkennishluta API lykilsins eða api).
    • Skráðu Password (allan API lykilinn).
    • Veldu https://<þitt-manor-lén>/odata sem stig auðkenninganna.
  5. Smelltu á Connect.
  6. Veldu gagnahópana sem þú þarft í glugganum Navigator (t.d. Matters, Times, ReportingBillables). Smelltu síðan á Load eða Transform Data.
  7. Búðu til vensl milli taflnanna með hefðbundnum lyklasvæðum (t.d. matter_id, client_id, user_id). Þá geturðu smíðað gagnvirk mælaborð og lykiltölur.

Tableau

  1. Opnaðu Tableau Desktop.
  2. Veldu OData undir Connect → To a Server.
  3. Í OData-tengiglugganum:
    • Server: Sláðu inn vefslóð tiltekins gagnahóps, t.d.: 
      https://<þitt-manor-lén>/odata/Matters
    • Authentication: Veldu Username and Password.
    • Username: Auðkennishluti API lykilsins.
    • Password: Allur API lykillinn.
  4. Smelltu á Sign In.
  5. Endurtaktu ferlið fyrir aðra gagnahópa sem gagnauppsprettan í Tableau þarf. Tengdu þá síðan saman á sameiginlegum ID-svæðum.

Qlik Sense og almennir REST/OData-biðlarar

Í Qlik Sense er hægt að nota REST Connector eða innbyggða OData Connector:

  1. Stofnaðu nýja gagnatengingu með vefslóðinni https://<þitt-manor-lén>/odata/<Gagnahópur>.
  2. Veldu Basic Authentication.
  3. Skráðu auðkennishluta lykilsins sem notandanafn og allan API lykilinn sem lykilorð.
  4. Settu HTTP-hausinn Accept: application/json.
  5. Keyrðu hleðsluskriftuna (load script).

Fyrirspurnarvalkostir og síðuskipting

Manor styður hefðbundna fyrirspurnarvalkosti OData v4. Með þeim geta ytri verkfæri síað, valið og raðað færslum á vefþjóninum áður en gögnin eru send. Þannig minnkar gagnamagnið sem fer yfir netið.

Kerfisfyrirspurnarvalkostir (System Query Options)

Hægt er að bæta fyrirspurnarvalkostum við slóð gagnahópa á hefðbundnu fyrirspurnarsniði:

Valkostur Tilgangur Dæmi
$select Skilar aðeins tilgreindum eiginleikum. Það minnkar gagnamagnið. /odata/Matters?$select=id,name,client_id,state
$filter Síar færslur eftir rökskilyrðum. /odata/Matters?$filter=state eq 'active'
$orderby Raðar niðurstöðum eftir einum eða fleiri eiginleikum í hækkandi (asc) eða lækkandi (desc) röð. /odata/Invoices?$orderby=issue_date desc
$top Takmarkar fjölda færslna sem skilað er. /odata/Times?$top=50
$skip Sleppir tilteknum fjölda færslna (notað við síðuskiptingu). /odata/Times?$skip=100&$top=50
$expand Tekur tengd gögn með inni í svarinu. /odata/Matters?$expand=client
$count Skilar heildarfjölda færslna ásamt niðurstöðunum. /odata/Matters?$count=true

Algengar síur og virkjar

Færibreytan $filter styður hefðbundna samanburðar- og rökvirkja:

Síðuskipting (1.000 færslur á síðu)

Manor skiptir niðurstöðum í síður á vefþjóninum. Þannig haldast afköst góð og minnið klárast ekki þegar mikið magn gagna er sótt:

Öryggisatriði

Hafðu eftirfarandi í huga til að tryggja öryggi við tengingu ytri skýrslutóla:

Tengt efni