Zum Inhalt springen

Einen Vorgang als REST-API in Jitterbit Studio bereitstellen

Einführung

API Manager ermöglicht es dir, einen Studio-Vorgang als HTTP-Endpunkt zu veröffentlichen, den jeder autorisierte Aufrufer bei Bedarf aufrufen kann. Nach der Veröffentlichung akzeptiert der Endpunkt eine HTTP-Anfrage, führt den verknüpften Vorgang synchron aus und gibt die Ausgabe des Vorgangs als HTTP-Antwort zurück.

Dieses Muster ist nützlich, wenn ein externes System oder internes Tool bei Bedarf Daten anfordern oder die Verarbeitung auslösen muss, beispielsweise eine Webanwendung, die Kundendatensätze abfragt, ein Partnersystem, das Bestellungen zur Verarbeitung einreicht, oder ein internes Dashboard, das die Berichtsgenerierung auslöst.

Dieses Handbuch verwendet die in Studio integrierte Option Als API veröffentlichen, die die API-Konfiguration direkt vom Vorgang aus öffnet. Alternativ kann das gleiche Ergebnis über die API-Manager-Benutzeroberfläche erreicht werden (siehe Custom API).

Dieses Handbuch setzt Folgendes voraus:

  • Eine Custom API ist in API Manager in der gleichen Umgebung wie das Projekt konfiguriert und veröffentlicht.
  • Der Vorgang, der als API bereitgestellt werden soll, ist bereits erstellt und bereitgestellt.

Für das ergänzende Muster (Empfang von ereignisgesteuerten Webhook-Pushes von externen Systemen) siehe Einen Studio-Vorgang über einen Webhook auslösen.

Designmuster

%%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart LR A[API-Client] -->|HTTP-Anfrage| B[API Manager Custom API] --> C[Studio-Vorgang] -->|HTTP-Antwort| A

Teil 1: Den Vorgang als API veröffentlichen

Schritt 1: Die API-Konfiguration öffnen

  1. Suche auf der Designoberfläche den Vorgang, den du veröffentlichen möchtest.

  2. Klicke auf das Aktionsmenü-Symbol des Vorgangs und wähle Als API veröffentlichen.

    Die API-Konfigurationsschublade wird unten im Projekt-Designer geöffnet.

    Hinweis

    Diese Option ist nur verfügbar, wenn der Vorgang keine nicht bereitgestellten Änderungen hat. Stelle den Vorgang zuerst bereit, wenn die Option nicht verfügbar ist.

Schritt 2: Das API-Profil konfigurieren

Gib auf dem Schritt Profil die grundlegenden API-Details ein:

  1. API-Name: Gib einen Namen für die interne Identifikation ein (z. B. Customer Query API). Dieser Name wird in API Manager und in Vorgangslogs angezeigt.

  2. Service Root: Gib das Basis-Pfad-Segment ein, das in der öffentlichen Endpunkt-URL verwendet wird (z. B. customers). Dieses Feld wird mit dem Vorgangsnamen in Camel Case vorausgefüllt. Leerzeichen sind nicht erlaubt.

  3. Versionsnummer: Gib eine Versionszeichenfolge ein (z. B. v1). Dies wird Teil der Endpunkt-URL.

  4. Klicke auf Weiter.

Schritt 3: Einstellungen konfigurieren

Konfiguriere auf dem Schritt Einstellungen das Laufzeitverhalten:

  1. Nur SSL: Aktiviert lassen. Dies erfordert HTTPS und wird für alle Produktionsendpunkte empfohlen.

  2. Timeout: Lege die maximale Zeit fest, die API Manager auf die Fertigstellung des Vorgangs wartet, bevor es einen Timeout-Fehler zurückgibt. Der Standard ist 30 Sekunden; das Maximum ist 180 Sekunden.

  3. Ausführliches Logging: Aktiviere während der Entwicklung, um Anfrage- und Antwortdaten in API-Logs einzuschließen. Deaktiviere dies in der Produktion, um große Protokolldateien zu vermeiden.

  4. Klicke auf Weiter.

Schritt 4: Den Service-Endpunkt konfigurieren

Definiere auf dem Schritt Services, wie Aufrufer den Vorgang erreichen:

  1. Methode: Wähle die HTTP-Methode aus, die Aufrufer verwenden werden. Wähle GET für Lesevorgänge. Wähle POST für Vorgänge, die einen Request Body akzeptieren (Dateneingabe, Datensatzerstellung).

  2. Pfad: Gib den Unterpfad ein, der an die Basis-URL angehängt wird (z. B. /records oder /submit).

  3. Antworttyp: Wähle, wie der Vorgang seine Antwort an den Aufrufer zurückgibt:

    • Systemvariable: Der Antworttext ist der Wert, der $jitterbit.api.response im Vorgang zugewiesen wird. Verwende dies in den meisten Fällen, da es volle Kontrolle über den Antwortinhalt und den Statuscode gibt. Siehe Teil 2 für Details.
    • Endgültiges Ziel: Die Antwort ist die Ausgabe einer API Response-Aktivität am Ende der Vorgangskette. Verwende dies, wenn der Vorgang bereits mit einer API Response-Aktivität endet.
    • Keine Antwort: API Manager gibt sofort eine leere 202 Accepted zurück, ohne auf die Fertigstellung des Vorgangs zu warten. Verwende dies für zeitaufwändige Fire-and-Forget-Vorgänge, bei denen der Aufrufer kein Ergebnis benötigt.

  4. Klicken Sie auf Weiter.

Schritt 5: Sicherheitsprofil hinzufügen

Weisen Sie im Schritt Sicherheitsprofile mindestens ein Sicherheitsprofil zu, um den Zugriff auf den Endpunkt einzuschränken.

  1. Um ein vorhandenes Profil zu verwenden, aktivieren Sie den Umschalter Zuweisen daneben.

  2. Um ein neues Profil zu erstellen, klicken Sie auf Neues Sicherheitsprofil und folgen Sie den Anweisungen. API-Schlüssel und Basic-Authentifizierung sind die häufigsten Optionen für Maschine-zu-Maschine-Integrationen. Verwenden Sie OAuth 2.0 für benutzergerichtete APIs, die eine Identität erfordern.

    Tipp

    Wenn Sie den Endpunkt ohne zugewiesenes Sicherheitsprofil belassen, ist er öffentlich für jeden mit der URL zugänglich. Weisen Sie vor der Veröffentlichung in der Produktionsumgebung immer ein Sicherheitsprofil zu.

  3. Klicken Sie auf Weiter.

Schritt 6: Veröffentlichen

  1. Schränken Sie im Schritt Benutzerrollen optional den Zugriff nach Organisationsrolle ein. Klicken Sie auf Weiter, falls keine Rollenbeschränkung erforderlich ist.

  2. Klicken Sie auf Veröffentlichen.

    Die API ist innerhalb von fünf Minuten live. Der API Manager zeigt die vollständige Endpunkt-URL im Format https://<host>/<service-root>/<version>/<path> an. Kopieren Sie diese URL, um sie mit dem API-Aufrufer zu teilen.

    Hinweis

    Eine veröffentlichte API zählt als eine API-URL für Ihr Harmony-Abonnementkontingent. Speichern Sie stattdessen als Entwurf, wenn Sie die Konfiguration vor der Aktivierung des Endpunkts abschließen möchten.

Teil 2: Antwort von der Operation zurückgeben

Wenn der Antworttyp auf Systemvariable eingestellt ist, muss die Operation den Antwortteil $jitterbit.api.response zuweisen, bevor sie abgeschlossen wird. Fügen Sie am Ende der Operation (oder am Ende der Operationskette) einen Skriptschritt hinzu, um diesen Wert festzulegen.

  • JSON-Antwort zurückgeben:

    <trans>
$jitterbit.api.response = JSONStringify($result_dict);
$jitterbit.api.response.status_code = 200;
</trans>

  • Reine Zeichenfolgeantwort zurückgeben:

    <trans>
$jitterbit.api.response = "Processing complete";
$jitterbit.api.response.status_code = 200;
</trans>

  • Fehlerantwort zurückgeben:

    <trans>
$err_response = Dict();
$err_response["error"] = "Record not found";
$jitterbit.api.response = JSONStringify($err_response);
$jitterbit.api.response.status_code = 404;
</trans>

Wenn $jitterbit.api.response nicht vor Abschluss der Operation gesetzt wird, gibt der API Manager eine leere 200 OK-Antwort zurück.

Eine vollständige Liste der API-Jitterbit-Variablen finden Sie unter API-Jitterbit-Variablen.

Integration prüfen

  1. Stellen Sie das Projekt bereit, falls Sie seit der Veröffentlichung Änderungen vorgenommen haben.

  2. Kopieren Sie im API Manager die veröffentlichte Endpunkt-URL von der Seite APIs.

  3. Senden Sie eine Testrequête an den Endpunkt mit einem Tool wie curl oder Postman, einschließlich des entsprechenden Autorisierungsheaders für das zugewiesene Sicherheitsprofil.

  4. Bestätigen Sie, dass der HTTP-Antwortteil und der Statuscode den in der Operation festgelegten Werten entsprechen.

  5. Öffnen Sie die API-Protokolle im API Manager und die Operationsprotokolle in Studio, um zu bestätigen, dass die Anfrage empfangen und die Operation erfolgreich abgeschlossen wurde.

Um der Operation selbst Authentifizierung hinzuzufügen (z. B. um ein JWT in einem Skriptschritt vor der Verarbeitung der Anfrage zu validieren), lesen Sie API-Endpunkte mit JWT authentifizieren.