API Page Creator#
Allgemein#
In der Entwicklungsumgebung von Microsoft Dynamics 365 Business Central1 werden Seiten vom Typ "API" zum Erstellen von versionierten, Webhook-unterstützten, OData v4-fähigen REST-Webdiensten verwendet. Dieser Seitentyp kann nicht in der Benutzeroberfläche angezeigt werden, ist jedoch für die Erstellung zuverlässiger Integrationsdienste vorgesehen. Beim Erstellen dieses Seitentyps müssen Sie zahlreiche Eigenschaften angeben, die Informationen für den Webdienst-Endpunkt bereitstellen. Seiten vom Typ "API" können zur Entwicklung einer benutzerdefinierten API verwendet werden. Weitere Informationen finden Sie unter Entwickeln einer benutzerdefinierten API.
Um AnwenderInnen die Erstellung von API-Pages für einen rein lesenden Zugriff auf Datenbereiche zu vereinfachen, steht mit dem Modul "API Page Creator" ein Werkzeug zur Verfügung, dass entweder die grundlegenden Dateien für die Weiterverarbeitung zu einer App durch eine/n EntwicklerIn oder bereits eine fertiggestellte App-Datei erzeugen kann. Somit kann bei der letztgenannten Option eine Interaktionsmöglichkeit z.B. innerhalb der Microsoft1 Power-Plattform auf beliebige Datenbereiche geboten werden, ohne dass ein/e EntwicklerIn für die individuelle Erstellung einer entsprechenden App tätig werden muss.
Hinweis
Für den Zugriff auf Daten müssen BenutzerInnen trotzdem mittels des Berechtigungssystems in Microsoft Dynamics 365 Business Central1 berechtigt werden.
Der Zugriff erfolgt aktuell ausschließlich lesend. Ein Hinzufügen, Ändern oder Löschen von Datensätzen wird nicht unterstützt.
API Page Creator Einrichtung#
Die Seite "API Page Creator Einrichtung" ist der zentrale Anlaufpunkt für die einfache Generierung einer individuellen App mit API Pages. Hier werden die Grundeinstellungen für die zu erstellende App hinterlegt. Des Weiteren stehen an dieser Stelle die benötigten Funktionalitäten zur Verfügung, um eine App entweder als Entwicklungsgrundlage für die weitere Ausprägung durch EntwicklerInnen in Visual Studio Code oder als gebrauchsfertige App für den direkten Einsatz in einem Test- oder Produktivsystem zu erstellen.
Inforegister Allgemein#
Im Inforegister "Allgemein" werden die grundsätzlichen Einstellungen für die spätere Erstellung einer eigenständigen App hinterlegt. Die Angabe der hier genannten Felder ist verpflichtend.
| Feld | Beschreibung |
|---|---|
| Herausgeber | Dieses Feld zeigt den Wert an, der bei der späteren Erstellung der App als Herausgeber verwendet und in entsprechenden Darstellungen angezeigt wird. Bei der Initialisierung der Einrichtung wird dieses Feld standardmäßig mit dem Unternehmensnamen aus den Firmendaten vorbelegt. Sollte dort noch kein Name eingetragen sein, so wird als Standardwert Default Publisher verwendet. Der Name kann an dieser Stelle manuell überschrieben werden. Der hier angegebene Wert wird ebenfalls als Eigenschaft APIPublisher in jeder API-Page verwendet. Für die Erstellung einer App darf dieses Feld nicht leer bleiben. Bei einer Änderung wird automatisch das Feld "App-Name" ebenfalls geändert. |
| App-Name | In diesem Feld wird der Name angegeben, unter dem die App erstellt und später veröffentlicht werden soll. Der App-Name wird durch die Benennung eines Herausgebers automatisch vorbelegt, kann jedoch manuell abgeändert werden. Für die Erstellung einer App darf dieses Feld nicht leer bleiben. |
| App-Id | Jede App, die in Microsoft Dynamics 365 Business Central1 zum Einsatz kommt, wird durch eine eindeutige Identifizierung gekennzeichnet. Dies ist die so genannte App-Id. Diese besteht aus einem GUID-String, welcher bei der Initialisierung der Einrichtung automatisch vorbelegt wird. Sollte die Vergabe einer abweichenden App-Id gewünscht sein, so kann entweder ein gültiger GUID-Text in diesem Feld angegeben oder über die Aktion "Neue App-ID generieren" automatisch die App-Id ausgetauscht werden. |
Hinweis
Es ist zu berücksichtigen, dass durch die Änderung der App-Id eine bereits im Vorfeld veröffentlichte App nicht mehr aktualisiert werden kann, sondern stattdessen eine neue separate App installiert wird.
Inforegister Objektnummernkreis#
Das "Inforegister Objektnummernkreis" beinhaltet die Angabe des Objektnummernkreises, in dem die API-Pages erstellt werden sollen. Der hier gewählte Nummernbereich muss mit anderen EntwicklerInnen oder eventuellen Partnern so abgestimmt werden, dass es nicht zu einer Überschneidung der Objektnummern kommt. Es gilt zu beachten, dass für kundenindividuelle Apps seitens der Lizenzbedingungen von Microsoft Dynamics 365 Business Central1 generell nur der Nummernbereich von 50.000 bis 99.999 freigegeben ist.
Hinweis
Gegebenenfalls ist für die Nutzung der Objekte in einer OnPremise-Umgebung die eingesetzte Lizenz zu erweitern. Unter Umständen müssen hierzu sogar neue Objekte erworben werden.
Diese Notwendigkeit ist durch die Lizenzbedingungen von Microsoft Dynamics 365 Business Central1 vorgegeben und liegt weder in der Hand der KUMAVISION AG noch kann es von dieser beeinflusst werden.
| Feld | Beschreibung |
|---|---|
| Von Objekt-ID | Geben Sie in diesem Feld die Startnummer für neue Objekte an. Es kann eine Startnummer zwischen den erlaubten Werten von 50.000 - 99.999 angegeben werden. Als Standardwert wird bei der Initialisierung der Einrichtung die Nummer 60.000 verwendet. Bitte beachten Sie, dass der Wert des Feldes "Von Objekt-ID" geringer sein muss als der Wert des Feldes "Bis Objekt-ID". Sofern der Nummernbereich der App geändert wird und bereits API-Pages hinterlegt sind, so werden diese automatisch einer Renummerierung unterzogen. |
| Bis Objekt-ID | Geben Sie in diesem Feld die Endnummer für neue Objekte an. Es kann eine Endnummer zwischen den erlaubten Werten von 50.000 - 99.999 angegeben werden. Als Standardwert wird bei der Initialisierung der Einrichtung die Nummer 60.999 verwendet. Bitte beachten Sie, dass der Wert des Feldes "Von Objekt-ID" geringer sein muss als der Wert des Feldes "Bis Objekt-ID". Sofern der Nummernbereich der App geändert wird und bereits API-Pages hinterlegt sind, so werden diese automatisch einer Renummerierung unterzogen. |
Inforegister Versionierung#
Im Inforegister "Versionierung" werden die vier Bestandteile (Major.Minor.Build.Revision) der App-Version dargestellt und können dort manuell beeinflusst werden. Generell muss hier kein Benutzereingriff erfolgen, da die Version mit Initialisierung der Einrichtung auf den kombinierten Wert 1.0.0.0 gesetzt und mit jeder App-Erstellung die Revision automatisch um den Wert 1 erhöht wird.
| Feld | Beschreibung |
|---|---|
| App Version - Major | Das Feld beinhaltet die Major-Version der zu erstellenden App. Bei Initialisierung wird der Wert auf "1" gesetzt und standardmäßig nicht automatisch verändert. Sofern eine andere Major-Version verwendet werden soll, kann an dieser Stelle ein Wert zwischen 0 und 999.999 angegeben werden. |
| App Version - Minor | Das Feld beinhaltet die Minor-Version der zu erstellenden App. Bei Initialisierung wird der Wert auf "0" gesetzt und standardmäßig nicht automatisch verändert. Sofern eine andere Minor-Version verwendet werden soll, kann an dieser Stelle ein Wert zwischen 0 und 999.999 angegeben werden. |
| App Version - Build | Das Feld beinhaltet die Build-Version der zu erstellenden App. Bei Initialisierung wird der Wert auf "0" gesetzt und standardmäßig nicht automatisch verändert. Sofern eine andere Build-Version verwendet werden soll, kann an dieser Stelle ein Wert zwischen 0 und 999.999 angegeben werden. |
| App Version - Revision | Das Feld beinhaltet die Revision-Version der zu erstellenden App. Bei Initialisierung wird der Wert auf "0" gesetzt und standardmäßig bei jeder App-Erstellung um den Wert 1 hochgezählt. Sofern eine andere Revision-Version verwendet werden soll, kann an dieser Stelle ein Wert zwischen 0 und 999.999 angegeben werden. |
Aktionen im Menüband#
API Pages#
Damit eine App erstellt werden kann, muss mindestens eine aktivierte API Page als auszugebendes Objekt hinterlegt sein. Über diese Aktion erfolgt eine Weiterleitung auf die Übersicht der API Pages, von der ausgehend neue API Pages erstellt oder bestehende API Pages kopiert werden können. Weitere Details zur Erstellung und Pflege von API Pages können dem Kapitel API Page entnommen werden.
Quellpaket erstellen & herunterladen#
Die Aktion "Quellpaket erstellen & herunterladen" kann verwendet werden, um einen Projektordner für die Weiterverarbeitung in Visual Studio Code durch einen Entwickler bereitzustellen. Voraussetzung dafür ist, dass neben den benötigten Angaben in der API Page Creator Einrichtung mindestens eine aktivierte API Page vorliegt. Bei Auswahl dieser Aktion wird für jede aktivierte API Page ein AL-Objekt in einem Ordner src erstellt. Zusätzlich werden die Dateien app.json mit allen grundlegenden Informationen zur zu erstellenden App, sowie eine launch.json mit Informationen zur Veröffentlichung der App erstellt. Alle Dateien werden gemeinsam in ein Zip-Archiv verpackt und heruntergeladen.
Wird dieses Paket an einen Entwickler weitergegeben, so kann dieser den entpackten Ordner in Visual Studio Code öffnen, die App bei Bedarf mit weiteren Objekten oder Anpassungen anreichern und schließlich in eine Business Central Umgebung veröffentlichen.
Erstellen & Herunterladen der kompilierten App#
Die Aktion "Erstellen & Herunterladen der kompilierten App" wird verwendet, um eine gebrauchsfertige App-Datei erstellen zu lassen, die im Anschluss direkt in eine Umgebung veröffentlicht werden kann. Anstatt eines Zip-Archives mit den Quelldateien wird hierbei eine App-Datei erstellt, die alle benötigten Inhalte aufweist, um durch einen Administrator in Microsoft Dynamics 365 Business Central1 veröffentlicht und installiert zu werden.
Erstellen & Installieren der kompilierten App#
Die Aktion "Erstellen & Installieren der kompilierten App" ist nur in einer SaaS-Instanz von Microsoft Dynamics 365 Business Central1 aktiviert und erlaubt es, eine komplette gebrauchsfertige App-Datei mit den API-Pages zu erstellen und diese automatisch im Hintergrund hochladen und veröffentlichen zu lassen. Dieser Veröffentlichungsprozess kann einige Minuten dauern, jedoch ist bei dieser Aktion kein weiterer manueller Arbeitsschritt für die Veröffentlichung und Intallation der App auszuführen. Vielmehr werden die Schritte automatisch im Hintergrund ausgeführt und die API-Pages stehen umgehend nach Veröffentlichung zur Verwendung bereit.
API Page#
Eine API Page spiegelt ein eindeutiges Objekt in der späteren App wider, das als eigenständige Entität bereitgestellt werden soll. Prinzipiell können beliebig viele API Pages an dieser Stelle erfasst werden. Die Anzahl wird lediglich durch die Angabe und Verfügbarkeit eines gültigen Objektnummernbereiches begrenzt.
Inforegister Allgemein#
| Feld | Beschreibung |
|---|---|
| Code | Das Feld beinhaltet einen eindeutigen Code, der die API-Page beschreibt. Durch die Verwendung eines Codes als eindeutiges Unterscheidungskriterium anstatt der Tabellennummer ist es möglich, bei Bedarf verschiedene API Pages für ein und dieselbe Tabelle zu erstellen. Dies kann z.B. bei Änderungen aufgrund neuer Versionen oder für Testszenarien hilfreich sein. |
| Tabellen-ID | Das Feld gibt die zu Grunde liegende Tabelle an, die für die Bereitstellung der API Page verwendet werden soll. Bei der Auswahl der Tabelle wird geprüft, ob diese als Obsolete oder Removed gekennzeichnet ist. Des Weiteren werden nach Auswahl einer gültigen Tabelle die Werte in den Feldern "Tabellenbezeichnung", "Entitätsname" sowie "Entitätsgruppenname" automatisch vorbelegt. |
| Tabellenbezeichnung | Das Feld beinhaltet die Bezeichnung der Tabelle und dient lediglich der Information. Das Feld ist durch BenutzerInnen nicht änderbar. |
| API-Gruppe | Das Feld beinhaltet den Wert, der in dem späteren API-Objekt als APIGroup-Eigenschaft übernommen werden soll und für eine leichtere Navigation der Inhalte als Gruppierungselement dient. Der Standardwert für dieses Feld ist custom. Der Inhalt dieses Feldes sollte gemäß CodeCop Warning AA0101 in einem Camel-Case Format vorliegen, um den Microsoft REST API Guidelines zu entsprechen. |
| Entitätsname | Über den Entitätsnamen wird bei Verwendung der API ein Entitätstyp im Singular definiert. Der Inhalt dieses Feldes sollte gemäß CodeCop Warning AA0101 in einem Camel-Case Format vorliegen, um den Microsoft REST API Guidelines zu entsprechen. Nach Angabe einer "Tabellennr." wird automatisch ein Entitätsname im korrekten Format basierend auf dem Tabellennamen (nicht -bezeichnung) vorgeschlagen. |
| Entitätsgruppenname | Über den Entitätsgruppennamen wird bei Verwendung der API ein Entitätstyp im Plural definiert. Der Inhalt dieses Feldes sollte gemäß CodeCop Warning AA0101 in einem Camel-Case Format vorliegen, um den Microsoft REST API Guidelines zu entsprechen. Nach Angabe einer "Tabellennr." wird automatisch ein Entitätsgruppenname im korrekten Format basierend auf dem Tabellennamen (nicht -bezeichnung) vorgeschlagen. |
| Version | Das Feld beinhaltet die Version der API und ist nicht zu verwechseln mit der App-Version, die aufgrund der Einstellungen in der API Page Creator Einrichtung festgelegt wird. Bei der Neuanlage einer API Page erhält diese automatisch die Version v1.0. Gemäß der Beschreibung des Comiler Error AL0422 kann als gültige Version nur der Wert beta oder eine Versionierung nach dem Schema vX.Y verwendet werden, wobei X und Y jeweils positive Ganzzahlen repräsentieren. |
| Aktiviert | Über das Feld wird festgehalten, ob die vorliegende API-Page aktiviert werden soll und damit bei der nächsten Bereitstellung einer App-Version berücksichtigt wird. Eine Änderung der API-Page Konfiguration kann nur erfolgen, wenn das Feld Aktiviert ausgeschaltet wird. Nach erfolgter Anpassung sollte das Feld wiederum eingeschaltet werden, so dass interne Prüfungen der Konfiguration durchgeführt werden und die API PAge für die nächste App-Erstellung vorgesehen wird. |
Inforegister API Page Zeilen#
Über das Inforegister "API Page Zeilen" werden die einzelnen Felder definiert, die in der API-Entität zur Auswahl angeboten werden sollen. Alle hier genannten Felder können durch die nutzende Anwendung konsumiert werden. Die Auswahl von Feldern erfolgt über die interne Fields-Tabelle und beinhaltet somit alle verfügbaren Felder der Tabelle unabhängig von der jeweilig eingesetzten App. Felder, die einen Obsolete-Status von Pending oder Removed aufweisen, werden in der Auswahl nicht mehr angezeigt. Sollten solche Felder bereits in den Zeilen verwendet werden, so werden diese entsprechend hervorgehoben und sollten aus der Liste der "API Page Zeilen" entfernt werden.
Um neue Felder hinzuzufügen, kann entweder die AssistEdit-Funktion einer Zeile oder die Aktion "Felder hinzufügen" verwendet werden. In beiden Fällen können sowohl einzelne, aber auch beliebig viele selektierte Felder gleichzeitig eingefügt werden.
| Feld | Beschreibung |
|---|---|
| Feld-ID | Das Feld beinhaltet die eindeutige Nummer des jeweiligen Feldes in der Tabelle. Über die AssistEdit-Funktionalität des Feldes kann die Feldauswahl geöffnet werden, um ein oder mehrere Felder für die Übernahme in die "API Page Zeilen" auszuwählen. |
| Feldbezeichnung | Das Feld beinhaltet die Bezeichnung des ausgewählten Feldes und dient lediglich der Information. Das Feld ist durch BenutzerInnen nicht änderbar. |
| API Feldname | Das Feld beinhaltet den Wert, der in dem späteren API-Objekt als Feldeigenschaft übernommen werden soll. Der Inhalt dieses Feldes wird nach der Definition einer "Feld-ID" automatisch gesetzt. Basis dafür ist der Feldname (nicht die Feldbezeichnung), der automatsisch in ein Camel-Case-Format übertragen wird. Der Inhalt dieses Feldes sollte gemäß CodeCop Warning AA0101 in einem Camel-Case Format vorliegen, um den Microsoft REST API Guidelines zu entsprechen. Bei Bedarf kann der "API Feldname" manuell abgeändert werden. Hier sollten jedoch immer die genannten Guidelines berücksichtigt werden. |
Aktionen im Menüband#
API Page kopieren#
Über die Aktion "API Page kopieren" kann zu einer bereits bestehenden API Page ein Duplikat erstellt werden. Nach Auswahl der Aktion folgt ein Abfragefenster, in dem ein neuer, eindeutiger "API-Page Code" angegeben werden muss. Des Weiteren werden in diesem Fenster die Felder "Neuer Entitätsname", "Neuer Entitätsgruppenname" und "Neue Version" angezeigt, die mit den Daten der ursprünglichen API-Page vorbefüllt sind und hier abgeändert werden können. Über den Schalter "API Page Zeilen kopieren" kann zudem festgelegt werden, ob die API Page Zeilen der zu Grunde liegenden API-Page ebenfalls in die neue API-Page kopiert werden sollen.
AL-Objekt der API Page erstellen#
Die Aktion "AL-Objekt der API Page erstellen" erstellt auf Basis der aktuell angezeigten API-Page ein AL-Objekt, das an einen Entwickler zur Berücksichtigung in einer eigenständiugen App-Entwicklung weitergegeben werden kann. Die erzeugte AL-Datei wird automatisch heruntergeladen.