Zum Hauptinhalt springen

API Client

Einleitung​

Nutzen Sie das API-Client-Modul, wenn Sie gesammelte Daten aus LoyJoy an Ihren Dienst senden, Daten von Ihrem Dienst nach LoyJoy ziehen oder einfach externe Dienste auslösen möchten. Die in diesem Modul konfigurierten API-Anfragen werden von einem LoyJoy-Server ausgeführt, nicht vom Browser des Nutzers.

Typische Anwendungsfälle​

Typische Anwendungsfälle sind das Exportieren von Daten aus LoyJoy an Ihren Webservice oder das Lesen von Daten aus externen Ressourcen.

Daten von einem externen Dienst lesen​

Als Beispiel möchten wir den aktuellen Preis eines Produkts lesen, der im Chat-Ablauf angezeigt werden soll.

Dazu setzen wir die Methode auf GET und geben die URL mit der ID des Produkts ein, z. B. http://example.org/getPrice?product-id=123abc. Wir könnten auch eine dynamische Produkt-ID verwenden, z. B. gespeichert in der LoyJoy-Variable product_id. Dann wäre die URL http://example.org/getPrice?product-id=${product_id}.

Nehmen wir an, diese Anfrage erzeugt einen JSON-Antwortkörper dieser Form:

{
  "price": {
    "amount": 125,
    "currency": "Euro",
    "validUntil": "2022-12-31"
  },
  "productId": "123abc"
}

Wir können dann das Feld /price/amount des JSON-Antwortkörpers auf eine Variable unserer Wahl mappen, z. B. product_price: grafik

Beim Durchlaufen dieses Prozessmoduls wird die GET-Anfrage ausgeführt und die Variable product_price mit dem Wert aus der Anfrage gefüllt. Danach kann die Variable product_price in jedem Textfeld verwendet werden.

Daten an einen externen Dienst senden​

Dies kann nützlich sein, um Kundendaten in eine bestehende Datenbank zu übertragen, z. B. um sie für eine Mailing-Liste zu abonnieren oder zu registrieren. Hier verwenden wir die POST-Methode und geben eine URL wie http://example.org/subscribe ein.

In diesem Fall verwenden wir einen JSON-Post-Body und geben das JSON einfach in das Payload-Textfeld ein. Im Payload verwenden wir die ${}-Notation, um auf die im LoyJoy-Chat vorhandenen Variablen zuzugreifen:

{
  "email": ${email},
  "firstName": ${firstname},
  "lastName": ${lastname},
  "birthdate": ${birthdate},
  "marketingOptIn": ${toBoolean(consent_single_opt_in_newsletter)},
  "consumption": ${toInteger(consumption)},
  "key": ${stringConcat(lastname, ", ", birthdate)}
}
hinweis

Datentypen werden automatisch auf Basis des Datentyps in LoyJoy behandelt. Alle Variablen werden in LoyJoy als Strings gespeichert. Deshalb müssen wir Typkonvertierungsfunktionen wie toBoolean und toInteger verwenden, um diese Typen zu senden. Auf dieser Seite finden Sie die vollständige Liste der Typkonvertierungsfunktionen. Andere Datentypen existieren in LoyJoy z. B. als Ausgabe von Funktionen wie randomInt.

hinweis

Sie können Ausdrücke im JSON-Body verwenden. Diese Ausdrücke sollten nicht in Anführungszeichen gesetzt werden:

{
  "key": ${stringConcat(lastname, ", ", birthdate)}
}

Die Variablen in diesem Beispiel sind alle standardmäßige LoyJoy-Variablen. Sie können die Standard-LoyJoy-Variablen hier nachschlagen. Zusätzlich können Sie auch benutzerdefinierte Variablen verwenden, die durch Fragebögen oder andere Module definiert wurden.

Auch hier können wir den Antwortkörper als JSON interpretieren. Zum Beispiel erhalten wir einen Antwortkörper wie:

{
  "status": "success",
  "subscriberId": "9cc2d7a1-888f-49bd-a169-5d196c900ced"
}

Wir können ein Mapping erstellen, das das Feld status der Antwort liest und auf eine Variable unserer Wahl abbildet: grafik

Abhängig vom Status können wir dem Kunden z. B. mitteilen, dass er erfolgreich abonniert wurde oder dass ein Fehler aufgetreten ist.

Verwendung des Moduls​

Senden Sie eine GET- oder POST-Anfrage an eine beliebige URL. Sie können Ihren Post-Anfragen ein benutzerdefiniertes Payload hinzufügen und in diesem Payload Variablen mit der ${variable}-Syntax verwenden. Wenn die URL eine JSON-Antwort zurückgibt, können Sie mit Mappings ein JSON-Feld auf eine LoyJoy-Variable abbilden.

Image1

Das folgende Video bietet einen kurzen Überblick: API Client Überblick

Anfrage​

Beginnen Sie mit der Eingabe der notwendigen Informationen Ihres Dienstes. Wenn Sie nicht sicher sind, welche Informationen relevant sind, fragen Sie den zuständigen Entwickler.

Autorisierung​

LoyJoy unterstützt drei verschiedene HTTP-Autorisierungsmethoden, die als Authorization-Header gesendet werden: Basic, Bearer und OAuth2.

Basic​

Bei der Basic-HTTP-Autorisierungsmethode werden Benutzername und Passwort als Teil des Authorization-Headers gesendet, getrennt durch einen Doppelpunkt und Base64-kodiert. Sie geben Benutzername und Passwort einfach in LoyJoy ein.

Bearer​

Die Bearer-HTTP-Autorisierungsmethode verwendet tokenbasierte Authentifizierung, bei der ein Token (normalerweise ein JWT) mit dem Präfix "Bearer" im Authorization-Header gesendet wird. Hier geben Sie das Token in LoyJoy ein (ohne das Präfix Bearer).

OAuth2​

OAuth2 ist ein branchenübliches Autorisierungsframework für delegierte Authentifizierung und Autorisierung. Es ermöglicht Nutzern, einem anderen Dienst eingeschränkten Zugriff auf ihre Ressourcen zu gewähren, ohne ihre Zugangsdaten weiterzugeben.

Um die OAuth2-Authentifizierung zu verwenden, müssen Sie die folgenden Informationen eingeben:

  • Header-Präfix: Präfix für den Authorization-Header. Üblicherweise und standardmäßig Bearer
  • Token-URL: URL, von der das Token abgerufen werden kann
  • Grant-Typ: Der Grant-Typ des OAuth2-Flows. client_credentials oder password
  • Client ID: ID des OAuth2-Clients
  • Client Secret: Secret zur Verifizierung des Clients
  • Passwort: Für den Grant-Typ password
  • Scope: Scope des OAuth2-Tokens
  • Authentifizierung: body oder header. Wenn Sie body wählen, wird das Token im Body der Anfrage an die Token-URL gesendet. Wenn Sie header wählen, wird das Token im Authorization-Header gesendet.

HTTP-Anfragemethode​

LoyJoy kann die HTTP-Anfrage als GET, POST oder PUT senden.

POST-/PUT-Body-Typen​

Drei verschiedene POST- und PUT-Body-Typen werden unterstützt:

  • JSON
  • Datei (Base64-kodiert)
  • Datei (Multipart)
  • Datei (Octet-Stream)
  • x-www-form-urlencoded (Schlüssel-Wert-Paare)

API-URL​

Geben Sie die URL des Endpunkts des Dienstes ein, in der Sie LoyJoy-Variablen verwenden können, z. B. https://example.org/some_endpoint?param1=${variable1}.

Payload​

Um einen HTTP-Body zusammen mit Ihrer Anfrage zu senden, verwenden Sie bitte die Methoden POST oder PUT. Strukturieren Sie Ihr Payload gemäß dem Schema, das Ihr Endpunkt definiert. Wenn Sie sich nicht sicher sind, fragen Sie bitte den zuständigen Entwickler. Beachten Sie, dass Sie LoyJoy-Variablen verwenden können. Beispielsweise können Sie ein JSON wie folgt senden.

{
  "source": "loyjoy",
  "firstname": ${firstname},
  "lastname": ${lastname},
  "variable1": ${variable1},
  "location_href": ${locationHref()}
}

Sie können jeden benutzerdefinierten Header einrichten, der für die Anfrage nötig ist, indem Sie Header-Schlüssel-Wert-Paare hinzufügen.

Image2

Antwort​

Der HTTP-Statuscode der Antwort wird immer in der Variable api_client_status_code gespeichert. Der Antwortkörper wird in der Variable api_client_response_body gespeichert. Bei einer JSON-Antwort wäre der Antwortkörper das vollständige JSON-Objekt.

Sie können jedoch Mappings verwenden, um Informationen aus JSON oder XML auszuwählen und in LoyJoy-Variablen zu speichern. So können Sie die Informationen aus der JSON- oder XML-Antwort im Chat-Ablauf verwenden.

Testen und Debuggen​

Um die API-Client-Konfiguration zu testen, können Sie die Chat-Vorschau verwenden und die Schritte durchgehen, die zur Aktivierung des API-Client-Moduls nötig sind. Um zu sehen, welche Daten übertragen wurden, können Sie das Debug-Logging im Modul aktivieren:

Klicken Sie zuerst oben rechts auf das Checklisten-Symbol.

Log debug

Aktivieren Sie dann den Schalter, um das Logging für die nächsten 60 Minuten zu aktivieren.

API client log

Das Log zeigt Ihnen dann, welche Anfragen gestellt wurden sowie das gesendete Payload und die empfangene Antwort. Payloads und Antworten werden nur gespeichert, wenn das Debugging aktiv ist. Andernfalls wird nur der HTTP-Statuscode nicht erfolgreicher Anfragen geloggt. Grundsätzlich deuten HTTP-Statuscodes, die mit 4 beginnen, auf einen Fehler in der Anfrage hin; Statuscodes, die mit 5 beginnen, auf einen internen Fehler im Dienst.

Eine Liste der HTTP-Statuscodes finden Sie hier.

Beispiel für ein Log einer erfolgreichen Anfrage: API client log debug

Beispiel für ein Log einer nicht erfolgreichen Anfrage: API client log debug error

Hier sehen wir, dass der Antwortstatus 404 war, was für "Not Found" (Nicht gefunden) steht. Beachten Sie den unterstrichenen Tippfehler in der URL. Die URL hätte /todos/1 statt /todoes/1 lauten müssen. Deshalb konnte der Server die Ressource nicht finden und antwortete mit dem Statuscode 404.

Ein weiteres Beispiel für eine nicht erfolgreiche Anfrage: API client log debug error 415

Hier sehen wir, dass die Ressource mit dem Statuscode 415 antwortete, was für "Unsupported Media Type" (Nicht unterstützter Medientyp) steht. Das bedeutet, dass der Server den Medientyp der Anfrage nicht unterstützt. In diesem Fall unterstützt der Server nur application/json, aber die Anfrage wurde mit application/x-www-form-urlencoded als Medientyp gesendet. Dies kann behoben werden, indem Sie den Request body type in der Modulkonfiguration ändern.

Wir sehen auch, dass der Antwortkörper oft weitere Informationen über den Fehler enthält und beim Debuggen des Problems helfen kann.

Cookies​

Diese Felder ermöglichen es Ihnen, Namen von Cookies einzugeben, die Sie senden oder empfangen möchten. Wenn der Server mit einem Cookie des angegebenen Namens antwortet, wird es in der LoyJoy-Session gespeichert. Wenn ein Cookie mit dem angegebenen Namen in der LoyJoy-Session gespeichert ist, wird es mit der Anfrage gesendet.

Header​

Header können in beide Richtungen verwendet werden. Um einen Request-Header hinzuzufügen, können Sie einfach einen gültigen Ausdruck und einen Header-Namen eingeben. grafik

Timeouts​

Das Prozessmodul wartet rund 20 Sekunden auf eine Antwort vom Server. Wenn der Server nicht innerhalb dieser Zeit antwortet, wird dies vom Prozessmodul als Timeout eingestuft. Es gibt mehrere Lösungen für dieses Problem.

Nicht erfolgreiche Anfragen wiederholen​

Die Replay-Funktion ermöglicht es Ihnen, fehlgeschlagene Anfragen erneut auszuführen. Die Anfrage wird gespeichert und kann wiederholt werden. Dies ist nützlich, wenn Sie Anfragen wiederholen möchten, die aufgrund eines Timeouts oder aus anderen Gründen fehlgeschlagen sind.

Statische IP-Adresse​

Standardmäßig sendet LoyJoy API-Anfragen von dynamisch zugewiesenen IP-Adressen. Wenn die Ziel-API nur Anfragen von freigegebenen (allowlisted) IP-Adressen akzeptiert, aktivieren Sie "Statische IP-Adresse verwenden" im Tab "Ausführung" des Moduls. Die Anfrage wird dann über einen Proxy mit einer statischen IP-Adresse gesendet, die unter der Einstellung angezeigt wird.

Diese Option ist nicht für hohe Last geeignet. Bitte kontaktieren Sie den LoyJoy-Support, bevor Sie sie aktivieren.

Prozessspezifische Variablen​

Dieses Modul erzeugt Variablen, die im gesamten aktuellen Prozess verfügbar sind. Sie gelten nur für diesen spezifischen Prozess und können sich mit Plattform-Updates weiterentwickeln. Eine detaillierte Liste finden Sie in der Liste der prozessspezifischen Variablen.