Einen Studio-Betrieb von einem Webhook in Jitterbit Studio auslösen

Einführung

API Manager ermöglicht es, einen Studio-Betrieb als HTTP-Endpunkt zu veröffentlichen. Wenn ein externes System eine HTTP-Anfrage an diesen Endpunkt sendet, empfängt API Manager die Anfrage und führt sofort den verknüpften Betrieb aus, wobei der Anfrageinhalts und die Header über Jitterbit-Variablen weitergeleitet werden.

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

Dieses Handbuch behandelt den Typ Custom API in API Manager. Es geht von folgenden Voraussetzungen aus:

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

Der allgemeine Ablauf sieht wie folgt aus:

Teil 1: Die benutzerdefinierte API erstellen

Schritt 1: Die API erstellen

1. Öffne API Manager und klicke auf New API.

2. Wähle Custom API als API-Typ aus.

3. API Name: Gib einen Namen für die API ein (beispielsweise Webhook Receiver). Dieser Name wird in API Manager und in Betriebsprotokollen angezeigt.

4. URL Prefix: Gib das Basissegment des Pfads für die öffentliche Endpunkt-URL ein (beispielsweise my-webhook).

5. Version: Gib eine Versionsnummer ein (beispielsweise 1.0). Dies wird Teil der Endpunkt-URL.

6. Enable SSL: Aktiviere diese Option, um HTTPS-Verbindungen zu erzwingen. Dies wird für alle Produktions-Endpunkte empfohlen.

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

8. Klicke auf Save.

Schritt 2: Den Service-Endpunkt konfigurieren

1. Klicke im API-Editor auf Add Service.

2. Method: Wähle die HTTP-Methode aus, die das externe System zum Senden des Webhooks verwendet (beispielsweise POST).

3. Path: Gib den Unter-Pfad des Endpunkts ein (beispielsweise /events). Dieser wird an die Basis-URL angehängt.

4. Operation: Wähle den Studio-Betrieb aus, der die eingehende Anfrage verarbeitet.

5. Response Type: Wähle System Variable aus. Mit dieser Einstellung wird der Antwortteil durch den Wert bestimmt, den der Betrieb der Variable $jitterbit.api.response zuweist.

6. Timeout: Lege die maximale Zeit fest, die API Manager auf den Abschluss des Betriebs wartet. Der Standard beträgt 30 Sekunden.

7. Klicke 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. Kopiere diese URL und konfiguriere das externe System so, dass es Webhook-Payloads dorthin sendet.

Teil 2: Auf die Anfrage-Payload im Betrieb zugreifen

Wenn API Manager den verknüpften Betrieb auslöst, werden Jitterbit-Variablen mit den eingehenden Anfragedaten gefüllt. Lese diese Variablen in einem Skriptschritt am Anfang des Betriebs.

Das folgende Beispiel protokolliert den eingehenden Text und URI im Betriebsprotokoll:

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

Um die Payload in einer Transformation zu verwenden, weise sie einer Variable zu und ordne diese Variable als Quelle zu:

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

Anfragen über mehrere Pfade hinweg weiterleiten

Wenn die API mehrere Service-Pfade hat (beispielsweise /createRecord und /updateRecord), kannst du alle Pfade einem einzelnen Controller-Betrieb zuordnen und eine Case()-Anweisung verwenden, um je nach URI zu untergeordneten Betrieben zu verzweigen:

<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 verwaltet.

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 HTTP-Statuscode ungleich 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 der protokollierte Body mit dem Test-Payload übereinstimmt.

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