Triggering einer Studio-Operation über einen Webhook in Jitterbit Studio

Einführung

Mit API Manager können Sie eine Studio-Operation als HTTP-Endpunkt veröffentlichen. Wenn ein externes System eine HTTP-Anfrage an diesen Endpunkt sendet, empfängt API Manager die Anfrage und führt sofort die verknüpfte Operation aus, wobei der Anfragebody und die Header durch Jitterbit-Variablen weitergeleitet werden.

Dieses Muster ist nützlich, um auf Echtzeitereignisse von externen Systemen wie CRM-Plattformen, Ticketing-Tools oder benutzerdefinierten Anwendungen zu reagieren, die ausgehende Webhooks unterstützen.

Diese Anleitung behandelt den Typ Custom API in API Manager. Sie geht von Folgendem aus:

• Eine Custom API ist in API Manager in derselben Umgebung wie das Projekt konfiguriert und veröffentlicht.
• Ein Studio-Projekt existiert mit mindestens einer Operation zum Empfangen der eingehenden Anfrage.

Der allgemeine Ablauf ist:

Teil 1: Erstellen der Custom API

Schritt 1: API erstellen

1. Öffnen Sie API Manager und klicken Sie auf New API.

2. Wählen Sie Custom API als API-Typ.

3. API Name: Geben Sie einen Namen für die API ein (z. B. Webhook Receiver). Dieser Name wird in API Manager und in Operationsprotokollen angezeigt.

4. URL Prefix: Geben Sie das Basissegment des Pfads für die öffentliche Endpunkt-URL ein (z. B. my-webhook).

5. Version: Geben Sie eine Versionsnummer ein (z. B. 1.0). Diese wird Teil der Endpunkt-URL.

6. Enable SSL: Aktivieren Sie diese Option, um HTTPS-Verbindungen zu erzwingen. Dies wird für alle Produktionsendpunkte empfohlen.

7. Enable CORS: Aktivieren Sie diese Option, wenn das externe System Cross-Origin-Anfragen aus einem Browser-Kontext sendet.

8. Klicken Sie auf Save.

Schritt 2: Konfigurieren des Service-Endpunkts

1. Klicken Sie im API-Editor auf Add Service.

2. Method: Wählen Sie die HTTP-Methode aus, die das externe System zum Senden des Webhooks verwendet (z. B. POST).

3. Path: Geben Sie den Endpunkt-Unterpfad ein (z. B. /events). Dieser wird an die Basis-URL angehängt.

4. Operation: Wählen Sie die Studio-Operation aus, die die eingehende Anfrage verarbeitet.

5. Response Type: Wählen Sie System Variable. Mit dieser Einstellung wird der Response-Body durch den Wert bestimmt, den die Operation der Variable $jitterbit.api.response zuweist.

6. Timeout: Legen Sie die maximale Zeit fest, die API Manager auf den Abschluss der Operation wartet. Der Standard ist 30 Sekunden.

7. Klicken Sie auf Save und dann auf Publish.

Nach der Veröffentlichung zeigt API Manager die vollständige Endpunkt-URL im Format https://<host>/<prefix>/<version>/<path> an. Kopieren Sie diese URL und konfigurieren Sie das externe System so, dass es Webhook-Payloads an diese URL sendet.

Teil 2: Zugriff auf die Request-Payload in der Operation

Wenn API Manager die verknüpfte Operation auslöst, werden Jitterbit-Variablen mit den eingehenden Request-Daten gefüllt. Lesen Sie diese Variablen in einem Script-Schritt am Anfang der Operation.

Das folgende Beispiel protokolliert den eingehenden Body und URI im Operationsprotokoll:

<trans>
WriteToOperationLog("Received body: " + $jitterbit.api.request.body);
WriteToOperationLog("URI: " + $jitterbit.api.request.headers.fulluri);
</trans>

Um die Payload in einer Transformation zu verwenden, weisen Sie sie einer Variablen zu und ordnen diese Variable als Quelle zu:

<trans>
$payload = $jitterbit.api.request.body;
</trans>

Routing von Anfragen über mehrere Pfade

Wenn die API mehrere Service-Pfade hat (z. B. /createRecord und /updateRecord), können Sie alle Pfade einer einzelnen Controller-Operation zuordnen und eine Case()-Anweisung verwenden, um basierend auf dem URI zu Sub-Operationen zu leiten:

<trans>
Case(
  Index($jitterbit.api.request.headers.fulluri, "/createRecord") >= 0,
    RunOperation("<TAG>operation:Create Record</TAG>");,
  Index($jitterbit.api.request.headers.fulluri, "/updateRecord") >= 0,
    RunOperation("<TAG>operation:Update Record</TAG>");
);
</trans>

Dies hält die API-Konfiguration einfach (ein Einstiegspunkt), während die Controller-Operation die Dispatch-Logik verarbeitet.

Teil 3: Eine Antwort an den Aufrufer zurückgeben

Wenn Response Type auf System Variable eingestellt ist, gibt API Manager den Wert von $jitterbit.api.response als HTTP-Response-Body zurück. Legen Sie diese Variable in der Operation fest, bevor sie abgeschlossen wird.

Das folgende Beispiel gibt eine JSON-Bestätigung zurück:

<trans>
$jitterbit.api.response = '{"status":"received"}';
</trans>

Wenn $jitterbit.api.response nicht gesetzt ist, gibt API Manager eine leere 200 OK-Antwort zurück.

Um einen anderen HTTP-Statuscode als 200 zurückzugeben, legen Sie $jitterbit.api.response.status_code zusammen mit dem Response-Body fest:

<trans>
$jitterbit.api.response.status_code = "400";
$jitterbit.api.response = '{"error":"Missing required field"}';
</trans>

Integration überprüfen

1. Stellen Sie das Projekt bereit und führen Sie es aus.

2. Kopieren Sie in API Manager die veröffentlichte Endpoint-URL.

3. Senden Sie eine Test-POST-Anfrage an den Endpoint mit einem Tool wie curl oder Postman, einschließlich eines JSON-Body.

4. Öffnen Sie die Operation Logs und bestätigen Sie, dass die Operation ausgeführt wurde und dass der protokollierte Body mit der Test-Payload übereinstimmt.

5. Bestätigen Sie, dass der HTTP-Response-Body und der Statuscode den in $jitterbit.api.response und $jitterbit.api.response.status_code festgelegten Werten entsprechen.