SpreadsheetUrlDownload

Mit dem SpreadsheetURLDownloadopen in new window 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 Cookbookopen in new window 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:

OptionWertBeschreibung
methodPOSTnotwendig, damit der requestBody übermittelt wird. Bei GET werden nur Parameter in der URL übermittelt.
batchSize5Damit 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 SpreadsheetURLDownloadopen in new window und APICallopen in new window 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:

  1. Direkt binär über einen Form-Multipart Upload
  2. 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 Belegenopen in new window.

Variante 2 - Datei als Base64-String im RequestBody

Dafür gibt es eine neue Template Funktion fileToBase64open in new window. 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ängenopen in new window 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.