ENTWICKLER-BLOG

OData REST Web Service Beispiel (Publish)20 Nov2019

Kategorie: AL Development

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 wir ein Beispiel aufbauen, einige Vorbereitungen vorgenommen werden müssen.

  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

Dynamics 365 Business Central (Navision) - Benutzerkarte - Webdienstzugriff

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

Dynamics 365 Business Central (Navision) - Webdienst - Zugriffschlüssel festlegen

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

Dynamics 365 Business Central (Navision) - der generierte Webdienstschlüssel

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

Dynamics 365 Business Central (Navision) - Postman App herunterladen

  1. 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/

Dynamics 365 Business Central (Navision) - REST - Resource abrufen

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

Dynamics 365 Business Central (Navision) - REST - Authorisation eirichten

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

Dynamics 365 Business Central (Navision) - REST - Basic Authorisation

  1. 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.

Dynamics 365 Business Central (Navision) - REST Apis Liste

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

Dynamics 365 Business Central (Navision) - REST - Mandanten GUID

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:

Dynamics 365 Business Central (Navision) - REST - GET Beispiel

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:

Dynamics 365 Business Central (Navision) - REST - GET Beispiel mit Filtern

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:

Dynamics 365 Business Central (Navision) - REST - GET Beispiel mit Select

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:

Dynamics 365 Business Central (Navision) - REST - GET Beispiel mit gt Filter

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.

Dynamics 365 Business Central (Navision) - REST - POST Beispiel - eTAG

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

Dynamics 365 Business Central (Navision) - REST - neuer Artikel

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)

Dynamics 365 Business Central (Navision) - REST - PATCH Beispiel

  • 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:

Dynamics 365 Business Central (Navision) - REST - PATCH Beispiel - If-Match Parameter

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

Das Ergebnis sieht so aus:

Dynamics 365 Business Central (Navision) - REST - PATCH Beispiel - Body

Und im Klienten:

Dynamics 365 Business Central (Navision) - Angepasster Artikel

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.

Dynamics 365 Business Central (Navision) - REST - DELETE Beispiel

Auch der erneute GET-Versuch erregt kein Ergebnis.

Dynamics 365 Business Central (Navision) - REST - GET nach dem DELETE Beispiel

Dynamics 365 Business Central(TM) (Navision) Entwickler und Berater View Konrad Buczkowski's LinkedIn profile Konrad Buczkowski