D365 F&O REST API: Den Ultimative Guide

At integrere Microsoft Dynamics 365 Finance & Operations (D365FO) med andre systemer er en afgørende opgave for mange virksomheder, der ønsker at strømline deres processer og sikre en gnidningsfri dataudveksling. En af de mest kraftfulde metoder til at opnå dette er ved at bruge Data Management Framework's Package Representational State Transfer (REST) Application Programming Interface (API). Denne API muliggør robust og filbaseret dataintegration ved hjælp af datapakker og understøtter både cloud- og on-premise-installationer af D365FO, hvilket giver en utrolig fleksibilitet.

Uanset om du skal importere store mængder data fra et eksternt system eller eksportere transaktionsdata til et data warehouse, tilbyder denne API de nødvendige værktøjer. I denne artikel vil vi dykke ned i alle aspekter af D365 F&O Package REST API, fra valg af den rette integrationsmetode til detaljerede gennemgange af import- og eksportprocesser, fejlhåndtering og praktiske eksempler på implementering.

Valg af den Rette Integrations-API

Før man kaster sig ud i kodningen, er det vigtigt at forstå, at D365FO tilbyder to primære API'er til filbaseret integration: Data Management Framework's Package API og Recurring Integrations API. Valget mellem disse afhænger af dine specifikke krav til planlægning, formatering og transformation. Nedenstående tabel sammenligner de to API'er for at hjælpe dig med at træffe den rigtige beslutning.

Hvis dine behov peger i retning af ekstern planlægning og en ren REST-baseret tilgang, er Data Management Framework's Package API det oplagte valg. Resten af denne artikel fokuserer udelukkende på denne API.

Autorisation: Sikring af Adgang til din API

Sikkerhed er altafgørende, når man arbejder med forretningskritiske data. Package API'en bruger OAuth 2.0 til at autorisere adgang, hvilket sikrer, at kun godkendte applikationer kan interagere med dit D365FO-miljø. For cloud-implementeringer håndteres dette via Microsoft Azure Active Directory (Azure AD), mens on-premise-installationer benytter Active Directory Federation Services (AD FS).

Når du bruger Client Credentials Grant-flowet, skal du registrere din applikation på siden Systemadministration > Opsætning > Azure Active Directory-applikationer i D365FO. Her angiver du det godkendte klient-ID og den brugerkontekst (sikkerhedsmapping), som API-kaldene skal udføres under. Dette sikrer, at API'en overholder de samme sikkerhedsregler og tilladelser som den tilknyttede bruger.

Dybdegående Gennemgang af Import-API'er

Importprocessen består af flere trin, der involverer at hente en skrivbar URL, uploade datapakken og starte importjobbet. Her er de centrale API-kald, du skal bruge.

1. GetAzureWritableUrl

Dette er det første skridt i importprocessen. Du kalder denne API for at få en midlertidig, skrivbar URL til en Azure Blob Storage-container (eller et lokalt lager for on-premise). URL'en indeholder et Shared Access Signature (SAS) token, der giver dig midlertidig tilladelse til at uploade din datapakke.

• Formål: At få en sikker URL til at uploade en datapakke.
• Input: Et unikt filnavn (uniqueFileName). Det anbefales at inkludere et GUID for at sikre unikhed.
• Output: Et JSON-objekt, der indeholder et BlobId og en BlobUrl med et indlejret SAS-token.

2. ImportFromPackage

Når din datapakke er uploadet til den URL, du modtog, kalder du ImportFromPackage for at starte selve importjobbet i D365FO. Dette API-kald sætter gang i datahåndteringsframeworket til at behandle den uploadede pakke.

• Formål: At initiere et importjob fra en uploadet datapakke.
• Inputparametre:
  • packageUrl: URL'en til den uploadede datapakke.
  • definitionGroupId: Navnet på dataprojektet i D365FO.
  • executionId: Et valgfrit ID til jobbet. Hvis det er tomt, genereres et nyt.
  • execute: En boolean-værdi, der angiver, om dataene skal flyttes fra staging til target med det samme.
  • overwrite: En boolean-værdi. Skal altid være false, hvis pakken indeholder en sammensat enhed (composite entity).
  • legalEntityId: Den juridiske enhed, som dataene skal importeres til.
• Output: Jobbets executionId, som bruges til at spore status.

Fejlhåndtering under Import

Hvis noget går galt, giver API'en metoder til at diagnosticere problemet:

• GetImportStagingErrorFileUrl: Henter en URL til en fejlfil, der indeholder poster, som fejlede under flytningen fra kilde til staging.
• GenerateImportTargetErrorKeysFile: Genererer en fejlfil med nøglerne til de poster, der fejlede under flytningen fra staging til target.
• GetImportTargetErrorKeysFileUrl: Henter URL'en til den fejlfil, der blev genereret i det forrige trin.

Effektiv Dataeksport med Export-API'er

Eksportprocessen er mere ligetil og involverer at starte et eksportjob og derefter hente den genererede datapakke.

1. ExportToPackage

Dette API-kald starter et eksportjob baseret på et eksisterende dataprojekt i D365FO. Hvis projektet bruger ændringssporing, vil kun ændrede eller nye poster siden sidste kørsel blive eksporteret.

• Formål: At initiere et eksportjob og generere en datapakke.
• Inputparametre:
  • definitionGroupId: Navnet på dataprojektet.
  • packageName: Det ønskede navn på den eksporterede fil.
  • executionId: Et valgfrit ID, hvis det er en genkørsel af et eksisterende job.
  • reExecute: En boolean-værdi for at genkøre et job.
  • legalEntityId: Den juridiske enhed, dataene skal eksporteres fra.
• Output: Jobbets executionId.

2. GetExportedPackageUrl

Når eksportjobbet er færdigt, bruges dette kald til at få en download-URL til den genererede datapakke. Ligesom ved import indeholder URL'en et SAS-token for sikker adgang.

• Formål: At hente en download-URL til en eksporteret datapakke.
• Input: Jobbets executionId.
• Output: En BlobUrl, der kan bruges til at downloade filen.

Overvågning og Statuskontrol

Både under import og eksport er det afgørende at kunne tjekke status for et kørende job. Til dette formål findes der et centralt API-kald.

GetExecutionSummaryStatus

Dette kald returnerer den aktuelle status for et givet executionId. Det er vigtigt at polle denne status regelmæssigt for at vide, hvornår et job er færdigt, eller om det er fejlet.

• Formål: At tjekke status for et datajob.
• Input: Jobbets executionId.
• Output: En statusstreng. Mulige værdier inkluderer:
  • Unknown
  • NotRun
  • Executing
  • Succeeded
  • PartiallySucceeded
  • Failed
  • Canceled

Udfordringer og Løsninger: Håndtering af Asynkrone Kald

Integration med en REST API i D365FO kan være udfordrende, især under spidsbelastning. Netværksproblemer, server-timeouts eller rate limits kan forårsage midlertidige fejl. En naiv tilgang, hvor man blot fejler ved første problem, er ikke robust nok til produktionsmiljøer.

Løsningen er at implementere en klient, der håndterer asynkrone kald og har en indbygget genforsøgsmekanisme. En bedste praksis er at bruge en strategi kaldet exponential backoff. Dette betyder, at klienten venter en progressivt længere periode mellem hvert genforsøg. For eksempel: vent 2 sekunder efter første fejl, 4 sekunder efter anden, 8 sekunder efter tredje, og så videre. Dette forhindrer, at man overbelaster en midlertidigt utilgængelig tjeneste og øger chancerne for succes, når tjenesten bliver tilgængelig igen.

En sådan robust klient bør:

1. Udføre API-kald asynkront: Dette forhindrer, at hovedprocessen blokeres, mens man venter på et svar.
2. Implementere exponential backoff: For at håndtere midlertidige fejl intelligent.
3. Have solid fejlhåndtering: Logge fejl, spore antallet af genforsøg og give klare fejlmeddelelser for nemmere debugging.

Ofte Stillede Spørgsmål (FAQ)

Hvad er den primære forskel på Package API'en og Recurring Integrations API'en?

Den primære forskel ligger i, hvordan jobs planlægges og initieres. Med Recurring Integrations API sker planlægningen internt i D365FO. Med Package API'en styres hele processen, inklusiv planlægning, eksternt af det system, der kalder API'en. Dette giver større fleksibilitet for eksterne integrationsplatforme.

Hvordan håndterer API'en sikkerhed og autorisation?

API'en bruger OAuth 2.0-protokollen. Enhver applikation, der ønsker at kommunikere med API'en, skal først autentificere sig via Azure Active Directory (for cloud) eller AD FS (for on-premise) for at modtage et adgangstoken. Dette token skal inkluderes i alle efterfølgende API-kald. Adgangen styres yderligere ved at mappe applikationens klient-ID til en specifik bruger i D365FO.

Er det muligt at bruge denne API til on-premise installationer af D365FO?

Ja, en af de store fordele ved Data Management Framework's Package API er, at den understøtter både cloud- og on-premise-implementeringer af D365FO. Dette sikrer en ensartet integrationsmetode på tværs af forskellige hosting-miljøer.

Hvad betyder "exponential backoff", og hvorfor er det vigtigt?

Exponential backoff er en fejlhåndteringsstrategi, hvor et program venter i længere og længere tid mellem genforsøg på en mislykket handling. Det er vigtigt for at skabe robuste integrationer, da det forhindrer, at man oversvømmer en midlertidigt overbelastet eller utilgængelig tjeneste med gentagne anmodninger. Det giver systemet tid til at komme sig og øger sandsynligheden for, at det næste forsøg lykkes.