REST-API mit dem HTTP v2-Connector in Jitterbit Studio aufrufen

Einführung

Der HTTP v2-Connector ermöglicht den Zugriff über das HTTP- oder HTTPS-Protokoll auf Dienste wie REST-APIs, GraphQL-APIs und Web-Formulare.

Dieses Handbuch behandelt zwei häufige Muster für die Arbeit mit REST-APIs in Studio:

• Verwendung einer HTTP v2 GET-Aktivität als Quelle zum Abrufen von Daten von einem REST-API-Endpunkt.
• Verwendung einer HTTP v2 POST-Aktivität als Ziel zum Senden von Daten an einen REST-API-Endpunkt, einschließlich Webhooks.

Die gleichen Prinzipien gelten für die Aktivitätstypen PUT, PATCH und DELETE.

HTTP v2-Verbindung konfigurieren

Konfiguriere vor dem Erstellen von HTTP v2-Aktivitäten eine Verbindung zur REST-API.

1. Öffne in Studio ein Projekt und klicke auf die Registerkarte Projektendpunkte und Connectors in der Design-Komponentenpalette.

2. Klicke auf den HTTP v2-Connector, um den Verbindungskonfigurationsbildschirm zu öffnen.

3. Connection Name: Gib einen eindeutigen Namen ein, der den REST-API-Dienst identifiziert, z. B. Customer API. Der Name darf keine Schrägstriche / oder Doppelpunkte : enthalten.

4. Base URL: Gib die Basis-URL der API ein, z. B. https://api.example.com/v1. Einzelne Aktivitäten können diese URL mit einem Pfadsuffix erweitern oder sie ganz durch eine vollständige URL ersetzen.

5. Authorization: Wähle im Menü den von der API erforderlichen Authentifizierungstyp aus. Häufige Optionen sind:

   • No Auth: Für öffentliche Endpunkte, die keine Authentifizierung erfordern.
   • API Key: Sendet ein Schlüssel-Wert-Paar als Header oder Abfrageparameter.
   • Bearer Token: Sendet einen Bearer-Token im Header Authorization.
   • Basic Auth: Sendet einen Base64-codierten Benutzernamen und ein Passwort im Header Authorization.

   Eine vollständige Beschreibung aller Authentifizierungstypen findest du unter HTTP v2-Verbindungs-Authentifizierungstypen.

   Tipp

   Verbindungsfelder unterstützen Projektvariablen. Verwende Projektvariablen für Anmeldedaten wie API-Schlüssel, Bearer-Tokens und Passwörter, um zu vermeiden, dass vertrauliche Werte direkt in der Verbindungskonfiguration gespeichert werden.

6. Klicke auf Test, um die Verbindung zu überprüfen. Ein Test ist erfolgreich, wenn die API einen beliebigen 2xx-Statuscode zurückgibt (oder 405 Method Not Allowed).

7. Klicke auf Save Changes.

Daten mit einer GET-Anfrage abrufen

Eine HTTP v2 GET-Aktivität wird als Quelle in einer Operation verwendet. Sie sendet eine HTTP GET-Anfrage an die REST-API und stellt die Antwort als Eingabe für den nächsten Schritt in der Operation bereit, normalerweise eine Transformation.

Die Operation folgt dem Transformationsmuster:

GET-Aktivität erstellen

Erweitere in der Design-Komponentenpalette den HTTP v2-Endpunkt, den du erstellt hast. Ziehe den Aktivitätstyp GET auf die Design-Leinwand, um eine Aktivitätsinstanz zu erstellen. Doppelklick auf die Aktivität, um ihre Konfiguration zu öffnen.

Schritt 1: Namen eingeben und Einstellungen festlegen

1. Name: Gib einen eindeutigen Namen für die Aktivität ein, z. B. Get Customer.

2. Path: Gib den Ressourcenpfad relativ zur Base URL ein, z. B. /customers/{id}. Die vollständige Runtime-URL wird im Feld URL unter Path angezeigt.

   • Wenn das Feld leer gelassen wird, wird die Base URL aus der Verbindung zur Laufzeit verwendet.
   • Ein Teilpfad wird an die Base URL angehängt.
   • Eine vollständige URL setzt die Base URL außer Kraft.

Um einen Pfadparameter einzufügen, schließen Sie ihn in geschweifte Klammern ein, beispielsweise {id}. Weitere Informationen finden Sie unter Variablen im URL-Pfad verwenden weiter unten.

1. Anfrageparameter: Klicken Sie auf das Hinzufügungssymbol , um Abfrageparameter als Schlüssel-Wert-Paare hinzuzufügen, beispielsweise limit / 100. Anfrageparameter werden automatisch URL-codiert.

2. Anfrage-Header: Klicken Sie auf das Hinzufügungssymbol , um Anfrage-Header als Schlüssel-Wert-Paare hinzuzufügen, beispielsweise Accept / application/json. Hier definierte Header werden zusätzlich zu allen auf der Verbindung definierten Headern angewendet.

3. Klicken Sie auf Weiter.

Schritte 2 und 3: Schemas bereitstellen

In Schritt 2 können Sie ein benutzerdefiniertes Anfrageschema bereitstellen (optional für GET-Anfragen, die normalerweise keinen Haupttext haben). In Schritt 3 können Sie ein benutzerdefiniertes Antwortschema bereitstellen.

Wenn die REST-API eine bekannte JSON-Struktur zurückgibt, stellen Sie in Schritt 3 ein benutzerdefiniertes JSON-Schema bereit, indem Sie Ja, neues Schema bereitstellen auswählen und das Schema eingeben oder einfügen. Dies ermöglicht der Transformation, einzelne Felder aus der API-Antwort zuzuordnen.

Wenn kein benutzerdefiniertes Antwortschema bereitgestellt wird, kommt das Standardantwortschema des Connectors zur Anwendung. Das Standardschema zeigt den gesamten Antwortkörper als ein einzelnes Feld responseContent an.

Schritt 4: Überprüfen Sie die Datenschemas

Die konfigurierten Anfrage- und Antwortschemas werden angezeigt. Klicken Sie auf Fertig, um die Aktivitätskonfiguration zu speichern. Die Schemas sind auch in allen benachbarten Transformationen auf der Designfläche verfügbar.

Greifen Sie auf die Antwort in einer Transformation zu

Ordnen Sie in der nachgelagerten Transformation Felder aus dem Antwortschema der GET-Aktivität dem Zielschema zu:

• Wenn ein benutzerdefiniertes Antwortschema bereitgestellt wurde, sind die einzelnen Felder aus der geparsten JSON-Antwort zur Zuordnung verfügbar.
• Wenn das Standardantwortschema verwendet wird, enthält das Feld responseContent den rohen Antwortkörper als Zeichenfolge. Verwenden Sie bei Bedarf die Funktion JSONParser in einem Skript, um es zu parsen.

Daten mit einer POST-Anfrage senden

Eine HTTP v2 POST-Aktivität wird als Ziel in einem Vorgang verwendet. Eine Transformation ordnet Quelldaten dem POST-Anfragekörper zu, und die Aktivität sendet diese an den REST-API-Endpunkt. Dieses Muster gilt auch für das Senden von Daten an Webhook-Endpunkte.

Der Vorgang folgt dem Transformationsmuster:

Erstellen Sie eine POST-Aktivität

Ziehen Sie auf der Designkomponentenpalette den Aktivitätstyp POST vom HTTP v2-Endpunkt auf die Designfläche. Doppelklicken Sie auf die Aktivität, um ihre Konfiguration zu öffnen.

Schritt 1: Geben Sie einen Namen ein und legen Sie Einstellungen fest

1. Name: Geben Sie einen eindeutigen Namen für die Aktivität ein, beispielsweise Bestellung erstellen.

2. Pfad: Geben Sie den Ressourcenpfad relativ zur Basis-URL ein, beispielsweise /orders. Um an einen Webhook zu senden, geben Sie hier die vollständige Webhook-URL ein: Eine vollständige URL setzt die Basis-URL aus der Verbindung außer Kraft.

3. Anfrage-Header: Fügen Sie alle vom API erforderlichen Header hinzu. Fügen Sie für REST-APIs, die JSON akzeptieren, Content-Type / application/json hinzu.

4. Klicken Sie auf Weiter.

Schritte 2 und 3: Schemas bereitstellen

Schritt 2 (Anfrageschema) definiert die Struktur des Anfragekörpers. Schritt 3 (Antwortschema) ist optional und erfasst die Antwort des API.

Um die Struktur des Anfragekörpers zu definieren:

1. Wählen Sie in Schritt 2 Yes, Provide New Schema und geben Sie das JSON-Schema ein oder fügen Sie es ein, das dem erwarteten Anforderungstext der API entspricht. Die Felder in diesem Schema stehen in der vorgelagerten Transformation zur Zuordnung zur Verfügung.

2. Geben Sie in Schritt 3 optional ein Antwortschema an, um Felder zu erfassen, die von der API zurückgegeben werden, z. B. eine erstellte Ressourcen-ID.

3. Klicken Sie auf Finished.

Quelldaten dem Anforderungstext zuordnen

Ordnen Sie in der vorgelagerten Transformation Quellenfelder den Feldern zu, die im Anforderungsschema der Aktivität POST definiert sind. Die Transformationsausgabe wird zur Laufzeit zum HTTP-Anforderungstext.

Variablen im URL-Pfad verwenden

URL-Pfade können mit drei Techniken dynamisch gestaltet werden:

• Pfadparameter sind Platzhalter im Feld Path, die in geschweifte Klammern eingeschlossen sind, z. B. /customers/{customerId}. Zur Laufzeit ersetzt der Connector den Wert des entsprechenden Felds aus dem Anforderungsschema. Ordnen Sie in der vorgelagerten Transformation den Quellwert dem Feld customerId im Anforderungsschema zu.

• Projektvariablen können überall dort verwendet werden, wo ein Variablensymbol in den Verbindungs- oder Aktivitätsfeldern angezeigt wird. Geben Sie eine öffnende eckige Klammer [ in das Feld ein oder klicken Sie auf das Variablensymbol, um eine Projektvariable auszuwählen. Dies ist nützlich für umgebungsspezifische Werte wie eine Basis-URL, die sich zwischen Entwicklung und Produktion unterscheidet. Weitere Informationen finden Sie unter Projektvariablen.

• Globale Variablen können von einem Skript festgelegt werden, das vor dem HTTP v2-Vorgang in einer Operation Chain ausgeführt wird. Das Skript weist einer globalen Variablen einen Wert zu (z. B. $gv_customer_id = "12345"), und das Feld Path verweist auf die Variable (z. B. /customers/$gv_customer_id). Weitere Informationen finden Sie unter globale Variablen.