3.2.3.8. Web-API

Steuerungsabfrage

• Dies ist ein optionales Eingabefeld, um eine SQL-Abfrage auf der OCT-Datenbank auszuführen.

• Für jede Ergebniszeile der Steuerungsabfrage wird die HTTP-Anfrage ausgeführt.

• Die Ergebnisfelder der Steuerungsabfrage können als Variablen in der URL, im Header, im Body und im Namen der Zieltabelle im SQL-Befehl verwendet werden.

• Jede Spalte der Steuerungsabfrage steht als {<Spaltenname>}-Platzhalter in der Anfrage (URL, Header, Body), in Zieltabellenfeldern, im Namen der Zieltabelle sowie in den zusätzlichen SQL-Befehlen zur Verfügung.

Icon “SQL-Editor-Dialog öffnen”

• Über das Icon kann ein separater Dialog mit einem vergrößerten SQL-Editor geöffnet werden.

Icon “Lupe”

• Mit einem Linksklick auf das “Suche”-Icon öffnet sich ein Dialog, der eine Übersicht der Steuerungsabfrage anzeigt.

• Schwebt man mit der Maus über dem Icon , wird ein Tooltip angezeigt.

HTTP-Methode

• Es öffnet sich ein Drop-down, in welchem folgende Optionen verfügbar sind:

  • GET

  • POST

  • PUT

  • DELETE

  • PATCH

• Wählen Sie die HTTP-Methode, die für Ihre API-Anfrage relevant ist.

• Nur bei GET müssen Extraktionsfelder ausgewählt sowie eine Zieltabelle angegeben werden.

URL

• Es muss die URL eingegeben werden, an welche die API-Anfrage gesendet werden soll.

Header

• Die Eingabe ist optional.

• Über den Button “Header hinzufügen” können mehrere Header hinzugefügt werden. Dafür muss ein Header-Name und ein Header-Wert eingegeben werden.

• Üblicherweise werden im Header z.B. Informationen für die Authentifizierung hinterlegt.

• Über das “X” rechts neben dem Eingabefeld für den Wert, kann eine Zeile des Headers gelöscht werden.

Body

• Die Eingabe ist optional, weshalb “Kein Body” standardmäßig ausgewählt ist.

• Das Format der Daten ist frei wählbar (z.B. JSON, XML, Text, Form URL kodiert).

• Bei Auswahl eines Datenformats öffnet sich bei “JSON”, “XML” und “Text” ein Editorfeld, in welchem zusätzliche Daten stehen können, die mit der API-Anfrage gesendet werden.

• Über das Icon “Editor vergrößern” kann ein separater Dialog mit einem vergrößerten Editor geöffnet werden.

• Bei Auswahl von “URL-kodierte Formulardaten” können über den Button “Feld hinzufügen” Schlüssel-Wert-Paare eingegeben werden.

• Über das “X” rechts neben dem Eingabefeld für den Wert, kann eine Zeile gelöscht werden.

Web API Authentifizierung

• In einem Drop-down kann eine Authentifizierungsmethode (Datenquellen-ID/Name der Datenquelle) ausgewählt werden, die zuvor als Datenquelle vom Typ „Web API Authentifizierung“ angelegt wurde.

• Bleibt das Eingabefeld leer, erfolgt keine Authentifizierung.

Menüleiste

Icon “Felder neu laden”

• Die Quellfelder werden neu geladen bzw. neu aus der Antwort der Anfrage gelesen.

Icon “Alle auswählen”

• Mit einem Linksklick auf das Icon werden alle Extraktionsfelder ausgewählt bzw. alle Checkboxen in der Spalte “Aktiv” aktiviert.

Icon “Alle abwählen”

• Mit einem Linksklick auf das Icon werden alle Extraktionsfelder abgewählt bzw. alle Checkboxen in der Spalte “Aktiv” deaktiviert.

Suchfeld

• Über das Suchfeld kann gezielt nach bestimmten Inhalten bzw. Feldern der API-Antwort in der Spalte “Quellfeld” gesucht werden.

Tabelle - Spaltenüberschriften

Aktiv

• Über diese Spalte mit Checkboxen können einzelne Felder für den Transfer in die Zieltabelle ausgewählt werden.

Quellfeld

• Zeigt den Namen und ggf. den Pfad des Quellfelds aus der API-Anfrage an.

• Beispiel: response.address.street - Pfad: response.address / Feld: street

Zielspalte

• Eingabefeld für den Namen des Felds in der Zieltabelle

SQL-Typ

• Es können Spaltentypen für Spalten der Zieltabelle definiert werden.

• Folgende SQL Server Datentypen werden unterstützt:

  • NVARCHAR(255) - Standardwert für das Extraktionsfeld

  • NVARCHAR(4000)

  • NVARCHAR(MAX)

  • INT

  • BIGINT

  • DECIMAL(18,6)

  • FLOAT

  • MONEY

  • BIT

  • DATE

  • DATETIME

  • UNIQUEIDENTIFIER

Standardwert

• Eingabefeld für einen Standardwert für das Zielfeld, falls der Wert im Response-Objekt nicht vorhanden oder leer ist.

• Variablen aus der Steuerungsabfrage können verwendet werden.

Vorschau

• Vorschau des Feldwerts aus dem ersten zurückgegebenen Datensatz

• Es werden die ersten hundert Zeichen angezeigt.

Tabelle allgemein

Sortierfunktion

• Mit einem Linksklick neben die Spaltenüberschrift können die Angaben auf- oder absteigend bzw. alphabetisch sortiert werden.

Menüleiste

Icon “Feld hinzufügen”

• Über das Icon kann ein neues statisches Feld hinzugefügt werden.

Tabelle - Spaltenüberschriften

Aktiv

• Über diese Spalte mit Checkboxen können einzelne Felder für den Transfer in die Zieltabelle ausgewählt werden.

Spaltenname

• Eingabefeld für den Spaltennamen

SQL-Typ

• Es können Spaltentypen für Spalten der Zieltabelle definiert werden.

• Folgende Typen werden unterstützt:

  • NVARCHAR(255) - Standardwert für das Extraktionsfeld

  • NVARCHAR(4000)

  • NVARCHAR(MAX)

  • INT

  • BIGINT

  • DECIMAL(18,6)

  • FLOAT

  • MONEY

  • BIT

  • DATE

  • DATETIME

  • UNIQUEIDENTIFIER

Wert

• Es kann ein beliebiger fester Wert zugewiesen werden. Außerdem können Platzhalter aus der Steuerungsabfrage im Format {Feldname} verwendet werden.

Icon “Löschen”

• Über das Icon kann die Zeile gelöscht werden.

Menüleiste

Icon “Felder neu laden”

• Die Quellfelder werden neu geladen bzw. neu aus der Antwort der Anfrage gelesen.

Icon “Alle auswählen”

• Mit einem Linksklick auf das Icon werden alle Extraktionsfelder ausgewählt bzw. alle Checkboxen in der Spalte “Aktiv” aktiviert.

Icon “Alle abwählen”

• Mit einem Linksklick auf das Icon werden alle Extraktionsfelder abgewählt bzw. alle Checkboxen in der Spalte “Aktiv” deaktiviert.

Suchfeld

• Über das Suchfeld kann gezielt nach bestimmten Inhalten bzw. Feldern der API-Antwort in der Spalte “Quellfeld” gesucht werden.

Tabelle - Spaltenüberschriften

Aktiv

• Über diese Spalte mit Checkboxen können einzelne Felder für den Transfer in die Zieltabelle ausgewählt werden.

Quellfeld

• Zeigt den Namen und ggf. den Pfad des Quellfelds aus der API-Anfrage an.

• Beispiel: response.address.street - Pfad: response.address / Feld: street

Zielspalte

• Eingabefeld für den Namen des Felds in der Zieltabelle

SQL-Typ

• Es können Spaltentypen für Spalten der Zieltabelle definiert werden.

• Folgende SQL Server Datentypen werden unterstützt:

  • NVARCHAR(255) - Standardwert für das Extraktionsfeld

  • NVARCHAR(4000)

  • NVARCHAR(MAX)

  • INT

  • BIGINT

  • DECIMAL(18,6)

  • FLOAT

  • MONEY

  • BIT

  • DATE

  • DATETIME

  • UNIQUEIDENTIFIER

Standardwert

• Eingabefeld für einen Standardwert für das Zielfeld, falls der Wert im Response-Objekt nicht vorhanden oder leer ist.

• Variablen aus der Steuerungsabfrage können verwendet werden.

Vorschau

• Vorschau des Feldwerts aus dem ersten zurückgegebenen Datensatz

• Es werden die ersten hundert Zeichen angezeigt.

Tabelle allgemein

Sortierfunktion

• Mit einem Linksklick neben die Spaltenüberschrift können die Angaben auf- oder absteigend bzw. alphabetisch sortiert werden.

Menüleiste

Icon “Feld hinzufügen”

• Über das Icon kann ein neues statisches Feld hinzugefügt werden.

Tabelle - Spaltenüberschriften

Aktiv

• Über diese Spalte mit Checkboxen können einzelne Felder für den Transfer in die Zieltabelle ausgewählt werden.

Spaltenname

• Eingabefeld für den Spaltennamen

SQL-Typ

• Es können Spaltentypen für Spalten der Zieltabelle definiert werden.

• Folgende Typen werden unterstützt:

  • NVARCHAR(255) - Standardwert für das Extraktionsfeld

  • NVARCHAR(4000)

  • NVARCHAR(MAX)

  • INT

  • BIGINT

  • DECIMAL(18,6)

  • FLOAT

  • MONEY

  • BIT

  • DATE

  • DATETIME

  • UNIQUEIDENTIFIER

Wert

• Es kann ein beliebiger fester Wert zugewiesen werden. Außerdem können Platzhalter aus der Steuerungsabfrage im Format {Feldname} verwendet werden.

Icon “Löschen”

• Über das Icon kann die Zeile gelöscht werden.

Menüleiste

Icon “Felder neu laden”

• Die Quellfelder werden neu geladen bzw. neu aus der Antwort der Anfrage gelesen.

Icon “Alle auswählen”

• Mit einem Linksklick auf das Icon werden alle Extraktionsfelder ausgewählt bzw. alle Checkboxen in der Spalte “Aktiv” aktiviert.

Icon “Alle abwählen”

• Mit einem Linksklick auf das Icon werden alle Extraktionsfelder abgewählt bzw. alle Checkboxen in der Spalte “Aktiv” deaktiviert.

Suchfeld

• Über das Suchfeld kann gezielt nach bestimmten Inhalten bzw. Feldern der API-Antwort in der Spalte “Quellfeld” gesucht werden.

Tabelle - Spaltenüberschriften

Aktiv

• Über diese Spalte mit Checkboxen können einzelne Felder für den Transfer in die Zieltabelle ausgewählt werden.

Quellfeld

• Zeigt den Namen und ggf. den Pfad des Quellfelds aus der API-Anfrage an.

• Beispiel: response.address.street - Pfad: response.address / Feld: street

Zielspalte

• Eingabefeld für den Namen des Felds in der Zieltabelle

SQL-Typ

• Es können Spaltentypen für Spalten der Zieltabelle definiert werden.

• Folgende SQL Server Datentypen werden unterstützt:

  • NVARCHAR(255) - Standardwert für das Extraktionsfeld

  • NVARCHAR(4000)

  • NVARCHAR(MAX)

  • INT

  • BIGINT

  • DECIMAL(18,6)

  • FLOAT

  • MONEY

  • BIT

  • DATE

  • DATETIME

  • UNIQUEIDENTIFIER

Standardwert

• Eingabefeld für einen Standardwert für das Zielfeld, falls der Wert im Response-Objekt nicht vorhanden oder leer ist.

• Variablen aus der Steuerungsabfrage können verwendet werden.

Vorschau

• Vorschau des Feldwerts aus dem ersten zurückgegebenen Datensatz

• Es werden die ersten hundert Zeichen angezeigt.

Tabelle allgemein

Sortierfunktion

• Mit einem Linksklick neben die Spaltenüberschrift können die Angaben auf- oder absteigend bzw. alphabetisch sortiert werden.

Menüleiste

Icon “Feld hinzufügen”

• Über das Icon kann ein neues statisches Feld hinzugefügt werden.

Tabelle - Spaltenüberschriften

Aktiv

• Über diese Spalte mit Checkboxen können einzelne Felder für den Transfer in die Zieltabelle ausgewählt werden.

Spaltenname

• Eingabefeld für den Spaltennamen

SQL-Typ

• Es können Spaltentypen für Spalten der Zieltabelle definiert werden.

• Folgende Typen werden unterstützt:

  • NVARCHAR(255) - Standardwert für das Extraktionsfeld

  • NVARCHAR(4000)

  • NVARCHAR(MAX)

  • INT

  • BIGINT

  • DECIMAL(18,6)

  • FLOAT

  • MONEY

  • BIT

  • DATE

  • DATETIME

  • UNIQUEIDENTIFIER

Wert

• Es kann ein beliebiger fester Wert zugewiesen werden. Außerdem können Platzhalter aus der Steuerungsabfrage im Format {Feldname} verwendet werden.

Icon “Löschen”

• Über das Icon kann die Zeile gelöscht werden.

Name der Zieltabelle

• Eingabefeld für den Namen der Zieltabelle in der OCT Datenbank, in welche die Daten übertragen werden.

• Diese kann manuell vom Benutzer angelegt oder automatisch über den Button “Zieltabelle erstellen” generiert werden.

Icon “Lupe”

• Mit einem Linksklick auf das “Lupe”-Icon öffnet sich ein Dialog, in welchem die ersten 100 Zeilen der Zieltabelle angezeigt werden und Gruppierungen möglich sind.

• Schwebt man mit der Maus über dem Icon, wird ein Tooltip angezeigt.

Checkbox “Inhalt der Zieltabelle löschen”

• Standardmäßig ist die Checkbox deaktiviert.

• Bei aktivierter Checkbox wird die Zieltabelle vor jeder Ausführung des Transformationsskripts geleert.

• Schwebt man mit der Maus über dem Icon , wird ein Tooltip angezeigt.

Button “Zieltabelle generieren”

• Bei Auswahl des Buttons wird die Zieltabelle mit den aus dem Skript abgeleiteten Spaltennamen erstellt. Wenn die Tabelle bereits existiert, wird sie gelöscht und neu generiert.

Icon “Kopieren”

• Über das Icon neben dem Button kann das Skript zum Erstellen der Zieltabelle in die Zwischenablage kopiert werden.

• Bei erfolgreichem Kopieren erscheint eine kurze grün hinterlegte Meldung.

• Schwebt man mit der Maus über dem Icon, wird ein Tooltip angezeigt.

HTTP Timeout (s)

• Eingabefeld für Sekunden

• Standardmäßig sind 60 Sekunden für den Timeout eingestellt.

• Die Timeout-Option gilt nur für HTTP-Aufrufe. Alle anderen Datenbankoperationen während der Step-Ausführung, wie z. B. Massenkopiervorgänge, unterliegen weiterhin den Timeout-Einstellungen anderer Datenflüsse.

Parallele Anfragen

• Standardmäßig ist der Wert “1” eingestellt.

• Wenn eine Steuerungsabfrage viele Zeilen zurückgibt, werden diese normalerweise nacheinander verarbeitet. Um eine schnellere Verarbeitung zu ermöglichen, können Anfragen parallel ausgeführt werden.

• Wird der Wert auf einen Wert größer als 1 gesetzt, werden von der Steuerungsabfrage zurückgegebene Zeilen gleichzeitig verarbeitet. Dabei laufen für jede Zeile die HTTP-Anfrage, die Datenübertragung sowie das jeweilige PreSQL/PostSQL parallel.

• Die Gesamtzahl der geschriebenen Zeilen bleibt identisch zu einem sequenziellen Lauf.

• Die Einstellung greift nur bei einer Steuerungsabfrage, die mehr als eine Zeile zurückgibt.

• Der Wert ist auf 1–99 begrenzt und ein Pflichtfeld.

Wiederholungen bei Fehler

• Über dieses Feld kann festgelegt werden, wie oft eine fehlgeschlagene API-Anfrage erneut ausgeführt werden soll.

• Standardmäßig ist eine Wiederholung bei Fehler eingestellt. Es können maximal 9 Wiederholungen durchgeführt werden.

• Die Anfrage wird wiederholt, wenn die API den HTTP-Statuscode 500 oder höher zurückgibt oder ein Netzwerkfehler bzw. Timeout vorliegt.

• Schlägt ein erster Versuch fehl, wird dies zunächst als Warnung (Warning) im Log protokolliert.

• Erst wenn auch der letzte Wiederholungsversuch fehlschlägt, wird ein Fehler (Error) protokolliert und der gesamte Schritt als fehlerhaft beendet.

• Dadurch können vorübergehende API-Ausfälle abgefangen werden, ohne den gesamten Prozess erneut starten zu müssen.

Antwort streamen

• Bei aktivierter Checkbox wird nicht auf die komplette Antwort der API-Anfrage gewartet. Stattdessen werden die eingehenden Daten fortlaufend verarbeitet und unmittelbar Zeile für Zeile in die Zieltabelle geschrieben.

• Der maximale Speicherverbrauch bleibt dabei weitgehend unabhängig von der Größe der zu verarbeitenden Datenmenge konstant. Das Verfahren eignet sich daher insbesondere für große Datenmengen und Bulk-Exporte, z.B. für DATEV-Exporte.

• Streaming muss durch die API unterstützt werden.

• Im Header wird, falls noch nicht vorhanden, die Eigenschaft “Accept” mit dem Wert “application/octet-stream” automatisch hinzugefügt.

Paginierung

• Die Paginierung ist optional und standardmäßig auf “Keine” eingestellt.

• Es können folgende Optionen ausgewählt werden: “Offset / Limit”, “Next Link” und “Page Token”.

Offset / Limit

• Optionale Eingabefelder für die Namen der Offset- und Limit-Parameter mit Namen und Werten

Next Link

• Optionales Texteingabefeld zur Angabe eines JSONPath-/XPath-Ausdrucks für die URL der nächsten Seite

• Beispiel Next-Link-Pfad:

  • JSON: {“data”: […], “nextPageUrl”: “https://api.example.com/customers/?sessionpage=jiagA5gag}”

  • Texteingabe $.nextPageUrl

Page Token

• In einer JSON Antwort gibt es einen Parameter, den man an die URL anhängen muss.

• Beispiel: URL: https://my.api.com/something

  • Token-Pfad: $.nextPageToken

  • Query-Parametername: myToken

  • Antwort:
    {“data”:[…], “nextPageToken”:”1234567890”}

  • URL: https://my.api.com/something?myToken=1234567890

Statusfeld-Pfad

• JSONPath (z.B. $state) oder Xpath-Ausdruck, der auf das Statusfeld in der Antwort zeigt.

• Wenn ein Pfad eingetragen ist, fragt der Web-API Step seine eigene URL ab, bis dieses Feld den erwarteten Wert erreicht. Im Anschluss wird die Extraktion ausgeführt.

• Ein leerer Statusfeld-Pfad deaktiviert die Statusabfrage.

Erwarteter Wert

• Wert, den das Statusfeld erreichen muss, damit die Statusabfrage als abgeschlossen gilt.

• Wenn kein Wert eingetragen wird, wird die Statusabfrage abgeschlossen, sobald das Feld in der Antwort der API existiert und einen beliebigen Wert hat.

Abfrageintervall (s)

• Standardmäßig sind 60 Sekunden eingestellt.

• Es kann die Wartezeit in Sekunden (0 - 3600 Sekunden) zwischen den Statusabfragen individuell eingegeben werden,

Maximale Versuche

• Standardmäßig wird die Abfrage einmal ausgeführt.

• Es kann individuell die Anzahl der Wiederholungen (1 bis 99) nach der ersten Statusabfrage eingestellt werden.

• Die HTTP-Wiederholungsrichtlinie (siehe “Wiederholungen bei Fehler” in den Optionen https://saxess-software.atlassian.net/wiki/spaces/OH/pages/2632843266/v2026.07%2B3.2.3.8.%2BWeb-API#3.2.3.8.6.-Optionen-(e) ) gilt zusätzlich für jede Statusabfrage.

Step-Status nach erfolgloser Statusabfrage

• Endgültiger Step-Status, wenn das Statusfeld den erwarteten Wert nicht erreicht.

• Es kann zwischen zwei Optionen gewählt werden:

  • Fehler = Der Step wird sofort mit einem Fehler beendet.

  • Warnung = Die betreffende Zeile wird übersprungen und die Ausführung des Steps fortgesetzt.

PreSQL

• SQL-Befehl, welcher vor jeder HTTP-Anfrage auf der OneCoolTool-Datenbank ausgeführt werden soll.

• Bei Verwendung von Platzhaltern bzw. Variablen wird das PreSQL-Skript vor jeder HTTP-Anfrage ausgeführt. Andernfalls wird es einmalig vor der ersten HTTP-Anfrage ausgeführt.

PostSQL

• SQL-Befehl, welcher nach jeder HTTP-Anfrage auf der OneCoolTool-Datenbank ausgeführt werden soll.

• Bei Verwendung von Platzhaltern bzw. Variablen wird das PostSQL-Skript nach jeder HTTP-Anfrage ausgeführt. Andernfalls wird es einmalig nach der ersten HTTP-Anfrage ausgeführt.

Icon “SQL-Editor-Dialog öffnen”

• Mit einem Linksklick auf das Icon kann ein separater Dialog mit einem vergrößerten SQL-Editor geöffnet werden.

Icon “Tooltip”

• Schwebt man mit der Maus über dem Icon , wird ein Tooltip angezeigt.