3.2.3.8. Web-API | Help Center

Mithilfe dieses Steps kann eine Web-API-Anfrage gestellt werden.

3.2.3.8.1. Web-API - Step hinzufügen

Wählen Sie den gewünschten Step aus:

Wenn der Step ausgewählt wird, öffnet sich eine Übersicht:

3.2.3.8.2. Steuerungsabfrage (a)

Hier kann eine optionale Steuerungsabfrage erstellt werden.

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) und im Namen der Zieltabelle zur Verfügung.

Icon “SQL-Editor-Dialog öffnen”

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

3.2.3.8.3. Anfrage (b)

Hier können alle Informationen für die HTTP-Anfrage eingetragen werden.

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.
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 “Form URL kodiert” 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. Hier finden Sie die Beschreibung der Datenquelle “Web API Authentifizierung”: 3.2.1.7. Web API Authentifizierung

3.2.3.8.4. Antwort (c)

Hier muss das Antwortformat der Web-API-Anfrage ausgewählt, Extraktionsfelder und statische Felder ausgewählt sowie das Transformationsskript bearbeitet werden.

In einem Drop-down kann das gewünschte Antwortformat (json, xml, text) ausgewählt werden.

3.2.3.8.4.1. Extraktionsfelder

3.2.3.8.4.1.1. Extraktionsfelder auswählen

Die Extraktionsfelder kommen aus der Antwort der Web-API-Anfrage.
Bei Auswahl des Buttons “Extraktionsfelder auswählen” öffnet sich ein Dialog, in welchem die Extraktionsfelder in einer Tabelle aufgelistet sind.

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.
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.

Endfelder - Felder, die keine Objekte enthalten - sind beim Öffnen des Dialogs “Extraktionsfelder” automatisch ausgewählt.

Die Anzahl der ausgewählten Extraktionsfelder wird direkt auf dem Button in eckigen Klammern angezeigt.

3.2.3.8.4.1.2. Statische Felder

Es besteht die Möglichkeit, den in die Zieltabelle zu übertragenden Daten zusätzliche statische Felder hinzuzufügen.
Variablen aus der Steuerungsabfrage sollten ersetzt werden, wenn sie als Wert für das statische Feld verwendet werden.
Bei Auswahl des Buttons “Statische Felder” öffnet sich ein Dialog, in welchem neue statische Felder hinzugefügt werden können.

Menüleiste
Icon “Zeile 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 “Zeile löschen”	Über das Icon kann die Zeile gelöscht werden.

Die Anzahl der ausgewählten Extraktionsfelder wird direkt auf dem Button in eckigen Klammern angezeigt.

3.2.3.8.4.2. Transformationsskript

Das Transformationsskript bietet im Vergleich zur Auswahl der Extraktionsfelder mehr Möglichkeiten zur Anpassung der Datenübernahme.

Die Daten können mit Hilfe von JavaScript beliebig transformiert werden.
Die von der HTTP-Anfrage zurückgegebene Antwort ist in der Variable “response” verfügbar.
Ziel des Transformationsskripts ist die Rückgabe eines Arrays von Zeilenobjekten, das in die Zieltabelle übertragen wird.
Für HTTP-Antworten im JSON Format sollte die Funktion JSON.parse(response) verwendet werden. Für eine HTTP-Antwort im XML Format sollte JSON.parse(parseXml(response)) verwendet werden.

Das Transformationsskript kann an dieser Stelle in einem Editor angesehen sowie bearbeitet werden.
Über das Icon “Editor vergrößern” kann ein separater Dialog mit einem vergrößerten Editor geöffnet und in diesem das Transformationsskript bearbeitet sowie angewandt werden.

3.2.3.8.5. Zieltabelle (d)

Hier wird definiert, in welcher Zieltabelle die Daten gespeichert werden.

Wenn keine Zieltabelle definiert ist, werden keine Daten in keine Zieltabelle übertragen. Dies ist in bestimmten Fällen vorgesehen und sinnvoll, z.B. bei POST-Aufrufen, bei denen ausschließlich ein HTTP-Statuscode zurückgegeben wird und der Response-Body leer bleibt.

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.

3.2.3.8.6. Optionen (e)

Hier kann ein Timeout für den HTTP-Anfrage sowie Optionen für die Paginierung eingegeben werden.

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.
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

3.2.3.8.7. Zusätzliche SQL-Befehle (f)

Die von der Steuerungsabfrage zurückgegebenen Felder können als Variablen im Filterausdruck, PreSQL und PostSQL verwendet werden.

Werden keine Variablen im PreSQL- oder PostSQL-Befehl verwendet, wird der Befehl nur einmal vor der ersten oder einmal nach der letzten Anfrage durchgeführt.

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.