SpreadsheetUrlDownload
Mit dem SpreadsheetURLDownload Step können Sie mehrere HTTP-Requests basierend auf einem Input-Spreadsheet abschicken.
Dabei gibt es 2 Möglichkeiten:
- pro Spreadsheet-Zeile einen HTTP-Request absenden bzw. eine URL aufrufen
- für mehrere Zeilen gebündelt (Batch) einen HTTP-Request (z.B. pro 5 Zeilen je einen Request)
Die URL und der HTTP-Request-Body kann mit Variablen dynamisch zusammen gebaut werden (mit den bekannten Template-Möglichkeiten (Stichwort Freemarker)). Alle Spaltenwerte der jeweiligen Input-Spreadsheet-Zeile kann als Variable verwendet werden.
Alternativ ist es auch möglich mehrere Batch-Requests mit mit jeweils x Artikeldaten als Teil des XML-Request-Body abzuschicken. Das ermöglicht fortgeschrittenen Benutzern sehr breite Einsatzmöglichkeiten.
Die Antwort (die sog. HTTP-Response), in der Regel XML oder JSON, steht dann als FILELIST zur Verfügung und kann mit den bekannten Steps XMLReader oder JSONReader weiterverarbeitet werden.
Weiterhin gibt der Step ein Spreadsheet aus, welches Informationen zu jedem Call enthält und Sie als Logfile auswerten oder abspeichern können.
Tutorial: REST-API Anbindung
Lernen Sie in unserem Tutorial REST API Anbindung mit Synesty, wie man jede beliebige HTTP-API mit JSON oder XML anbinden kann - auch ohne Add-Ons von Synesty und ohne Programmierung in PHP, Java oder Javascript.
Unterschied zwischen APICall, SpreadsheetURLDownload und URLDownload
Dieses Cookbook beschreibt den Unterschied der drei Steps.
Anwendungsbeispiel
Stellen sie sich vor, Sie haben ein Spreadsheet mit 100 Artikeln. Für jeden Artikel soll der aktuelle Warenbestand über eine API eines anderen Systems angefragt werden.
Beispiel Lieferanten API
http://api.meinlieferant.de/getStock
Ein typischer Flow mit diesem Step beginnt so:
Hier wird angenommen, dass die per API abzufragenden Artikel in einem Datastore existieren (sie könnten auch aus einer CSV-Datei stammen). Für jeden Artikel (genauer für jede Artikelnummer) soll eine API-URL eines Lieferanten aufgerufen werden.
Jeder Aufruf gibt eine XML-Response als FILELIST zurück und zusätzlich wird ein Spreadsheet ausgegeben, welches Daten über jeden ausgeführten HTTP-Request / Call enthält.
Jede Datei dieser FILELIST wird mit Hilfe des XMLReader Steps geparst und in ein Spreadsheet umgewandelt und dann weiter verarbeitet.
Beispielkonfiguration SpreadsheetUrlDownload Step
Hier wird der Identifier aus dem Input-Spreadsheet an jede URL gehängt, damit pro SKU Daten abgefragt werden.
Ergebnis
Das Ergebnis Spreadsheet sieht z.B. so aus:
Zusätzlich gibt es noch eine FILELIST als Ausgabe, die im anschließenden XMLReader Step geparst wird.
Hierbei ist es wichtig zu wissen, dass der XMLReader Step in der Lage ist mehrere XML-Dateien als FILELIST zu verarbeiten, aber nur wenn alle XML-Dateien identisch aussehen, also das gleiche Schema verwenden.
Request Body mit Inhalt aus mehreren Zeilen / BatchSize
Der SpreadsheetURLDownload Step bietet die Möglichkeit mehrere Zeilen zu einem Request zusammenzufassen.
Dazu dient die Option batchSize.
Beispiel:
Angenommen, Sie haben ein Spreadsheet mit 10 Artikeln.
Die API, die sie ansprechen erlaubt es 5 Artikel pro Request zu schicken. Die Artikelnummern sollen kommagetrennt im Request-Body übermittelt werden.
Das bedeutet bei 10 Artikeln: 2 Requests mit jeweils 5 Artikelnummern.
Input Spreadsheet:
![Input Spreadsheet]../img/18088038/41648691.png "Input Spreadsheet")
SpreadsheetURLDownload Konfiguration:
Die wichtigen Einstellungen sind:
| Option | Wert | Beschreibung |
|---|---|---|
| method | POST | notwendig, damit der requestBody übermittelt wird. Bei GET werden nur Parameter in der URL übermittelt. |
| batchSize | 5 | Damit wird pro 5 Zeilen jeweils ein HTTP-Request abgeschickt. |
| requestBody | <#list rows as row>${row.get("id")!}<#sep>, </#list> | wenn batchSize > 1 ist, wird eine Variable rowsverfügbar, mit der man auf alle Zeilen des aktuellen "Batches" zugreifen kann (im Beispiel auf die jeweiligen 5 Artikelzeilen). |
Ergebnis nach Abschicken der Requests:
Man sieht, dass bei 10 Artikeln und batchSize=5 insgesamt 2 HTTP-Requests abgeschickt werden. Der requestBody enthält jeweils 5 Artikelnummern.
Hilfsvariable im requestBody
Wenn batchSize>1 ist, dann erscheint in der Variablenauswahl über den + - Button ganz oben eine neue Variable mit der Bezeichnung "BatchRows Example Code:..."
Diese Variable fügt automatisch ein Skript in den requestBody ein, womit man auf alle Werte der Zeilen im jeweiligen Batch zugreifen kann. Bearbeiten Sie diese Skript einfach so, dass Sie damit den gewünschten RequestBody erstellt haben. Im Beispiel haben wir z.B. alle Spalten bis auf die id-Spalte entfernt, da wir nur diese verwenden wollen.
Spalten des Input-Spreadsheets durchschleifen
Wann brauche ich das?
Das Output-Spreadsheet enthält u.a. den requestBody und auch (optional) den responseContent, welche man dann weiterverarbeiten kann.
Manchmal braucht man aber in Folge-Steps auch Werte aus dem Input-Spreadsheet wie z.B. eine Artikelnummer / SKU.
Mit der Option outputSourceColumns kann man eine Liste von Spalten des Input-Spreadsheets auswählen, die auch wieder im Output-Spreadsheet auftauchen sollen (sprich: durchgeschliffen werden).
Diese Spalten tauchen dann im Output-Spreadsheet mit dem Prefix source_ auf.
Beispiel:
Hier sollen die 2 Spalten sku und identifier2 durchgeschliffen werden.
Das führt dazu, dass diese Spalten auch wieder im Output-Spreadsheet auftauchen und zwar mit den Spaltennamen source_sku und source_identifier2.
Begrenzung der Calls pro Sekunde bei URL-Abrufen und API-Calls
Die Steps SpreadsheetURLDownload und APICall haben jetzt einen neue Option rateLimitPerSecond.
Damit lassen sich die Anfragen pro Sekunde limitieren. Der Step wartet zwischen den Anfragen dann automatisch so lange zwischen Anfragen, so dass das Call-Limit eingehalten wird.
Wozu brauche ich das?
Viele APIs und Webservice Schnittstellen erlauben nur eine bestimmte Anzahl Zugriffe pro Sekunde oder Minute (sog. Call-Limits), um die Systemlast zu reduzieren. D.h. der Aufrufer muss sich an diese Limits halten. Mit dieser Option haben Sie die Möglichkeit diese Call-Limits zu konfigurieren.
Beispiele:
- 2 pro Sekundebedeutet 120 Aufrufe/Minute
- 0.5 pro Sekunde bedeutet 2 Sekunden Pause nach jedem Aufruf
- Default: Leer = Kein Limit
HTTP Error Codes
Im Feld errorStatusCodes können sie konfigurieren welche HTTP Status als Fehler gewertet werden. Standardmäßig (leeres Feld) sind Antworten mit einem HTTP-Statuscode größer oder gleich 300 ein Fehler. Im Falle einer Weiterleitung (Status 3xx) bei einem GET Request wird der Status Code zur weitergeleiteten URL ausgewertet.
Sie können auch individuelle Status als Komma-separierte Liste im Feld angeben. Es ist auch möglich die Status in Form von Regulären Ausdrücken anzugegeben.
Beispiele:
- leer -> Fehler bei Status >= 300
- 401,407 -> Fehler bei Status Code 401 & 407
- 40[0-7],5[0-9][0-9] -> Fehler bei Status Code 400 bis 407 und 500 bis 599
- 40[135] -> Fehler bei Status Code 401, 403 und 405
- 3.*,4.*,5.* -> Fehler bei 300 – 599
Quellen Base 64 kodieren
Sollen mittels SpreadsheetUrlDownload Base64-kodierte Inhalte übertragen werden, so können diese mittels der Methode urlcontentBase64() aus einer externen Quelle eingebunden werden.
Die Methode erwartet als ersten Parameter die Datei / Bild URL.
Mit dem zweiten Parameter (Boolean) kann angegeben werden, ob die URL zuvor darauf geprüft werden soll, ob sich dort eine Datei befindet.
Per default ist dieser Wert true. Er kann aber gegeben den Fall, dass sich definitiv eine Datei hinter der Adresse verbirgt oder die Adresse nicht geprüft werden soll auf false gesetzt werden.
Im Fehlerfall gibt diese Funktion einen Fehler nach dem Muster "ERROR: [Fehlermeldung]" aus.
Beispiel für die Anwendung im RequestBody:
<#assign base64img = meta.urlcontentBase64(image_url!, true)/>
<#if !base64img?startsWith("ERROR") >
{
"id": 1,
"base64Image": ${base64img}
}
</#if>
HTTP Multipart Requests
Siehe APICall#HTTPMultipartRequests.
Dateiupload
Der SpreadsheetURLDownload bietet auch die Möglichkeit, eine Datei pro Request zu senden. Diese Funktion gab es bisher schon im URLDownload und APICall Step (siehe APICall#HTTPMultipartRequests).
Dabei unterscheidet man zwei Arten, wie Dateien in einem HTTP-Request übertragen werden können:
- Direkt binär über einen Form-Multipart Upload
- als Base64-String im RequestBody
Variante 1 - Dateiupload binär über einen Form-Multipart Upload
Dafür gibt es 3 Optionen: filesToUpload, fileNameInList und fileParameterName.
Dadurch wird folgender HTTP-Multipart-Request erzeugt.
Wann braucht man das?
Es kommt jetzt auf die Art der API an, die überhaupt diese Form des HTTP-Requests für Dateiupload erwartet. Ein Beispiel in einem vergangenen Projekt war die Lexoffice REST-API zur Übermittlung von Belegen.
Variante 2 - Datei als Base64-String im RequestBody
Dafür gibt es eine neue Template Funktion fileToBase64. Diese wandelt eine Datei in einen BASE64 String und ann auch mit FILELIST umgehen und eine einzelne Datei anhand des Names selektieren. Beispiel:
# Einzelne Datei in Base64 umwandeln. FILEOBJECT könnte z.B. das Ergebnis aus einem FTPSingleFileDownload oder URLDownload Step sein
${fileToBase64(FILEOBJECT)}
# Einzelne Datei aus eine Dateiliste in Base64 umwandeln. Hier wird die Datei invoice2.pdf aus der Dateiliste ausgewählt. Die Liste könnte z.B. von einem FTPDownload kommen oder eine entpackten ZIP-Datei mit Rechnungen.
${fileToBase64(FILELIST, "invoice2.pdf")}
Wann braucht man das?
Auch hier kommt es wieder auf die API an. Die Mailjet API zum Versenden von E-Mail-Anhängen erwartet z.B. jeden Dateianhang als Base64 String.
"Attachments": [
{
"ContentType": "text/plain",
"Filename": "test.txt",
"Base64Content": "VGhpcyBpcyB5b3VyIGF0dGFjaGVkIGZpbGUhISEK"
}
]
Hilfreiche Tools zum Debugging
Die Arbeit mit APIs und HTTP-Requests ist manchmal etwas tricky, da man nicht so recht weiss, was genau bei der Gegenseite ankommt.
Hilfreiche Tools sind:
Damit kann man sich eine temporäre Test-URL erstellen gegen die man HTTP-Requests feuern kann. Zu jedem Request kann man sich dann genau die HTTP-Daten und Header anschauen, die übermittelt wurden.
Bei der Arbeit mit APIs und Schnittstellen ist dieses Tool sehr nützlich, da es sichtbar macht, was man sonst nicht sieht.
Inputs
Das sind die Optionen, mit denen man den Step konfigurieren kann.
| Name | Datentyp | Beschreibung | Pflichtfeld | Werte |
|---|---|---|---|---|
| account | ACCOUNT | Wählen sie einen HTTP account für eine Client Zertifikat-basierte Authentifizierung | Nein | |
| input | SPREADSHEET | SPREADSHEET das alle Daten zum ausführen der Anfrage enthält. | Ja | |
| host | STRING | Das ist die URL die abgerufen wird (e.g https://api.somewebservice.com/GetStock, https://www.mywebsite.com/products.csv). Ünterstützte Protokolle sind http://, https://. Das Protokoll ist Pflicht. | Ja | |
| method | STRING | Die HTTP Methode (GET, POST, PUT, HEAD, PATCH, DELETE). | Ja |
|
| requestBody | STRING | Optional: Den HTTP request body direkt senden. Besonders nützlich bei der Kommunikation mit XML oder JSON Webdiensten, bei denen die ganze XML Anfrage in das Text Feld geschrieben wird. Funktioniert nur mit der POST, PATCH, PUT HTTP Methode. Wenn batchSize=1 sind alle Felder der Zeile als Freemarker Variablen verfügbar (z.B. ${somecol1!}). Die Variable ${rows} enthält zusätzlich je nach batchSize alle Zeilen des aktuellen Batches. Bei bodyContentType=multipart/form-data (oder Dateiupoad mit fileToUpload) kann man auch Form-Parameter übermitteln z.B. ¶m1=value1¶m2=value2 (wenn die URL/host keine Parameter hat, dann ohne das erste &-Zeichen). Es ist auch für bessere Lesbarkeit möglich, pro Zeile einen Parameter zu verwenden. Wichtig ist, dass der Wert keine Zeilenumbrüche beinhaltet. Verwenden Sie ggf. die Funktion ${urlEncode("one & one is two")}, um Werte url-encodiert zu schicken. Für mehrzeilige Werte sollte die Freemarker <#compress> function probiert werden. | Nein | |
| limit | STRING | Begrenzt die Anzahl der Zeilen die vom Eingabe SPREADSHEET verwendet werden. Verwenden Sie kleine Werte zum Testen. | Nein | |
| batchSize | STRING | Legen Sie eine batchSize > 1 fest um, einen Call pro N in batchSize festgelegten Zeilen zu machen. Dies ist oft hilfreich, wenn man auf APIs zugreifen möchte die nur das Senden von z.B. 25 Einträge pro Aufruf erlauben. Beispiel: Angenommen Sie haben 12 Zeilen in Ihrem Eingangs SPREADSHEET. Mit batchSize=1 werden 12 Requests ausgeführt (einer pro Zeile). Mit batchSize=5 werden 3 Requests (1. und 2. Request: 5 Zeilen, 3. Request: 2 Zeilen) ausgeführt. Die Variable ${rows} enthält alle Zeilen des Batchs und kann im requestBody verwendet werden. Bei batchSize=1 steht jeder Spaltenwert als einfache Variable ${spaltenname} im requestBody zur Verfügung. (Achtung bei batchSize=1: Die ${rows} Variable kann von einer gleichnamigen Spalte 'rows' überschrieben werden.). | Nein | |
| bodyContentType | STRING | Optional: Der Content type des requestBody. | Nein |
|
| requestHeaders | STRING | Optional: Zusätzliche HTTP request headers, die der HTTP Anfrage als key=value (Schlüssel-Wert-Paar) hinzugefügt werden (ein Paar pro Zeile). | Nein | |
| username | STRING | Falls die URL mit HTTP BASIC AUTH geschützt ist. Das ist der Benutzername. | Nein | |
| password | STRING | Das HTTP BASIC AUTH Passwort. | Nein | |
| errorStatusCodes | STRING | kommagetrennte Liste von HTTP Status Codes bei denen der Flow anhält, z.B. 403,404,500. Leer lassen für alle Status Codes größer 300. | Nein | |
| filename | STRING | Kann verwendet werden um Dateinamen der Antwort-Dateien zusammenzusetzen. Immer eine Dateierweiterung für den Dateinamen angeben (z.B. meinedatei.txt). Wenn leer wird der Dateiname automatisch gesetzt. | Nein | |
| filesToUpload | FILELIST | Optional: Diese Datei direkt in den requestBody senden. Wichtig: Die Option 'bodyContentType' sollte dafür leer oder 'multipart/form-data;' sein. | Nein | |
| fileNameInList | STRING | Der Dateiname einer Datei in 'filesToUpload', die im Request gesendet werden soll. | Nein | |
| fileParameterName | STRING | Optional: Der Name des HTTP-Request-Parameters, unter dem die Datei hochgeladen wird. (Default, wenn leer: 'upfile') | Nein | |
| outputMode | STRING | Legen Sie das Ausgabe Verhalten fest. (Datei Liste - eine Datei pro Antwort. responseContent Spalte hinzufügen - Die Antwort wird ebenfalls im Ergenis Spreadsheet dargestellt. Bitte nur nutzen wenn Datei Liste nicht ausreicht. Fügt den Inhalt der Antwort mit Base64 kodierter Zeichenfolge zum Ausgabe Spreadsheet - Die Ausgabe der responseContent Spalte ist eine Base64 kodierte Zeichenfolge.) | Nein |
|
| encoding | STRING | Der Zeichensatz der Antwort (Default: UTF-8). Wird nur verwendet für den Ausgabe Modus 'responseContent Spalte hinzufügen' | Ja |
|
| outputSourceColumns | STRING | Legt die Spalten des Quell-Spreadsheets fest, die zum Ausgabe Spreadsheet hinzugefügt werden sollen. | Nein | |
| headerContentType | STRING | Der HTTP header ContentType | Nein |
|
| timeoutInSeconds | STRING | Optional: HTTP Verbingungs- und Lese-Timeout in Sekunden. Default: 60s. Wenn der Server für die Antwort länger als timeoutInSeconds braucht, schlägt der Step fehl und gibt ienen Fehler aus. | Nein | |
| rateLimitPerSecond | STRING | Die Geschwindigkeitsbegrenzung erlaubt es die Anzahl der Aufrufe pro Sekunde, z.B. 2 Aufrufe/s (=120 Aufrufe/Minute) zu beschränken. Oder 0.5 Aufrufe/s bedeutet eine Verzögerung von 2 Sekunden nach jedem Aufruf. Default: keine Begrenzung. | Nein | |
| numErrorsToStopFlow | STRING | Optional: Legt die Anzahl der Fehler oder Timeouts fest, die passieren dürfen bevor ein Flow mit ERROR abbricht. Default: 3. Es wird empfohlen des Wert gering zu halten. Wenn Hosts zu langsam antworten, versuchen Sie die die batchSize zu verringern. | Nein | |
| sslCertificates | STRING | Experten-Einstellungen für https-urls: Unter normalen Umständen resultieren URLs mit Selbst-Signierten SSL Zertifikaten in einem Fehler. Dieser kann übergangen werden wenn diese Einstellung auf 'Selbst-Signierten SSL Zertifikaten vertrauen' gesetzt wird. Diese Einstellung stellt aber ein Sicherheitsrisiko dar, da schadhafte Seiten dies missbrauchen könnten um sensitive Informationsn zu stehlen. Nur benutzen, wenn Sie wissen was Sie tun!!! | Nein |
|
Outputs
Das sind die Ergebnisse des Steps, die von nachfolgenden Steps, nach der Ausführung verwendet werden können.
| Name | Datentyp | Beschreibung | Pflichtfeld | Werte |
|---|---|---|---|---|
| requests | SPREADSHEET | Ein SPREADSHEET, welche die URL, requestBody und HTTP-Status jeder Anfrage enthält. | Ja | |
| output | FILELIST | Eine FILELIST, welche den Inhalt jeder Anfrage enthält. | Ja |