Microsoft
Business Central
API (Service-to-Service) Alle notwendigen Einrichtungen

Erstellung der Azure App-Registrierung

Um die Microsoft Business Central API verwenden zu können, benötigen Sie eine Azure App-Registrierung. Wie können Sie eine solche App-Registrierung anlegen und die Werte

• Client-ID
• Client Secret

ermitteln, welche für die Verwendung der API notwendig sind?

Anlage der App-Registrierung

Öffnen Sie das Azure-Portal unter https://portal.azure.com  sowie anschließend über das Navigationsmenü die Verwaltung „Microsoft Entra ID“.

Im Reiter „Verwalten” befindet sich die Schaltfläche „App-Registrierungen”, in welcher Sie wiederum die Schaltfläche „Neue Registrierung” finden. Wählen Sie diese aus, um eine neue Anwendung zu registrieren.

Geben Sie der Anwendung in dem Formular, das sich öffnet, einen Namen und definieren Sie die unterstützten Kontotypen. Der Name ist frei wählbar und der Kontotyp ist abhängig davon, wer diese Anwendung in Zukunft verwenden bzw. auf diese API zugreifen darf. In diesem Beispiel werden nachfolgende Werte verwendet:

• Name: Demoapplikation
• Unterstützte Kontotypen: Nur Konten in diesem Organisationsverzeichnis (nur Contoso – einzelner Mandant)

Der optionale Punkt „Umleitungs-URI“ kann in dieser Einrichtung vernachlässigt werden. Bestätigen Sie die getätigten Eingaben mittels der Schaltfläche „Registrieren“.

Nach der Registrierung der App wird diese geöffnet. Die Client ID (Anwendungs-ID) können Sie der Zusammenfassung entehmen.

Anlage Client Secret

In der Verwaltung einer App-Registrierung können Sie ein neues Client Secret erstellen, indem Sie über das Navigationsmenü den Menüpunkt „Zertifikate & Geheimnisse“ auswählen und in der sich öffnenden Verwaltung auf die Schaltfläche „Neuer geheimer Clientschlüssel“ gehen.

Für den neuen geheimen Schlüssel müssen Sie einen Namen und einen Gültigkeitszeitraum angeben. Nach der Anlage können Sie das Client Secret der Spalte „Wert“ entnehmen:

Zuweisung von API-Berechtigungen

Das zwingende Zuweisen von API-Berechtigungen erfolgt über den Eintrag „API-Berechtigungen“, welcher sich über das Navigationsmenü aufrufen lässt. In dieser Verwaltung können Sie neue Berechtigungen über die Schaltfläche „Berechtigung hinzufügen“ anlegen.

Nun geht es darum, eine neue Berechtigung für den Zugriff auf Dynamics 365 Business Central anzulegen.

In der Kategorie „Anwendungsberechtigungen“ wählen Sie dafür nachfolgende Berechtigung aus:

• API.ReadWrite.All
• Automation.ReadWrite.All

Unter Umständen müssen Sie die Einrichtung nach der Anlage der Berechtigungen noch mittels der Schaltfläche „Administratorzustimmung für „Name Ihrer Organisation“ erteilen“ bestätigen.

Einrichtung der Entra-Anwendung in Business Central

Für den erfolgreichen Zugriff auf die Microsoft Business Central API müssen Sie die Anwendung, die Sie zuvor im Abschnitt Erstellung der Azure App-Registrierung erstellt haben, in Business Central hinterlegen. Die nachfolgenden Abschnitte beschreiben diesen Prozess.

Erstellung der Microsoft Entra-Anwendung

Die Microsoft Entra-Anwendung können Sie über die Seite „Microsoft Entra-Anwendungen“ anlegen. Navigieren Sie zu dieser Seite und legen Sie einen neuen Datensatz mittels der Schaltfläche „Neu“ an.

Befüllen Sie das Feld „Client-ID“ mit der Client-ID aus dem Abschnitt Erstellung der Azure App-Registrierung und vergeben Sie eine passende Beschreibung (Zum Beispiel: „API-Webshop“).

Anschließend kann der Status der Anwendung auf „Aktiviert“ geändert werden.

Zuweisung von Berechtigungen

Über das Inforegister „Benutzerberechtigungssätze“ gilt es der erstellten Anwendung alle Berechtigungen zu geben, die für den Betrieb der Schnittstelle notwendig sind.

Beispiel: Existiert ein API-Endpunkt, welcher Daten aus der Tabelle „Artikel“ abrufen möchte, so benötigt diese Anwendung mindestens lesenden Zugriff auf die Tabelle „Artikel“. Es ist also notwendig, einen entsprechenden Berechtigungssatz anzulegen bzw. einen bestehenden Berechtigungssatz zu verwenden. Der Berechtigungssatz „D365 Basic“ enthält beispielsweise die Berechtigung die Tabelle „Artikel“ zu lesen und wird im Folgenden für weitere Demonstrationen verwendet.

Die angelegten Berechtigungssätze können Sie über die Spalte „Mandant“ auf einzelne Mandanten beschränken. Ist der Wert in der Spalte leer, so gilt der Berechtigungssatz für alle Mandanten.

Einrichtung Postman

Dieser Abschnitt beschreibt beispielhaft eine Abfrage eines API-Endpunktes mittels der Anwendung „Postman“ (https://www.postman.com ). Es wird die grundlegende Bedienung der Anwendung vorausgesetzt.

Einrichtung URL

Erstellen Sie einen neuen „Request“ und fügen Sie nachfolgende URL ein:

https://api.businesscentral.dynamics.com/v2.0/{Tenant ID}/{Umgebung}/api/v2.0/companies

Die Werte „Tenant ID“ und „Umgebung“ müssen mit den korrekten Werten befüllt werden.

Beispiel:

• Tenant ID: Ihre Tenant ID
• Umgebung: „Production“ oder „Sandbox“ oder Ihr frei gewählter Sandboxname

Authentifizierung

Für die erstellte Abfrage in Abschnitt „Einrichtung Postman“ ist eine Authentifizierung mittels OAuth2.0 erforderlich. Diese lässt sich über den Reiter „Authorization“ und dem darin enthaltenen Auswahlmenü „Type“ auswählen.

Im Abschnitt „Configure New Token“ wählen Sie für den „Grant Type“ den Wert „Client Credentials“ aus und befüllen die restlichen Felder wie nachfolgend beschrieben.

• Token Name: Frei wählbar (beschreibt das erstellte Token)
• Grant Type: Client Credentials
• Access Token URL: https://login.microsoftonline.com/{Tenant ID}/oauth2/v2.0/token (🡨 Den Platzhalter „Tenant ID“ mit der korrekten Tenant ID ersetzen)
• Client ID: Die in Abschnitt „Anlage der App-Registrierung“ erstellte Client ID
• Client Secret: Das in „Anlage Client Secret“ erstellte Client Secret
• Scope: https://api.businesscentral.dynamics.com/.default
• Client Authentication: Send as Basic Auth header

Nach der Befüllung der Felder kann ein neues Token mittels der Schaltfläche „Get New Access Token“ abgerufen werden.

In dem Fenster, das sich nun öffnet, können Sie das zuvor abgefragte Token über die Schaltfläche „Use Token“ für zukünftige Abfragen verwenden.

Abfrage Artikel

Um die Standard-Artikel-API abzufragen, müssen Sie zuvor den korrekten Mandanten auswählen. Hierzu können Sie nach erfolgreichem Abschluss der Abschnitte „Einrichtung URL“ und „Authentifizierung“ auf die Schaltfläche „Send“ klicken. Das Ergebnis der Abfrage beinhaltet alle verfügbaren Mandanten. Wählen Sie die „id“ eines Mandanten aus:

Nach der Auswahl muss die URL aus dem Abschnitt „Einrichtung URL“ um die zuvor ausgewählte Mandanten-ID und den Endpunkt „items“ erweitert werden.

https://api.businesscentral.dynamics.com/v2.0/{Tenant ID}/{Umgebung}/api/v2.0/companies({Mandanten-ID})/items

Nach der Bestätigung der Eingabe mit der Schaltfläche „Send“ werden alle Artikel in diesem Mandanten abgerufen.