Externe REST-APIs im Jitterbit App Builder konsumieren

Einführung

Dieser Leitfaden gibt einen Überblick darüber, wie man sich mit externen REST-APIs verbindet und diese als Datenquellen innerhalb des App Builders konsumiert. Die Konfiguration des REST-Datenquellenservers wird für alle REST-Endpunkte verwendet.

Die Einrichtung und Nutzung einer REST-Datenquelle umfasst diese Hauptphasen:

1. Erstellen eines REST-Datenquellenservers: Stellen Sie die erste Verbindung zur Basis-URL der REST-API her.

2. Konfigurieren und Hinzufügen von Endpunkten: Definieren Sie die spezifischen API-Endpunkte, auf die Sie zugreifen möchten, einschließlich ihrer Parameter, Header und Methoden.

3. REST-Objekte für vollständige Integration verwenden: Abstrahieren Sie die konfigurierte API in ein REST-Objekt für nahtlose CRUD-Operationen und UI-Integration.

In diesem Leitfaden wird die kostenlose Alpha Vantage Aktien-Daten-API als praktisches Beispiel verwendet.

Erstellen eines REST-Datenquellenservers

Um einen REST-Datenserver zu erstellen, befolgen Sie diese Schritte:

1. Wählen Sie IDE > Datenserver.

2. Klicken Sie auf die Schaltfläche + Server.

3. Geben Sie im Abschnitt Servereinstellungen die folgenden Felder ein:

   • Servername: Geben Sie einen beschreibenden Namen für den Server ein. Verwenden Sie für unser Beispiel Alpha Vantage.

   • Typ: Wählen Sie REST API.

   • URL: Geben Sie die Basis-URL ein, die in der Dokumentation Ihrer API angegeben ist. Für Alpha Vantage ist dies https://www.alphavantage.co/.

     Hinweis

     Spezifische Endpunkte werden in einem späteren Schritt konfiguriert.

   • Anforderungsinhaltstyp und Antwortinhaltstyp: Wählen Sie die Inhaltstypen für Anfrage und Antwort aus. Typischerweise ist dies JSON.

4. (Optional) Erweitern Sie den Abschnitt Sicherheitseinstellungen, wenn Ihre API eine Benutzername/Passwort-Authentifizierung auf Serverebene erfordert.

   Tipp

   Die meisten REST-APIs, einschließlich Alpha Vantage, verwenden einen API-Schlüssel im Header oder in der Abfragezeichenfolge. Dies wird im nächsten Abschnitt konfiguriert.

5. (Optional) Beschreibung: Geben Sie eine Beschreibung für diesen Server ein.

6. Klicken Sie auf die Speichern-Schaltfläche und schließen Sie dann den Dialog. Sie sollten Ihren neuen REST-Datenserver in der Liste sehen.

REST-Endpunkte konfigurieren und hinzufügen

Nachdem Sie den Datenquellenserver erstellt haben, müssen Sie seine Parameter konfigurieren und die API-Endpunkte definieren, auf die Sie zugreifen möchten.

Allgemeine Parameter (Header und Abfragezeichenfolgen) konfigurieren

Sie können Parameter definieren, die für alle Endpunkte auf dem Server gelten, z. B. für die Authentifizierung. Die meisten REST-Dienste erfordern, dass Sie einen API-Schlüssel übergeben.

Um einen allgemeinen Parameter zu konfigurieren, befolgen Sie diese Schritte:

1. Klicken Sie in der Liste Datenserver auf die Schaltfläche Datensatz öffnen für Ihren neuen REST-Datenserver.

2. Klicken Sie im Popup Server unter Servereinstellungen auf das Symbol Endpunkte.

3. Klicken Sie im Panel Webdienstparameter auf die Schaltfläche + Parameter. Eine neue Zeile erscheint.

4. Setzen Sie die Werte basierend auf den Anforderungen Ihrer API. Für unser Beispiel mit Alpha Vantage müssen wir den API-Schlüssel als Abfragezeichenfolgenparameter hinzufügen:

   • Typ: Wählen Sie Abfrage.

   • Name: Geben Sie den Namen des Parameters ein. Verwenden Sie in diesem Beispiel apikey. Der Name muss mit dem übereinstimmen, was die API erwartet.

   • Wert: Fügen Sie Ihren einzigartigen API-Schlüssel ein.

   • Verwendungstyp: (Optional) Wählen Sie einen Verwendungstyp.

5. Klicken Sie auf das -Symbol, um den Parameter zu speichern.

Einen REST-Endpunkt hinzufügen

Nachdem Ihr REST-Datenserver konfiguriert wurde, können Sie spezifische API-Endpunkte hinzufügen.

Um einen Endpunkt hinzuzufügen, befolgen Sie diese Schritte:

1. Klicken Sie im Panel Endpunkte auf die Schaltfläche + Endpunkt. Eine neue Zeile erscheint.

2. Setzen Sie die Werte in der Zeile wie folgt. Für unser Beispiel erstellen wir einen Endpunkt, um ein globales Aktienangebot abzurufen:

   • Name: Geben Sie dem Endpunkt einen beschreibenden Namen. Verwenden Sie in diesem Beispiel global_quote. Dieser Name wird verwendet, um die resultierende Datentabelle im App Builder zu identifizieren.

   • Endpunkt: Geben Sie den Teil der URL ein, der die Ressource angibt. Für dieses Beispiel wird ein globales Angebot abgerufen, indem Sie Folgendes eingeben, das einen Platzhalter {{ticker}} für einen nächsten definierten Parameter enthält:

query?function=GLOBAL_QUOTE&symbol={{ ticker }}

• Methode: Wählen Sie die HTTP-Methode. Wählen Sie in diesem Beispiel GET aus.

• Klicken Sie auf das -Symbol, um den Endpunkt zu speichern.

Definieren Sie endpunktspezifische Parameter

Fügen Sie nun einen Parameter für das Aktien-Ticker-Symbol hinzu, um die Abfrage durchzuführen:

1. Klicken Sie im Panel Web Service Parameters erneut auf + Parameter.

2. Setzen Sie die Werte wie folgt:

   • Typ: Wählen Sie Query.

   • Name: Geben Sie einen Namen für diesen Parameter ein. In diesem Beispiel ticker.

   • Wert: Lassen Sie das Feld leer, da wir dies dynamisch bereitstellen möchten.

   • Nutzungsart: Wählen Sie Input.

   • Testwert: Geben Sie AAPL (für Apple Corp.) zu Testzwecken ein.

3. Klicken Sie auf das -Symbol, um den Parameter zu speichern.

Testen Sie die Verbindung

Testen Sie schließlich den Endpunkt, um sicherzustellen, dass Ihre Konfiguration korrekt ist.

1. Wählen Sie im Panel Endpoints den neu erstellten global_quote-Endpunkt aus.

2. Klicken Sie auf Testverbindung, dann auf Fortfahren.

Wenn die Konfiguration korrekt ist, wird eine Nachricht "Verbindungstest bestanden" angezeigt, und die von der API zurückgegebenen Daten (die Informationen für AAPL) werden im Abschnitt Text Results angezeigt.

Ihr API-Endpunkt ist jetzt verbunden. Der App Builder erstellt automatisch eine Datentabelle mit dem Namen global_quote (aus dem Endpunktnamen) in der Alpha Vantage-Datenquelle, die Sie nun verwenden können, um UI-Komponenten zu erstellen.

Alternative: Importieren aus einem OpenAPI-Dokument

Wenn Sie ein OpenAPI (Swagger)-Dokument für Ihre REST-API haben, können Sie es importieren, um automatisch Endpunkte zu generieren. Siehe Importieren eines OpenAPI-Dokuments für detaillierte Anweisungen.

Verwenden Sie REST-Objekte für eine vollständige Integration

REST-Objekte ermöglichen es Entwicklern des App Builders, REST-APIs ähnlich wie App Builder-Datenobjekte zu nutzen, wodurch vollständige CRUD (Create, Read, Update, Delete)-Operationen, benutzerdefinierte Ereignisse und eine erweiterte UI-Integration ermöglicht werden.

Für REST-APIs, die CRUD-ähnliche Operationen unterstützen, ist die Konfiguration eines REST-Objekts eine einfache Möglichkeit, eine API mit Ihrer App Builder-App zu integrieren.

CRUD-Endpunkte konfigurieren

Für eine CRUD-ähnliche REST-API müssen Sie Endpunkte konfigurieren, die es ermöglichen, dass Datensätze die Operationen Erstellen, Lesen, Aktualisieren und Löschen durchlaufen. Dies umfasst typischerweise die Einrichtung der folgenden Endpunkte in Ihrer REST-Datenquelle:

Befolgen Sie die Schritte in Fügen Sie einen REST-Endpunkt hinzu für jede CRUD-Operation, die Sie benötigen, und geben Sie den entsprechenden Namen, Endpunkt, Methode und alle erforderlichen Beispielfelder für POST- oder PUT-Methoden an.

Ein REST-Objekt erstellen

Nachdem Ihre CRUD-Endpunkte konfiguriert wurden, können Sie das REST-Objekt erstellen.

1. Wählen Sie IDE > Datenserver.

2. Wählen Sie Ihren REST-Datenserver aus und klicken Sie dann auf Datensatz öffnen für die REST-API. Das Popup REST-API öffnet sich.

3. Klicken Sie unter REST-API auf Endpunkte.

4. Klicken Sie unter Webdienst auf Mehr > Superobjekte. Der Dialog REST-Objekte öffnet sich.

5. Klicken Sie auf + REST-Objekt.

6. Geben Sie einen Namen für Ihr REST-Objekt ein (zum Beispiel Kunden), und klicken Sie dann auf das Speichern-Symbol.

7. Klicken Sie auf das Bleistift-Bearbeiten-Symbol, aktivieren Sie Einfügen, Aktualisieren und Löschen nach Bedarf, und klicken Sie dann erneut auf das Speichern-Symbol.

Konfigurieren und Binden des REST-Objekts

Nachdem Sie das REST-Objekt erstellt haben, müssen Sie dessen Single Comp und Many Comp konfigurieren und die CRUD-Operationen an Ihre Endpunkte binden.

1. Single und Many Comps konfigurieren: Öffnen Sie das REST-Objekt und konfigurieren Sie die Single Comp und Many Comp, indem Sie die entsprechenden Tabellen (zum Beispiel customers(get)/items) und Spalten von Ihrem Lese-Endpunkt hinzufügen.

2. CRUD-Endpunkte konfigurieren: Wählen Sie für jede CRUD-Operation (Löschen, Einfügen, Aktualisieren) den entsprechenden Endpunkt aus, den Sie erstellt haben, und binden Sie die Felder aus dem REST-Objekt an die Eingabeparameter des Endpunkts.

Sie sollten nun in der Lage sein, dieses REST-Objekt in der Benutzeroberfläche Ihrer Anwendung zu verwenden und Zeilen hinzuzufügen, zu löschen oder zu aktualisieren, als ob es sich um eine native App Builder-Tabelle handelt.

Erweiterte Funktionen: Sortierung, Paging und Filterung

REST-Objekte unterstützen auch erweiterte Dateninteraktionsfunktionen. Um diese zu aktivieren, müssen Sie spezifische Parameter in Ihrer REST-Datenquelle mit dem richtigen Nutzungstyp konfigurieren:

• Sortierung: Fügen Sie einen Parameter mit dem Nutzungstyp Request Sort hinzu. Der Parametername sollte dem entsprechen, was Ihre API erwartet (zum Beispiel, $sort).

• Paging: Konfigurieren Sie Parameter für Request Limit, Request Offset (oder Request Page Number) und Request Count. Sie müssen auch den Nutzungstyp der count-Spalte in Ihrer Antworttabelle auf Response Total Rows setzen.

• Filterung: Fügen Sie einen Parameter mit dem Nutzungstyp Request Filter (OData) für die OData-ähnliche Filterung hinzu. Der Parametername sollte dem entsprechen, was Ihre API erwartet (zum Beispiel, $filter).