Eigene Business-Central-API-Page in AL erstellen und testen

Grundlagen-Tutorial mit Schritt-für-Schritt-Beispielen

1. Was ist eine API-Page in Business Central?

Eine API-Page stellt Daten einer Business-Central-Tabelle über einen versionierten HTTP-Endpunkt bereit. Sie ist keine klassische Benutzeroberfläche. Der API-Vertrag legt Entitätsnamen, Felder und erlaubte Lese- oder Schreiboperationen fest. Für vorhandene Standardentitäten solltest du zuerst die Business Central API v2.0 prüfen.

2. Voraussetzungen

Du brauchst eine unterstützte Business-Central-Sandbox, Visual Studio Code mit AL Language Extension, passende Symbole und Berechtigungen zum Veröffentlichen einer Extension. Verwende zum Testen ausschließlich anonymisierte oder eigens erstellte Beispieldatensätze.

3. API-Page anlegen

Im Beispiel stellen wir nur Artikelstammdaten bereit. Das AL-Objekt ist als Lernbeispiel gedacht und verwendet einen eigenen API-Publisher, eine Gruppe und Version. Die Datenquelle ist die Standardtabelle Item. Feldnamen und unterstützte Konfiguration solltest du mit deiner BC-Version abgleichen.

page 50120 "Demo Items API"
{
    PageType = API;
    APIPublisher = 'maxdev';
    APIGroup = 'tutorial';
    APIVersion = 'v1.0';
    EntityName = 'demoItem';
    EntitySetName = 'demoItems';
    SourceTable = Item;
    ODataKeyFields = SystemId;
    DelayedInsert = true;
    InsertAllowed = false;
    ModifyAllowed = false;
    DeleteAllowed = false;

    layout
    {
        area(content)
        {
            repeater(General)
            {
                field(id; Rec.SystemId) { }
                field(number; Rec."No.") { }
                field(displayName; Rec.Description) { }
            }
        }
    }
}

4. Warum ODataKeyFields und SystemId wichtig sind

Die SystemId ist eine persistente GUID, die Datensätze identifiziert. Sie ist für API-Adressen besser geeignet als eine fachliche Artikelnummer, die organisatorisch anders behandelt werden kann. Mit ODataKeyFields legst du den API-Schlüssel fest.

5. Extension veröffentlichen und URL bilden

Nach dem Publish in der Sandbox folgt die URL dem Muster: /api/{publisher}/{group}/{version}/companies({companyId})/{entitySetName}. Mandant und Environment stehen davor in der Business-Central-Dienstadresse. Die API-Page wird über ihre Metadaten bereitgestellt; normalerweise ist kein manueller Eintrag auf der Webdienstseite nötig.

6. Mit OAuth2 authentifizieren

Für Business Central Online brauchst du ein von Microsoft Entra ID ausgestelltes Access Token für Business Central, nicht für Microsoft Graph. Die Berechtigungen der aufrufenden App und die Zuordnung in Business Central müssen passen. Teile keine Client-Secrets oder echten Access Tokens in Tutorials.

7. GET-Anfrage testen

Teste zunächst den Abruf der Liste und anschließend einen einzelnen Datensatz per SystemId. Ein 200-Status beweist einen erfolgreichen API-Aufruf, aber nicht automatisch, dass ein Client alle für eine bestimmte Geschäftsoperation nötigen Daten erhält.

GET https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/api/maxdev/tutorial/v1.0/companies({companyId})/demoItems
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

8. Schreibende Zugriffe absichern

Soll die API ausschließlich lesen, halte sie auch technisch schreibgeschützt. Für Schreiboperationen benötigst du passende Tabellenvalidierung, Berechtigungen und klare Geschäftsregeln. Ein direkter Datenbankzugriff darf nicht die Business-Central-Buchungslogik umgehen.

9. 401, 403 und 404 verstehen

401 deutet auf fehlende oder ungültige Authentifizierung, 403 auf unzureichende Berechtigung und 404 auf nicht gefundene oder nicht sichtbare Ressourcen beziehungsweise einen falschen Pfad. Bei unerwarteten Fehlern überprüfe Environment, CompanyId, Namespace und den Namen des EntitySets.

10. Übungen und nächste Schritte

Ergänze eine zweite lesbare Spalte, veröffentliche erneut in der Sandbox und prüfe das JSON. Beschränke die Abfrage auf einzelne Artikel. Anschließend kannst du lernen, wie eine C#-Anwendung per OAuth auf diese API zugreift.

Documentation

Microsoft: API PageType · Business Central API