API Connector Tools
Das API-Connector-Tools Add-On beinhaltet generische HTTP-Steps wie den APICall, SpreadsheetURLDownload oder URLDownload, mit dem sich nahezu jede auf HTTP basierende API ansprechen lässt.
Das ist vor allem dann praktisch, wenn es für eine API oder einen Webservice noch keine fertigen Steps in Synesty Studio gibt.
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.
HTTP Accounts unter Meine Verbindungen
Ein wichtiger Abschnitt für die HTTP-Steps ist der über HTTP-Accounts. Damit können Sie Zugangsdaten für APIs verwalten, insbesondere auch für OAuth 2.0.
XML oder JSON Lesen und schreiben
Im Zusammenhang mit APIs, Webservices und Schnittstellen geht es häufig darum, XML zu lesen (parsen) oder zu erzeugen.
Dazu empfehlen wir auch folgende Inhalte:
- Steps zum lesen von XML: XMLReader, XMLReaderVisual
- Steps zum lesen von JSON: JSONReader, JSONReaderVisual
- Die Seite XML und JSON Parsing am Beispiel mit komplexeren Beispielen
- TextHTMLWriter - der Step zum erzeugen von Text (XML, JSON, HTML....)
- Cookbook zum Erstellen von XML-Dateien am Beispiel
Client-Zertifikat basierte Authentifizierung
Die Steps APICall , SpreadsheetURLDownload oder URLDownload unterstützen auch eine Authentifizierung über Client-Zertifikate. Wenn der Server diese Art der Client-Authentifizierung erfordert, muss zunächst eine neue HTTP Verbindung mit dem zugehörige SSL-Zertifikat erstellt werden.
Legen Sie dazu einen neuen HTTP Account unter Mein Konto / Meine Verbindungen / HTTP / Neuen Account erstellen an.
Im Feld clientCertificate können sie ihre .p12 Zertifikatsdatei auswählen und hochladen. Falls vorhanden geben sie anschließend die zugehörige Passphrase im Feld clientCertificatePassphrase an und speichern die Account Daten.
Die angelegte Verbindung können sie anschließend im APICall , SpreadsheetURLDownload oder URLDownload Step als Account auswählen.
HTTP Accounts
HTTP Accounts nehmen eine gewisse Sonderrolle unter Meine Verbindungen ein, weil sie die Zugangsdaten für alle HTTP-Steps im API-Connector Tools Add-On verwalten. Darüber hinaus unterstützt dieser Account-Typ auch verschiedene Arten der Authencation von HTTP-APIs, u.a. das sehr komplexe OAuth 2.0 Authentication Protokoll.
Type - No Auth
Die einfachste Konfiguration des HTTP-Accounts ist der Type No Auth. Dabei kann man lediglich folgende Parameter hinterlegen:
- baseUrl (optional) - diese URL wird, wenn gefüllt, automatisch vor jede URL vorangestellt. Das ist praktisch, da man die Basis-URL für alle Steps zentral pflegen kann und in Steps nur noch den hinteren Teil der URL angeben muss.
- clientCertificate (optional) - SSL-Zertifikat für die auf Client-Zertifikaten basierende Authentifizierung (Base64-kodierte Datei). Laden Sie die Original-Zertifikatsdatei hoch. Sie wird automatisch als base64 kodiert
- clientCertificatePassphrase (optional) - Das Passwort für das clientCertificate
Type - OAuth 2.0
Die komplexeste Art der Authentication ist OAuth 2.0. Diese Art umfasst verschiedenste Ausprägungen, definiert durch die Grant-Types. Derzeit werden 3 Grant Types unterstüzt:
- Client Credentials
- Authorization Code
- Refresh Token
Client Credentials
Beim sog. Client Crededentials Grant fragt der Client (Synesty) bei der API-Gegenstelle (Token URL) mit den Zugangsdaten ClientId und einem Client Secret einen Access Token an (durch Klick auf Konfiguration starten). Dieser Access Token wird gespeichert und bei jedem HTTP-Request benötigt, um auf die API zuzugreifen (z.B. mit den Steps APICall, URLDownload oder SpreadsheetURLDownload).
Scope und Audience
Das Feld Scope wird je nach verwendeter API unterschiedlich gefüllt und ist der entsprechenden API-Dokumentation zu entnehmen. Oft gibt man da eine Liste von Berechtigungen oder Objekten an, auf die man zugreifen möchte. Im Screenshot z.B. auf Produktdaten und Bestellungen.
Der Audience Parameter ist (zum Zeitpunkt dieses Dokuments) nur Teil einer OAuth Draft-Spezifikation und kann bei einigen APIs mitgegeben werden. Wir gehen deshalb hier nicht weiter darauf ein.
Wenn ClientId und Client Secret korrekt sind, wird bei Klick auf Konfiguration starten der Access Token gefüllt.
Wenn dieser Access Token automatisch bei jedem HTTP-Request an den Server mitgeschickt werden soll, dann kann man durch Angabe von Add info automatically to=Request Header und Header Prefix=Bearer dafür sorgen, dass bei den HTTP-Steps folgender HTTP-Header mit dem geholten Access Token automatisch mitgeschickt wird:
Authorization: Bearer {Access Token}
Die Konfiguration dafür sieht so aus.
Authorization Code
Der sog. Authorization Code Grant ist eine komplexere Ausprägung von OAuth 2.0, bei der eine Benutzerinteraktion im Browser involviert ist. Dabei wird der Benutzer kurz auf eine Login-Webseite des Systems umgeleitet (Redirect). Dort gibt der Benutzer seine Zugangsdaten ein und teilt der anderen Anwendung mit, dass Synesty in seinem Namen auf die API zugreifen darf. Danach landet der Benutzer wieder in Synesty, und das Feld Access Token ist gefüllt. Dieser Access Token wird wieder bei jedem HTTP-Request benötigt, um auf die API zuzugreifen (z.B. mit den Steps APICall, URLDownload oder SpreadsheetURLDownload).
Wir zeigen am Beispiel der Slack-API wie dieser OAuth 2.0 Authorization Code Flow aussehen könnte.
Das Ziel dieser Konfiguration ist, über eine Slack-Webhook eine Nachricht an einen Channel zu schicken.
Danach klicken wir auf Konfiguration starten. Wir werden auf Slack umgeleitet, loggen uns ein und wählen den Channel, an den Synesty Nachrichten schicken darf.
Nach Klick auf Zulassen landen wir wieder in Synesty, mit nun ausgefülltem Access Token, Refresh Token und Token Response.
Der Refresh Token wird benötigt, um einen neuen Access Token zu holen, wenn dieser abgelaufen ist (siehe Feld Expires at). Mehr dazu weiter unten.
Die Token Response ist die komplette JSON-Anwort der jeweiligen API. In einigen Fällen wie z.B. hier bei Slack beinhaltet diese Antwort wichtige Werte und Parameter, die für weitere API-Calls benötigt werden. Im Fall von Slack beinhaltet die Response auch eine individuelle URL, an die weitere Requests geschickt werden müssen. Das ist der Grund warum, man sich diese Token Response speichern und merken muss.
Token Ablaufdatum und automatische Erneuerung des Tokens
Eine Sache, auf die bisher wenig eingegangen wurde, ist, was passiert, wenn der Token abgelaufen ist. In den Screenshots sieht man das Feld Expires at und Refresh Token Expires at. Diese beinhalten in der Regel den Zeitpunkt, bis wann der Token gültig ist bzw. wann dieser verfällt und seine Gültigkeit verliert.
Die HTTP-Steps, die einen HTTP-Account konfiguriert haben, sind in der Lage dies zu berücksichtigen und automatisch einen neuen Token zu holen. Das ist insbesondere bei den Steps APICall und SpreadsheetURLDownload wichtig, die mehrere Requests ausführen können und bei denen der Token sogar während der Ausführung ablaufen kann. D.h. die Steps erkennen und erneuern einen abgelaufenen Token in folgenden Szenarien:
- wenn der Token vor der Ausführung eines HTTP-Requests abgelaufen ist (durch Prüfung des Expires At Datums)
- wenn das Expires At Datum während der Ausführung des Steps abläuft
- wenn die API bei einem Request mit einem Fehler antwortet, dass der Token abgelaufen ist. In diesem Fall wird der versucht den Token zu erneuern und der HTTP-Request danach noch einmal erneut versucht. Schlägt der Request erneut fehl, dann wird abgebrochen, wie bei einem normalen HTTP-Request ohne OAuth-Token Erneuerung.
Das beutetet, dass man den HTTP OAuth-Account nur ein einziges Mal korrekt einrichten muss und dass ab diesem Zeitpunkt die HTTP-Steps immer einen korrekten Access Token zur Verfügung haben und sich diesen bei Ablauf erneuern - unter der Voraussetzung, dass die Zugangsdaten sich bei der Gegenstelle nicht ändern und die Gegenstelle, diesen OAuth Token Refresh-Prozess unterstützt.
Type - Basic Auth (preemptive)
Bei der "Basic"-HTTP-Authentifizierung werden die Anmeldedaten als Benutzer-ID/Kennwort-Paare in einer einzigen Anfrage übermittelt, die mit base64 kodiert ist.
Im Browser kennt man das als Benutzer, wenn beim Aufruf einer URL ein Popup mit Benutzername und Passwort auftaucht.
Type - Digest Auth
Digest-Authentifizierungsverfahren gemäß RFC 2617. Dies beinhaltet einen Challenge-Response-Austausch mit 2 Anfragen zur Aushandlung von qop, nonce, realm und Algorithmus (z.B. MD5 oder MD5-sess).
Type - Bearer Token
Bearer-Authentifizierung (auch Token-Authentifizierung genannt). Verwenden Sie sie, wenn Ihr Client nur ein Token senden muss, wenn er Anfragen an geschützte Ressourcen stellt. Das Token wird automatisch zu den requestHeaders hinzugefügt (Authorization: Bearer YOURTOKEN).
Steps im API Connector Tools Add-On
- APICall
- Archive
- ExtractArchive
- HTML2Spreadsheet
- HTMLParser
- JSONReader
- SpreadsheetUrlDownload
- UrlDownload
- WebDAVDownload
- WebDAVDownload
- WebDAVRename
- WebDAVRename
- WebDAVUpload
- WebDAVUpload
- XMLReader