Neue APIs erstellen

Abgeschlossen

Sie können eine Seite oder ein Abfrage-Objekt anfertigen, um eine neue API in Business Central zu erstellen. Stellen Sie je nach Objekttyp die Eigenschaft PageType oder QueryType auf API ein. Mit den regulären OData-Webdiensten können Sie eine vorhandene Seite oder Abfrage als Webdienst veröffentlichen. Die Folge ist, dass alle Felder, die auf Ihrer Kartenseite definiert sind, in Ihrem Webdienst verfügbar sind. Wenn Sie ein Feld benötigen, das nicht Teil der vorhandenen Seite war, müssen Sie dieses Feld zur Seite hinzufügen. Dieses Feld steht dann aber auch allen Benutzern in der Business Central-Anwendung zur Verfügung.

Mit der API können Sie separate Seiten erstellen, die in der Client-Anwendung nicht angefordert werden können und nur in API-Aufrufen verwendet werden können. Sie müssen keine API-Seite wie bei normalen OData-Webdiensten veröffentlichen. Sie müssen nur eine API-Seite erstellen, die Teil Ihrer Erweiterung ist. Stellen Sie Ihre Erweiterung bereit, und dann ist Ihre API-Seite verfügbar.

Verwenden Sie zum Erstellen einer API-Seite den Ausschnitt tpage, und setzen Sie dann die Eigenschaft PageType auf API. Wenn Sie den PageType in API ändern, stellen Sie auch einige der folgenden Eigenschaften ein:

• APIVersion – Die Version Ihrer API. Sie können mehrere Versionen derselben API erstellen. Jede Version ist ein separates Objekt mit einer eigenen Objektnummer. Sie können jedoch mehrere Versionen gleichzeitig unterstützen. Auf diese Weise müssen andere Dienste, die auf Ihrem API-Dienst basieren, nicht direkt geändert werden, wenn Ihr Dienst ein neues Feld hinzufügt oder die Struktur der API ändert. Die Version kann entweder den Wert Beta oder v1.0, v1.1, v1.2, v2.0 usw. haben. Sie müssen den Buchstaben v ausdrücklich angeben. Sie können nur eine Haupt‑ und eine Nebenversion angeben, keine Buildversionsnummer. Zum Beispiel ist „v1.1.3“ kein gültiger Wert.

• APIPublisher – Der Name Ihres Unternehmens, das die APIs erstellt hat. Dieser Wert wird in der URL verwendet, um eine Verbindung zur API herzustellen und alle APIs desselben Herausgebers zu gruppieren.

• APIGroup – Eine Gruppe, mit der eine Reihe von APIs logisch gruppiert werden. Dieser Wert wird auch in der URL verwendet, um eine Verbindung zur API herzustellen.

• EntityName – Der singuläre Wert für die Entität, die von der API zurückgegeben wird (Debitor, Artikel, Auto, Kreditor, Künstler, Film usw.).

• EntitySetName – Dieser Parameter ist der Pluralwert für die Entität, die von der API zurückgegeben wird (Debitoren, Artikel, Autos, Kreditoren, Künstler, Filme usw.).

• DelayedInsert – Dieser Wert sollte für API-Seiten immer auf true eingestellt sein. Diese Einstellung stellt sicher, dass die Werte nur in die Datenbank eingefügt werden, wenn alle Werte aus der API-Anforderung bereitgestellt wurden.

• ODataKeyFields – Diese Eigenschaft gibt an, welches Feld als Schlüssel verwendet wird. Wenn Sie einen bestimmten Datensatz anfordern, können Sie diese Eigenschaft festlegen, um anzugeben, in welchem Feld Sie nach diesem bestimmten Datensatz suchen. Microsoft erstellt ein Feld SystemId, das für jede Tabelle verfügbar ist, auch für Ihre eigenen Tabellen, ohne dass Sie es selbst erstellen müssen. Das Feld SystemId identifiziert einen Datensatz eindeutig und ändert sich im Laufe der Zeit nie, selbst wenn Sie den Primärschlüssel aktualisieren. Wir empfehlen die Verwendung des Felds SystemId als „ODataKeyFields“.

Das folgende Codebeispiel zeigt die Struktur einer benutzerdefinierten API-Seite, die die Debitorentabelle verwendet.

page 50115 "My Custom Customer API"

{
    PageType = API;
    APIVersion = 'v1.0';
    APIPublisher = 'mycompany';
    APIGroup = 'sales';
    EntityName = 'mycustomer';
    EntitySetName = 'mycustomers';
    DelayedInsert = true;
    SourceTable = Customer;
    ODataKeyFields = SystemId;

    layout
    {
        area(Content)
        {
            repeater(GroupName)
            {
                field(id;SystemId)
                {
                    ApplicationArea = All;
                }
                field(name;Name)
                {
                    ApplicationArea = All;
                }
                field(email;"E-Mail")
                {
                    ApplicationArea = All;
                }
            }
        }
    }
}

Die Namen aller Felder sollten mit Camel-Case-Schreibweise (camelCase) erstellt werden und dürfen keine Sonderzeichen enthalten.

Die URL für diese API basiert auf den Eigenschaften APIPublisher, APIVersion, APIGroup und EntitySetName.

Base URL: https://api.businesscentral.dynamics.com/v2.0/<tenant>/<environment>

/api/<apipublisher>/<apigroup>/<apiversion>/<entitysetname>

In diesem Beispiel würde dieser URI wie folgt aussehen.

/api/mycompany/sales/v1.0/mycustomers