Guide til OData-forespørgsler i Dynamics 365

Open Data Protocol (OData) er en afgørende standardprotokol for oprettelse og forbrug af data. Formålet med OData er at levere en REST-baseret protokol til CRUD-operationer (Create, Read, Update, Delete), som gør det muligt for udviklere at interagere med data via RESTful webtjenester. Ved at anvende webteknologier som HTTP og JSON giver OData adgang til information fra en bred vifte af programmer. Denne protokol tilbyder en enkel og ensartet måde at dele data på, hvilket fremmer bred integration på tværs af produkter og muliggør integration ved hjælp af HTTP-protokolstakken. I sammenhæng med Dynamics 365 åbner OData op for en verden af muligheder for at få adgang til og manipulere data på en struktureret og effektiv måde.

Hvad er formålet med OData?

OData er designet til at standardisere dataadgang over internettet. Det bygger på velkendte teknologier som HTTP, REST og JSON, hvilket gør det let for udviklere at lære og implementere. Fordelene ved at bruge OData er mange og betydningsfulde for moderne applikationsudvikling:

• Standardiseret interaktion: Det giver udviklere mulighed for at interagere med data ved hjælp af RESTful webtjenester, hvilket er en branchestandard.
• Simpel datadeling: Det tilbyder en enkel og uniform metode til at dele data på en måde, der er let at opdage og forstå.
• Bred integration: Protokollen muliggør problemfri integration på tværs af forskellige produkter og platforme.
• HTTP-baseret: Integrationen sker via den almindelige HTTP-protokolstak, hvilket fjerner behovet for komplekse drivere eller biblioteker.

I Dynamics 365 fungerer det offentlige OData-serviceendepunkt som en gateway, der giver adgang til data på en konsistent måde for en bred vifte af klienter. For at se en liste over alle de enheder, der er eksponeret, kan man åbne OData-tjenestens rod-URL, som typisk har formatet: [Din organisations rod-URL]/data.

Adressering af Ressourcer med OData

For at interagere med data via OData skal man forstå, hvordan ressourcer adresseres. Hver del af en URL specificerer en bestemt ressource, fra hele datasæt til enkelte felter. Nedenfor er en tabel, der illustrerer, hvordan forskellige ressourcer adresseres ved hjælp af et eksempel fra Fleet Management.

Understøttede Funktioner fra OData-specifikationen

Dynamics 365's OData-tjeneste understøtter en række centrale funktioner, som giver stor fleksibilitet i datahåndtering. Disse funktioner er i overensstemmelse med den officielle OData-specifikation.

CRUD Support

Fuld CRUD-funktionalitet (Create, Retrieve, Update, Delete) håndteres via standard HTTP-verber:

• POST: Opretter en ny ressource.
• GET: Henter en ressource.
• PATCH/PUT: Opdaterer en eksisterende ressource.
• DELETE: Sletter en ressource.

Query Options (Forespørgselsindstillinger)

OData giver dig mulighed for at forme og filtrere resultaterne ved hjælp af en række forespørgselsindstillinger, der tilføjes til URL'en:

• $filter: Anvender filterkriterier til samlingen.
• $count: Returnerer det samlede antal elementer i samlingen.
• $orderby: Sorterer resultaterne.
• $skip: Springer et specificeret antal elementer over.
• $top: Begrænser antallet af returnerede elementer.
• $expand: Inkluderer relaterede enheder i resultatet (kun første niveau understøttes).
• $select: Specificerer, hvilke egenskaber der skal returneres.

Derudover understøtter OData-tjenesten server-drevet paginering med en maksimal sidestørrelse på 10.000 poster for at sikre god ydeevne.

Filterdetaljer og Operatorer

$filter-indstillingen er særligt kraftfuld og understøtter en række indbyggede operatorer, der minder om SQL:

• Sammenligning:eq (lig med), ne (ikke lig med), gt (større end), ge (større end eller lig med), lt (mindre end), le (mindre end eller lig med).
• Logiske:and, or, not.
• Aritmetiske:add, sub, mul, div, divby, mod.
• Gruppering: Parenteser () til at styre rækkefølgen af operationer.

En særlig nyttig funktion er brugen af contains, som er implementeret som et jokertegn. For eksempel, for at finde alle enheder, hvor et strengfelt indeholder ordet 'retail', kan du skrive: $filter=StringField eq '*retail*'. Det er dog vigtigt at bemærke, at operatorerne 'has' og 'in' ikke understøttes.

Avancerede Emner

Batch-anmodninger

For at forbedre ydeevnen og reducere antallet af netværkskald understøtter OData-tjenesten batch-anmodninger. Dette giver dig mulighed for at samle flere operationer i en enkelt HTTP-anmodning. Dette er især nyttigt, når du skal udføre mange oprettelser eller opdateringer på én gang.

Data på Tværs af Virksomheder (Cross-Company)

Som standard returnerer OData kun data, der tilhører brugerens standardfirma. For at få adgang til data fra andre firmaer, som brugeren har adgang til, skal du tilføje forespørgselsindstillingen ?cross-company=true. Dette er en afgørende funktion for organisationer med flere juridiske enheder.

Eksempel på at hente data fra alle tilgængelige firmaer:

http://[baseURI]/data/FleetCustomers?cross-company=true

Hvis du vil filtrere på et specifikt firma, der ikke er dit standardfirma, kan du kombinere det med et filter på dataAreaId:

http://[baseURI]/data/FleetCustomers?$filter=dataAreaId eq 'usrt'&cross-company=true

Eksponering af Egne OData-enheder og Handlinger

OData-enheder er baseret på opdaterbare visninger (updatable views). For at eksponere en visning som en OData-enhed på øverste niveau, skal du sætte dens IsPublic-egenskab til TRUE i AOT (Application Object Tree). Dette gør dine brugerdefinerede data tilgængelige via OData-endepunktet.

Du kan også tilføje brugerdefinerede handlinger (actions) til dine OData-enheder. Dette gøres ved at tilføje en metode til den opdaterbare visning og dekorere den med attributten SysODataActionAttribute. Dette giver dig mulighed for at indlejre forretningslogik, der kan kaldes via OData.

Her er et eksempel på en metode, der eksponeres som en handling:

[SysODataActionAttribute("CalcMaintenanceDuration", true)] public int CalculateMaintenanceDuration() { // Forretningslogik her return 0; }

Efter eksponering vil denne handling være synlig i tjenestens $metadata-dokument og kan kaldes fra klientapplikationer.

Ofte Stillede Spørgsmål (FAQ)

Hvordan håndterer jeg godkendelse (authentication)?

OData i Dynamics 365 benytter den samme godkendelsesstak som serveren. Dette betyder, at adgangskontrol og sikkerhed håndteres centralt, og brugere vil kun kunne se og redigere data, de har tilladelse til. For mere information henvises til den officielle dokumentation om serviceendepunkter.

Hvorfor tager det første OData-kald lang tid efter en genstart?

Det første OData-kald, der behandles af en AOS (Application Object Server), der lige er blevet genstartet, kan tage lang tid. Dette skyldes, at metadata-cachen endnu ikke er bygget. Denne forsinkelse kan undgås ved at "opvarme" OData under AOS-opstart. Der findes procedurer for at bygge OData-metadata-cachen, når AOS starter, for at sikre hurtig respons fra første kald.

Understøtter OData array-felter?

Nej, OData understøtter ikke array-felter i enheder. Dette er en vigtig begrænsning at være opmærksom på, når man designer enheder, der skal eksponeres via OData. Data skal struktureres i relaterede enheder i stedet for at bruge arrays.

Hvordan bruger jeg Enums i en OData-forespørgsel?

Enums (nummererede typer) er placeret under navneområdet Microsoft.Dynamics.DataEntities. For at bruge en enum-værdi i en forespørgsel, skal du angive det fulde navneområde efterfulgt af enum-navnet og værdien. Operatorerne eq (lig med) og ne (ikke lig med) understøttes for enums.

Eksempel på forespørgsel med en enum:

https://[URL]/data/CustomersV3?$filter=PersonGender eq Microsoft.Dynamics.DataEntities.Gender'Unknown'

Ved at forstå disse principper og funktioner kan udviklere og administratorer udnytte den fulde kraft af OData til at bygge robuste og effektive integrationer med Dynamics 365.