OpenAPI — generischer REST-Konnektor

Generischer REST-Konnektor, der Endpunkte, Wrapper-Schlüssel und Datentypen direkt aus einer OpenAPI-Spezifikation ableitet.

Der OpenAPI-Konnektor verbindet die DataBridge mit einer beliebigen REST-API, für die eine OpenAPI-Spezifikation (JSON oder YAML) existiert. Anders als bei den übrigen HTTP- Konnektoren werden Pfade, Wrapper-Schlüssel ({"clients": [...]} vs. {"client": {...}}) und Feldtypen nicht pro Ressource fest verdrahtet, sondern zur Laufzeit aus der Spezifikation aufgelöst. Ein Mapping muss dafür lediglich SourceTable/TargetTable auf den Ressourcennamen setzen (z. B. clients).

Eigenschaft	Wert
Lesen	✅ unterstützt
Schreiben (Create/Update)	✅ unterstützt
Löschen	✅ unterstützt
Aktionsaufrufe (InvokeAction)	✅ unterstützt
Job-Filter	⚠️ wird als Query-String an die Liste-Anfrage angehängt (kein `$filter`-Standard, API-abhängig)
Status	In Entwicklung / Preview

Status: in Entwicklung

Der Konnektor befindet sich aktuell noch in aktiver Entwicklung. Insbesondere die Auflösung der OpenAPI-Spezifikation lädt im aktuellen Codestand (OpenApiConnector.GetOpenApiDocument) eine lokale Testdatei von einer festen Pfadangabe, nicht den über openApiSpecUrl konfigurierten Endpunkt. Vor einem produktiven Einsatz ist das zu prüfen bzw. zu beheben.

Verbindungsparameter

{
  "baseUrl": "https://api.example.com",
  "openApiSpecUrl": "https://api.example.com/openapi.yaml",
  "clientId": "<Client-ID>",
  "clientSecret": "<Client-Secret>",
  "tenantId": "<Entra Tenant ID>",
  "scope": "<OAuth2-Scope>",
  "tokenUrl": "https://api.example.com/oauth/token",
  "apiKeyHeader": "X-API-Key",
  "apiKeyValue": "<API-Key>",
  "customHeaders": { "X-Custom-Header": "wert" },
  "nextLinkPath": "@odata.nextLink",
  "nextPagePath": "meta.next_page",
  "pageQueryParam": "page",
  "pageSizeQueryParam": "per_page",
  "updateMethod": "PATCH",
  "authenticateSpecRequest": false
}

Parameter	Pflicht	Standardwert	Beschreibung
`baseUrl`	✅	—	Basis-URL der API (ohne abschließenden Schrägstrich; wird bei Bedarf entfernt)
`openApiSpecUrl`	✅	—	URL zur OpenAPI-Spezifikation (JSON oder YAML)
`authenticateSpecRequest`	—	`false`	`true` = die Spezifikation wird mit denselben Zugangsdaten wie die API abgerufen; `false` = ohne Authentifizierung
`customHeaders`	—	(leer)	Zusätzliche statische Header, die bei jeder Anfrage mitgeschickt werden (z. B. Mandanten- oder Staging-Header)
`nextLinkPath`	—	(leer)	JSON-Pfad zur nächsten Seiten-URL in paginierten Antworten (z. B. `@odata.nextLink`). Gesetzt ⇒ URL-basierte Paginierung.
`nextPagePath`	—	(leer)	JSON-Pfad zur nächsten Seitennummer (z. B. `meta.next_page`). Erfordert zusätzlich `pageQueryParam`.
`pageQueryParam`	—	(leer)	Query-Parameter für die Seitennummer (z. B. `page`), zusammen mit `nextPagePath`
`pageSizeQueryParam`	—	(leer)	Query-Parameter für die Seitengröße (z. B. `per_page`); wenn gesetzt, wird `maxPageSize` darüber mitgeschickt
`updateMethod`	—	`PATCH`	HTTP-Methode für Aktualisierungen. `PUT` für APIs, die volle Ersetzung statt Teilaktualisierung erwarten.

Zusätzlich stehen die universellen Parameter maxPageSize, language, httpClientTimeoutSeconds, keyVaultUrl, logCreateRequests, logUpdateRequests und logReceivedData zur Verfügung — siehe Verbindungen.

Weder nextLinkPath noch nextPagePath gesetzt

Ohne eines der beiden Paginierungs-Felder liest der Konnektor nur die erste Seite der Liste-Antwort — es findet keine automatische Fortsetzung statt.

Authentifizierung

Der OpenAPI-Konnektor nutzt dieselbe Auswahllogik wie die übrigen HTTP-Konnektoren, erweitert um API-Key-Authentifizierung:

Methode	Aktivierung	Parameter
Basic Authentication	`userName` + `password` gesetzt	`userName`, `password`
OAuth2 Client Credentials	`clientId` + `clientSecret` + `tenantId` gesetzt (Vorgabe, wenn nichts anderes zutrifft)	`clientId`, `clientSecret`, `tenantId`, `scope`, optional `tokenUrl`
API Key	`apiKeyHeader` gesetzt	`apiKeyHeader`, `apiKeyValue`

{
  "apiKeyHeader": "X-Qonto-Staging-Token",
  "apiKeyValue": "<Token>"
}

tokenUrl — konfigurierbarer OAuth2-Endpunkt

Bei den übrigen HTTP-Konnektoren (D365BC, D365CE, D365NAV) ist der OAuth2-Token-Endpunkt fest auf den Microsoft-Login-Endpunkt eingestellt. Der OpenAPI-Konnektor führt zusätzlich den Parameter tokenUrl ein: Ist er gesetzt, wird der Token dort statt beim Microsoft-Standardendpunkt angefragt. Damit lassen sich auch APIs anbinden, deren OAuth2-Provider nicht Microsoft Entra ID ist. Bleibt tokenUrl leer, greift weiterhin der Microsoft-Standardendpunkt.

Zusätzliche statische Header (z. B. mandantenspezifische Tokens, die parallel zu OAuth2 oder API-Key benötigt werden) lassen sich unabhängig von der Authentifizierungsmethode über customHeaders mitgeben.

Tabellen- und Feldnamen

SourceTable / TargetTable: kurzer Ressourcenname, wie er in der OpenAPI-Spezifikation als letztes Pfadsegment vorkommt (z. B. clients für /v2/clients). Der Konnektor sucht in der Spezifikation nach einem Pfad, der auf /<Ressourcenname> endet und keine Parameter enthält; ein zugehöriger Einzeldatensatz-Pfad (/v2/clients/{id}) wird automatisch mitaufgelöst.
Alternativ kann auch der vollständige Pfad aus der Spezifikation eingetragen werden (Rückwärtskompatibilität).
SourceField / TargetField: Feldname aus dem JSON-Schema der Ressource. Verschachtelte Felder werden mit Punktnotation adressiert (z. B. phone.country_code).

Liste- und Einzeldatensatz-Antworten müssen nicht manuell konfiguriert werden: Wrapper- Schlüssel wie {"clients": [...]} oder {"client": {...}} werden aus der Spezifikation erkannt. Fehlen entsprechende Hinweise in der Spezifikation, erkennt der Konnektor ersatzweise die gebräuchlichen Muster value, data und results als Array-Wrapper.

Unterstützte TargetKey-Typen

Typ	Beschreibung
`PrimaryKey` / `Id`	Schlüsselwert wird direkt aus dem `TargetKey.KeyName`-Attribut der Nachricht gelesen und unverändert in die Item-URL eingesetzt
`CustomKey`	Ein oder mehrere Feld-Wert-Paare werden als Query-String (`key=wert&key2=wert2`) an die Liste-Anfrage angehängt; der Datensatz wird darüber gesucht
`Filter`	Wie `CustomKey`, zusätzlich wird `id` als besonderer `keyName`-Wert erkannt und dafür `message.Id` verwendet

Wird bei CustomKey/Filter mehr als ein Datensatz gefunden, bricht die Verarbeitung mit einem Fehler ab (Found more than 1 record).

Schreiben (Upsert)

Der Konnektor prüft vor jedem Schreibvorgang, ob bereits ein Zieldatensatz existiert (GetSingleRequest bei PrimaryKey/Id/CustomKey, ein gefilterter Liste-Abruf bei Filter). Existiert er, wird nur bei tatsächlicher Werteänderung ein Update ausgelöst — identische Werte führen zu keiner Anfrage.

Anlegen: POST auf den Collection-Pfad
Aktualisieren: PATCH (Vorgabe) oder PUT (updateMethod) auf den Item-Pfad
Anfrage-Body wird bei Bedarf automatisch in einen aus der Spezifikation abgeleiteten Wrapper-Schlüssel eingebettet (z. B. {"client": {...}}). Ein Job kann das über SpecialSettings gezielt abschalten:
```
{ "DoNotWrapRequestBody": true }
```
Ein 409 Conflict bei Anlegen oder Aktualisieren wird als transiente Ausnahme behandelt und über die Transitive-Queue erneut verarbeitet (siehe Architektur → Retry- und Fehlerverhalten).

Löschen

Anders als die SQL-Konnektoren unterstützt der OpenAPI-Konnektor Löschungen: Der Schlüssel wird wie beim Lookup aufgelöst, anschließend folgt ein DELETE auf den Item-Pfad.

InvokeAction — generische Aktionsaufrufe

Neben dem klassischen CRUD-Zyklus unterstützt die DataBridge seit dieser Version Aktions-Jobs: Ein Job mit Action = InvokeAction (technisch: jeder Wert, der nicht auf einen bekannten JobActionType passt) ruft einen benannten, nicht-CRUD-Endpunkt auf, statt einen Datensatz anzulegen oder zu ändern — z. B. POST /v2/client_invoices/{id}/send_by_einvoice.

Konfiguration:

Feld	Bedeutung
`Job.Action`	Name der Aktion (z. B. der OpenAPI-`operationId` oder ein sprechender Bezeichner) — beliebig, solange er nicht `NewUpdate`, `Delete`, `TimeStamp` oder `DeleteOnUpdate` entspricht
`TableMapping.TargetPath` + `TargetTable`	Ergeben zusammen den Aktionspfad, so wie er in der Spezifikation steht (z. B. `TargetPath = "v2/client_invoices/{id}"`, `TargetTable = "send_by_einvoice"`)
`FieldMapping` mit gesetztem `TargetField`	Optional; ergibt den JSON-Request-Body der Aktion

Ablauf:

Der Aktionspfad wird in der Spezifikation nachgeschlagen; die HTTP-Methode wird daraus übernommen (bevorzugt POST, sonst PUT/PATCH/DELETE — die erste im Pfad gefundene, nicht-GET-Methode).
Pfadparameter ({id} etc.) werden aus message.Id (Parametername id) bzw. aus message.Attributes aufgelöst; ein nicht auflösbarer Parameter erzeugt lediglich eine Warnung und bleibt im Pfad stehen.
Ist mindestens ein Zielfeld gemappt, wird daraus ein JSON-Body gebaut und mitgeschickt.
Bei einem ResponseJob wird die Antwort — über den aus der Spezifikation abgeleiteten Wrapper-Schlüssel entpackt — als neue Queue-Nachricht mit ActionCode = NewUpdate weitergereicht.

Ein fehlender Aktionspfad oder eine Antwort ohne 2xx-Statuscode brechen den Job mit einer Ausnahme ab.

Job-eigene Source-/Target-Pfade (statt nur Mapping-Tabelle)

(neu, alle Konnektoren betroffen — beim OpenAPI-Konnektor besonders relevant)

Ein Job kann eigene Felder Source und Target tragen, die den SourceTable/TargetTable der referenzierten Mapping-Zeilen überschreiben. Damit lässt sich ein und dasselbe Mapping für mehrere Ressourcen bzw. Aktionspfade wiederverwenden. Details: Jobs → Source und Target.

Änderungserkennung (Watermark)

Eigenschaft	Wert
Empfohlener WatermarkType	`datetime`
WatermarkField	Beliebiger JSON-Pfad im Antwortobjekt (z. B. `updated_at`), der bei jedem gelesenen Datensatz zu einem gültigen Zeitstempel ausgewertet werden kann

Der Watermark-Wert wird über job.WatermarkField als SelectToken-Pfad auf jedes gelesene JSON-Objekt angewendet. Der Filterausdruck (Job.Filter) wird — anders als bei D365BC/NAV — nicht in eine standardisierte Query-Syntax übersetzt, sondern unverändert als Query-String an die Liste-Anfrage angehängt; Aufbau und Platzhalter sind daher von der jeweiligen API abhängig.

EmbedChildren — eingebettete Kind-Datensätze

(Quell-Feature ist derzeit nur im D365CE-Connector implementiert, das Zielverhalten dazu liegt im OpenAPI-Konnektor)

Verweist ein Feld-Mapping über die SourceOperation EmbedChildren auf einen anderen Job, werden dessen Zeilen bereits beim Lesen in die Nachricht des Elterndatensatzes eingebettet. Beim Schreiben in eine OpenAPI-Zielressource baut der Konnektor daraus ein verschachteltes JSON-Array (z. B. Rechnungspositionen unter lines) und schreibt es als Teil der Elternanfrage — ohne Feld-für-Feld-Abgleich mit einem eventuell vorhandenen Array im Zieldatensatz. Details zur Quellseite: Architektur und D365CE.

Caching

OpenAPI-Dokument und aufgelöste Ressourcen-Metadaten (Pfade, Wrapper-Schlüssel, Schema) werden pro Prozess zwischengespeichert. Ein Neuladen der Spezifikation erfordert einen Neustart der Function App bzw. ein erneutes Kaltstart-Init.