Einrichtung und Konfiguration Universal REST API

Tags:

  4 Minuten Lesezeit  

Einrichtung

Um eine sichere Verbindung zwischen den Systemen aufbauen zu können, wird der Standard OpenID Connect verwendet. In Bezug auf Microsoft Dynamics 365 Business Central lautet das Stichwort hier “Service-to-Service” Authentication (S2S): https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/automation-apis-using-s2s-authentication

Somit sind grundsätzlich Tätigkeiten in drei Ebenen nötig.

flowchart TD
    classDef Aareon_blue fill:#051163,stroke:#051163,color:#FFFFFF,font-family:Segoe UI, Arial, Helvetica,sans-serif
    classDef Bright_blue fill:#086DFB,stroke:#086DFB,color:#FFFFFF,font-family:Segoe UI, Arial, Helvetica,sans-serif
    classDef Sand        fill:#F7F3F0,stroke:#F7F3F0,color:#081326,font-family:Segoe UI, Arial, Helvetica,sans-serif
    classDef Stone       fill:#EBE3DC,stroke:#EBE3DC,color:#081326,font-family:Segoe UI, Arial, Helvetica,sans-serif
    classDef Coral       fill:#FF7F62,stroke:#FF7F62,color:#081326,font-family:Segoe UI, Arial, Helvetica,sans-serif
    classDef Peach       fill:#FFD8CA,stroke:#FFD8CA,color:#081326,font-family:Segoe UI, Arial, Helvetica,sans-serif
    classDef Green       fill:#50B214,stroke:#50B214,color:#081326,font-family:Segoe UI, Arial, Helvetica,sans-serif
    classDef Light_green fill:#B9E99C,stroke:#B9E99C,color:#081326,font-family:Segoe UI, Arial, Helvetica,sans-serif
    classDef Baby_blue   fill:#A4CBFF,stroke:#A4CBFF,color:#081326,font-family:Segoe UI, Arial, Helvetica,sans-serif
    classDef Burgundy    fill:#550000,stroke:#550000,color:#FFFFFF,font-family:Segoe UI, Arial, Helvetica,sans-serif
    classDef Dark_green  fill:#2F630E,stroke:#2F630E,color:#FFFFFF,font-family:Segoe UI, Arial, Helvetica,sans-serif

    E[Microsoft Entra ID]:::Coral
    RP[RELion<br>Produktiv]:::Green
    RS[RELion<br>Sandbox]:::Green
    NSTP[Business Central Dienst<br>Produktiv]:::Bright_blue
    NSTS[Business Central Dienst<br>Sandbox]:::Bright_blue

    subgraph SGE["`**Kunde - Entra-Admin**`"]
        E
    end
    class SGE Peach

    subgraph SGR["`**Kunde - Super-User**`"]
        E --> RP
        E --> RS
    end
    class SGR Light_green

    subgraph SGNST["`**Aareon RELion - Dev-Ops**`"]
        RP --> NSTP
        RS --> NSTS
    end
    class SGNST Aareon_blue

  1. Registrieren Sie in Ihrem Entra ID-Tenant muss durch Ihren Entra-Admin eine zusätzliche Unternehmensanwendung je zugreifendem Programm registriert werden.

    1. Beispiel

      1. Eine Applikation für das RELion Consulting zur Einrichtungskontrolle
      2. Eine Applikation für das DMS
      3. Eine Applikation für das Vermietungsportal
      4. …

    2. Die entsprechende Anleitung zum Registrieren der Anwendung finden Sie hier: https://learn.microsoft.com/de-de/dynamics365/business-central/dev-itpro/administration/automation-apis-using-s2s-authentication#task-1-register-a-microsoft-entra-application-for-authentication-to-business-central

      1. In “Task 1” der Microsoft Dokumentation wird die Anwendung in Ihrem Entra ID Tenant registriert.
      2. Als API-Berechtigungen werden folgende Dynamics 365 Business Central Anwendungsberechtigungen benötigt
        1. API.ReadWrite.All
        2. Automation.ReadWrite.All
      3. Bitte teilen Sie uns Tenant ID, Client ID und Client Secret (zufallsgeneriertes Passwort, 40 Stellen) für die Applikation zur Einrichtungskontrolle durch das RELion Consulting über einen verschlüsselten Weg mit.

  2. Jede unter Punkt 1 angelegt Applikation muss durch Ihren RELion-Super-User jeweils in beiden Instanzen (Produktiv und Sandbox) auf der Seite Microsoft Entra-Anwendungen separat angelegt, aktiviert und berechtigt werden.

    1. Folgende Berechtigungssätze sind für die Ersteinrichtung sinnvoll.
      1. RE URA
      2. SUPER (DATA)
      3. D365 AUTOMATION
    2. Eine Einschränkung bzw. feinere Einrichtung kann und soll im Laufe der Anbindung des jeweiligen zugreifenden Programms vorgenommen werden.
    3. Bitte teilen Sie uns die grundlegende ODataV4-URL der jeweiligen Instanz mit. Sie finden diese auf der Seite Webdienst und sieht zum Beispiel so aus: https://kunde.dynamicstocloud.com:1103/ST-123456

  3. Von Seiten Aareon RELion wird die Installation der Universal REST API-Extension vorgenommen und die notwendigen Einstellungen an den beiden Instanzen (Produktiv und Sandbox) vorgenommen.

Konfiguration

Hier werden alle Einrichtungen mit deren Verhalten beschrieben. Die Obsolete Einrichtungen werden zwar in der Einrichtungsoberfläche noch angezeigt, haben aber keine Auswirkung mehr und werden hier auch nicht mehr näher beschrieben.

Es können pro Mandant verschiedene Einrichtungen vorgenommen werden. Wenn der von uns empfohlene Standard genutzt werden möchte, dann brauchen die Einstellungen nicht angepasst zu werden.

Empfehlung: In allen Mandanten die gleiche Einrichtung zu verwenden.

Code

Code – Feld, über den Wert dieses Feldes kann bei einem Request eine bestimmte Konfiguration gewählt werden. Die Konfiguration mit einem leeren Code Feld ist die Konfiguration, die als Standard zur Anwendung kommt, wenn keine Konfiguration bei einem Request enthalten ist.

Debug

Aktivert das Dugging. Folgende Einstellungen sind hier möglich:

  • Off: kein Logging von eingehenden Aufrufen und Antworten
  • Full: Logging von Aufrufe und Antworten
  • Request: nur Logging der Aufrufe
  • Response: nur Logging der Antworten

ACHTUNG: Nicht unnötg aktivieren, da hierdurch zum einem Daten und damit Speicher belegt wird und zum anderen dadurch die Performance eines Request deutlich vermindert wird.

Response Format

Es kann zwischen den Standard Formaten 0,1,2 und 9 gewählt werden. Es kann nur ein Responseformat für alle Datentypen gewählt werden. Die unterschiede zwischen den Format Typen kann der Microsoft Doku entnommen werden: https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-format-property

Wir empfehlen das Format 9 zu verwenden, da es Regions und Sprachunabhängig immer Eindeutig ist. Auch wenn Microsoft es als “XML” Format bezeichnet, wird selbstverständlich ein JSON zurück geliefert. Mit XML-Format ist gemeint, dass es so formatiert wird, dass es auch in einer XML-Datei genau so formatiert ist.
Beispiel: es gibt bei Zahlen keinen Tausender Trennzeichen und das “Komma” ist immer in allen Sprachen ein “Punkt”.

Enum Possible Values

Manchmal benötigt ein System, die Information, welche Options/Enum-Werte möglich sind bei einem Feld. Wird dies Einstellung auf true gesetzt, so wird das Response Object immer so erweitert, das zu einem Enum/Option auch die dazu gehörigen Möglichkeiten geliefert werden.


Empfehlung: Diese Einstellung nur in der Entwicklung auf true lassen. Eventuel ein Setup “DEV” anlegen, wo dieser Wert auch true ist. Ansonsten werden hier sonst unnötige Datenmengen im Trafik erzeugt werden.

Number of Entities To Read

Gibt die maximale Anzahl an Datensätzen an, die in einem request übertragen werden sollen. Dieser Wert kann im Request über den “top” Parameter übersteuert werden.

Field Name Replace From/To Char

Mit diesen beiden Werten kann ein allgemeines Suchen und Ersetzen im Feldnamen umgesetzt werden. Wenn also Als Beispiel die Leerzeichen durch ein Unterstrich im Feldnamen ersetzt ode rganz entfernt werden sollen.

Zuletzt geändert April 2, 2025: Merged PR 4864: doku-projektentwicklung (a9ad810)