Wie OData in Business Central verwendet wird - Teil 2

In dem Beitrag zeigen wir ein Beispiel von REST-OData Webserivce von Business Central. Im Teil 1 haben wir ein Beispiel, wo Navision ein anderes System über REST-Odata zugegriffen und abgefragt hat und als eine Response einen QR-Kode erhalten hat. Wir haben diese Richtung als 'Subscribe' Beispiel genannt. Jetzt wollen wir die Navision Ressourcen ausstellen, die von außen abgefragt oder manipuliert werden könnten (mit CRUD). Das Beispiel heißen wir 'Publish' OData Webservice. Bevor ein Beispiel aufgebaut wird, es müssen einige Vorbereitungen vorgenommen werden.

1. Einrichtung der Identifizierung um mit dem 'Webdienst-Zugriffschlüssel' zur REST zu kommunizieren.

In unserem Beispiel brauchen wir eine 'Basic authentication'. Die andere Option ist eine 'AAD' - Azure Active Directory.

• Sicherstellen, dass die Authentifizierung in Business Central auf NavUserPassswort umgestellt ist. Es ist notwendig um die OData und SOAP Dienste mit 'Webdienst-Zugriffschlüssel' authentifizieren zu können. Die Umstellung von Windows auf NavUserPassword wurde in dem Beitrag beschrieben.
• In Business Central die Seite 'Benutzer' auswählen
• Auf der Seite zum Register 'Webdienstzugrif' gehen
• Im Feld 'Webdienst-Zugriffschlüssel' AssistEdit öffnen

• Im Popup-Fenster einen Webdienst-Zugriffschlüssel festlegen.

• Der generierte Schlüssel im Zwischenspeicher kopieren. Der wird uns zum Authentifizierung dienen.

2. Postman von hier herunterlanden, installieren und ggf. registrieren.

3. In Postman eine Verbindung zu REST-Api von Business Central erstellen.

• Postman öffnen und eine neue Request generieren.
• In der Commandline schreiben: http://x2:15048/BC150/api/beta/

• Darüber hinaus muss die Authentifizierung eingerichtet werden. den Reiter 'Authorisation' öffnen and die Authentifizierungsart 'Basic Auth' auswählen.

• Im Feld 'Username' den Namen des Benutzers mit den zugewiesenen 'Webdienst-Zugriffschlüssel' schreiben. Im Feld 'Password' den generierten 'Webdienst-Zugriffschlüssel' schreiben.

4. Sobald alles eingerichtet können wir den Ruff GET mit dem Knopf 'Send' versuchen. Falls erfolgreich, bekommen wir den Status des Abrufs '200' und im Body eine json Response mit der Liste von im Business Central vorhandenen REST-Apis. In der aktuellen Version (2019 wave 2 - Oktober 2019 Release) gibt es 51 Apis, die in Web Services verwendet werden können.

5. Jetzt wird eine Liste von vorhandenen Mandanten aufgerufen mit der Methode: http://x2:15048/BC150/api/beta/companies.

In unserem Beispiel haben wir nur einen Mandanten. Gäbe es mehr Mandanten, hätten wir mehr Sätze mit den verschiedenen ID-Nummer. Die brauchen wir, um die Resoursen des bestimmten Mandanten aufrufen zu können. Der Syntax jedes Aufrufs soll so aussehen:

http://x2:15048/BC150/api/beta/companies(<Mandanten-ID>)/<Resource-ID>?$filter=<Abfrage>

Jetzt können wir mit den Beispielen beginnen. In den folgenden Schritten führen wir die folgenden Methoden aus:

• GET
• GET mit Filtern
• POST
• PATCH
• DELETE

GET - Beispiel

Aus allen 51 vorhanden in Dynamics 365 REST-Apis wählen wir die Artikel: items. Unser Ziel ist eine Liste von Artikeln für den ausgewählten Mandant aufzurufen. Der Mandant-ID ist 7710cc50-8d16-44d6-ac77-17f9b630c757. Die komplette Abfrage sieht so aus:

http://x2:15048/BC150/api/beta/companies(7710cc50-8d16-44d6-ac77-17f9b630c757)/items

Das Ergebnis: Eine Liste von allen Artikeln:

GET mit Filtern - Beispiel

Im zweiten Beispiel versuchen wir die Artikelliste nur auf die Artikel zu filtern, die zwischen '7' und '8' liegen (die Variable number ist eine Textart). Die Abfrage sieht so aus:

http://x2:15048/BC150/api/beta/companies(7710cc50-8d16-44d6-ac77-17f9b630c757)/items?$filter=(number gt '7' and number lt '8')

Das Ergebnis:

Darüber hinaus wollen wir unsere Ergebnisse nur zu drei Spalten einschränken, nämlich number,displayName,inventory und unitPrice. Die Abfrage sieht so aus:

http://x2:15048/BC150/api/beta/companies(7710cc50-8d16-44d6-ac77-17f9b630c757)/items?$filter=(number gt '7' and number lt '8')&$select=number, displayName, inventory, unitPrice

Das Ergebnis:

Zum Schluss wollen wir nur die Artikel mit dem Einzelpreis über 2000 haben. Die Abfrage sieht so aus:

http://x2:15048/BC150/api/beta/companies(7710cc50-8d16-44d6-ac77-17f9b630c757)/items?$filter=(number gt '7' and number lt '8') and unitPrice gt 2000 &$select=number, displayName, inventory, unitPrice

Als Ergebnis wurde unsere Liste auf 2 Artikel eingeschränkt:

POST - Beispiel

In unserem REST- Post Beispiel wollen wir einen neuen Artikel hinterlegen. Die Methode wird in den folgenden Schritten ausgeführt:

1. Body auswählen.
2. Media-Type JSON wählen
3. Im Body alle Felder kopieren, die weggeschrieben werden sollten.
4. Den Command POST ausführen: http://x2:15048/BC150/api/beta/companies(7710cc50-8d16-44d6-ac77-17f9b630c757)/items. Als Ergebnis wird ein neuer Satz weggeschrieben. Zu beachten sind:

• Der GUID des neuen Satzes. Den brauchen wir zukünftig, um den Satz aufzurufen oder z.B. zu löschen mit DELETE.
• ETag-Token. Den brauchen wird noch später im PATCH Command.

Ob der Satz wirklich erstellt wurde, können wir direkt in der Anwendung prüfen.

PATCH - Beispiel

In einer PATCH Methode können wir einen existierenden Satz ändern. Zum Beispiel werden wir den Einstandspreis des Artikels 'Seccount' von 50,20 auf 75,00 ändern. Dazu brauchen wir den GUID des Satzes (<Resource-ID>), wie im Muster unten

http://x2:15048/BC150/api/beta/companies(<Mandanten-ID>)/<Resource-ID>?$filter=<Abfrage>

Den Resource-ID kennen wir aus dem POST Beispiel. Wir können den immer mit der GET-Abfrage finden.

Der zweite Parameter ist der ETag-Token. Im ETag-Token wird ein Stand des Ressourcen auf Serverebene gespeichert. Es heißt, wird der Stand des Resources (z.B. des Satzes) geändert, ändert sich auch der Token. Wir brauchen den Token um sicherzustellen, dass die Änderung wir vornehmen wollen zu dem aktuellen Recordstand weggeschrieben wird. Ansonsten bekommen wir eine Fehlermeldung (der Satz wurde von anderen Benutzern abgeändert).

In unserem Beispiel wird der ETag-Token im Parameter "@odata.etag" gespeichert und lautet: "W/\"JzQ...Dsn\"" . Da wir ODATAV4 nutzen, es ist eine base64 encode Version des E-Tages.

Um den Satz zu PATCHen müssen wir:

• Den Resource mit dem bestimmten Resource-ID aufrufen.

http://x2:15048/BC150/api/beta/companies(7710cc50-8d16-44d6-ac77-17f9b630c757)/items(0e769a01-b00b-ea11-90ee-907841ee06f0)

• Im Header muss der ETag als "If-Match" weggeschrieben werden. Dazu müssen die Escape Zeichen am Anfang und Endes des Strings gelöscht werden. Der String soll so aussehen: W/"JzQ...Dsn". In Postman sieht alles so aus:

Im letzten Schritt schreiben wir im Body, was abgeändert werden sollte.

Das Ergebnis sieht so aus:

Und im Klienten:

DELETE - Beispiel

In einem DELETE Beispiel löschen wir den Artikel 'Seccount', den wir in früheren Schritten eingelegt und geändert haben. Dazu brauchen wir den <Resource-ID>. Der Synthax sieht ähnlich wie bei GET-Methode.

http://x2:15048/BC150/api/beta/companies(7710cc50-8d16-44d6-ac77-17f9b630c757)/items(0e769a01-b00b-ea11-90ee-907841ee06f0)

Wenn wir den ausführen, bekommen wir den Status 204 No Content. Der Rekord wurde abgegriffen.

Auch der erneute GET-Versuch erregt kein Ergebnis.

Dynamics 365 Business Central^(TM) (Navision) Entwickler und Berater Konrad Buczkowski