So erstellen und konfigurieren Sie eine HTTP-Connector-Funktion

Erfahren Sie, wie Sie durch das Modal für die Verbindungsfunktion und den Erstellungsprozess navigieren.

Übersicht

Connector-Funktionen sind eine Funktion zur Strukturierung der Interaktion von Tulip-Anwendungen mit externen Servern und Diensten. Während ein Connector die allgemeine Verbindung zwischen Tulip und dem externen Server ist, sind Connector-Funktionen spezifische Anfragen für Dienste oder Informationen. In diesem Artikel zeigen wir Ihnen, wie Sie eine Connector-Funktion erstellen und konfigurieren, um auf bestimmte Daten oder Informationen von einem externen Dienst zuzugreifen.

Informationen über die Grundlagen von APIs finden Sie in diesem Artikel über die Verwendung einer API.

Einrichten

Bevor Sie eine Connector-Funktion erstellen, müssen Sie einen HTTP-Connector erstellen, um eine Verbindung zwischen Ihren Anwendungen und dem Dienst herzustellen, mit dem Sie kommunizieren möchten. Sie erstellen Ihre Konnektor-Funktionen innerhalb dieses Konnektors, und jede Konnektor-Funktion innerhalb eines Konnektors teilt die Konfiguration des übergeordneten Konnektors. Um einen HTTP-Konnektor zu erstellen, folgen Sie den Schritten in diesem Artikel: So konfigurieren Sie einen Connector.

Nachdem Sie einen Connector erstellt haben, ist es an der Zeit, Connector-Funktionen zu erstellen. Konnektorfunktionen sind die einzelnen Vorgänge, die Ihr Konnektor durchläuft, um Daten von dem API-Server abzurufen, mit dem Sie sich verbinden.

Erstellen Sie eine Connector-Funktion

Wählen Sie auf der Seite Konnektoren den Konnektor aus, mit dem Sie arbeiten möchten, indem Sie auf seinen Namen klicken.

Auf dieser Seite wird eine Liste der mit dem Konnektor verbundenen Funktionen angezeigt. Um eine neue Verbindungsfunktion zu erstellen, klicken Sie auf + Funktion erstellen.

Bevor wir eine neue Funktion erstellen, ist es hilfreich, sich mit dem Editor für Konnektorenfunktionen vertraut zu machen, der in diesem Artikel beschrieben wird: .:::(Internal) (Private Notizen) Artikel zur Übersicht über Verbindungsfunktionen hier einfügen :::

Um die Dinge kurz zu halten, gehen wir in diesem Artikel davon aus, dass Sie die verschiedenen Teile des Anschlussfunktionseditors bereits kennen.

Hier ist der Prozess, den wir verwenden werden, um eine Verbindungsfunktion einzurichten:

1. Wählen Sie den Typ {{Glossar.API-Aufruf}}
2. Schreiben Sie die API-URL
3. Legen Sie die Eingaben fest
4. Definieren Sie die Parameter für die zurückgegebenen Daten
5. Festlegen der Ausgaben in Punktnotation

Aufruftyp und URL

Die ersten beiden Elemente, die für jede HTTP-Connector-Funktion konfiguriert werden müssen, sind der API-Aufruftyp (GET, POST, PUT usw.) und die Endpunkt-URL. Wählen Sie aus der Liste der Aufruftypen aus, indem Sie die Dropdown-Liste verwenden, und geben Sie den Endpunktpfad in das Feld nach der Basis-URL ein. In der API-Dokumentation des Dienstes, mit dem Sie eine Verbindung herstellen möchten, finden Sie eine Liste der Endpunkt- und Konfigurationsdetails.

:::(Info) (HINWEIS) In diesem Artikel verwenden wir ein Stück Fachjargon: API-Aufruf. Ein API-Aufruf oder eine API-Anfrage ist eine Nachricht, die an einen Server gesendet wird und eine API auffordert, einen Dienst oder Informationen bereitzustellen. Da APIs eine Möglichkeit für ein Programm sind, mit einem anderen zu interagieren, sind Aufrufe der Prozess, durch den eine Anwendung eine Anfrage an eine andere Anwendung sendet. :::

In diesem Artikel verwenden wir als Beispiel die Document360 API, den Dienst, der die Wissensdatenbank von Tulip hostet. Die Funktion, die wir einrichten, gibt einen Artikel zusammen mit den zugehörigen Eigenschaften auf der Grundlage der ID des Artikels zurück.

Benennen wir unsere Funktion, legen wir den Aufruftyp (GET) fest und geben wir die URL für den Aufruf ein:

:::(Info) (HINWEIS) Bei der Aufruf-URL wird zwischen Groß- und Kleinschreibung unterschieden. Achten Sie darauf, dass Sie sie genau so eingeben, wie sie in der API-Dokumentation aufgeführt ist:::

Holen Sie sich den Aufruftyp und die URL aus der Endpunktdokumentation Ihres Systems. Diese beiden Aktionen bestimmen Ihre REST-Anfrage. Einen detaillierten Überblick über eine REST-Anfrage finden Sie unter Anatomie einer REST-Anfrage.

Wenn Sie auf Test klicken, wird die Funktion ausgeführt und die Informationen werden im Abschnitt Testergebnisse des Editors angezeigt. Wenn Sie unter Testergebnisse Body auswählen, können Sie das vollständige, ungefilterte Ergebnis Ihrer Anfrage anzeigen. Großartig, wir haben Daten!

{{Glossar.Input}}s

So wie unsere Konnektor-Funktion derzeit konfiguriert ist, können wir nur eine bestimmte Artikel-ID abrufen.

Unser Ziel mit dieser Funktion ist es, sie so zu konfigurieren, dass sie Informationen zu jedem Artikel liefert, an dem wir interessiert sind. Zu diesem Zweck müssen wir unsere Funktion so bearbeiten, dass wir einen Wert für eine beliebige Artikel-ID übergeben können.

Wir können unsere Konnektorfunktion so bearbeiten, dass sie jeden Wert annimmt, indem wir Inputs konfigurieren. Mit Inputs können Sie Werte aus Ihren Anwendungen übernehmen und an Connector-Funktionen übergeben.

Eingaben werden in zwei Teilen konfiguriert: 1.) Erstellen einer Eingabe im Eingabebereich, 2.) Festlegen, wo diese Eingabe in der Konnektorfunktion verwendet werden soll.

Fügen Sie zunächst ein Feld in den Eingabebereich ein. Sie können den Datentyp einer Eingabe bearbeiten, indem Sie auf das Symbol neben dem Namen der Eingabe klicken. Vergewissern Sie sich, dass der von Ihnen gewählte Typ dem Typ der Quelle entspricht, die Sie in Ihren Anwendungen verwenden werden. Das Feld neben dem Eingabenamen kann zum Testen von Werten verwendet werden, die Sie an Ihre Konnektorfunktion übergeben möchten, und kann Eingaben aus Ihren Anwendungen simulieren.

Als Nächstes müssen wir angeben, wo diese Eingabe in unserer Konnektorfunktion verwendet werden soll. Auf Eingaben kann überall in einer Konnektorfunktion zugegriffen werden, einschließlich in der Endpunkt-URL, in Abfrageparametern und in JSON-Extraktoren in den Ausgaben. Weitere Informationen darüber, wie eine bestimmte Funktion konfiguriert werden muss, finden Sie in der API-Dokumentation für jeden Dienst, den Sie verwenden möchten.

In unserem Beispiel können wir auf einen bestimmten Artikel zugreifen, indem wir ihn am Ende des Endpunktpfads oder anstelle von "{articleId}" angeben.

Mithilfe von Eingaben können wir dieser URL dynamisch einen Wert übergeben und so diese Konnektorfunktion verwenden, um Informationen über jeden gewünschten Artikel zu erhalten.

Wir fügen Eingaben in den Endpunktpfad ein, indem wir ein Dollarzeichen**($**) vor und nach dem Parameter (in diesem Fall "ID") einfügen. Bei der Zeichenkette zwischen den Dollarzeichen wird zwischen Groß- und Kleinschreibung unterschieden, und sie muss exakt mit dem Namen Ihrer Eingabe übereinstimmen. Kehren wir zu unserem Beispiel zurück und ändern wir die URL so, dass die ID mit unserer Eingabe übereinstimmt. Der Text zwischen den Dollarzeichen wird zu einem Block, der eine Eigenschaft angibt, etwa so:

Jetzt können wir die ID als Eingabewert festlegen, anstatt den Wert direkt in die Endpunkt-URL zu kodieren.

Um weitere Eingaben hinzuzufügen, klicken Sie auf das + in der oberen rechten Ecke des Eingabefeldes.

Parameter

Abfrageparameter sind Schlüssel-Wert-Paare, die nach dem ? im Endpunkt oder unter Abfrageparameter beim Erstellen einer Connector-Funktion erscheinen.

Nachdem wir nun unsere Eingaben eingerichtet haben, können Sie einige Parameter erstellen, um die Testergebnisse zu ändern und sicherzustellen, dass Sie nur die gewünschten Informationen erhalten. Die Schlüssel und Werte für diese Parameter finden Sie in der API-Dokumentation des Servers, mit dem Sie sich verbinden.

Bei Schlüssel-Wert-Paaren ist eine der Komponenten ein "Schlüssel" und die andere ist der "Wert"; beide werden am Ende der URL Ihres Formulars hinzugefügt. Stellen Sie sich diese Paare wie Token in einer E-Mail vor, um den Namen einer Person zu personalisieren. Mit Hilfe von Schlüssel-Wert-Paaren können Sie Informationen an ein Formular weitergeben.

Der Schlüssel gibt einen Variablennamen an.

Der Wert gibt einen Eigenschaftswert an.

In diesem Beispiel möchten wir einen Parameter festlegen, der sicherstellt, dass der zurückgegebene Artikel auf der Knowledge Base-Website veröffentlicht wird. Wenn Sie die in der API-Dokumentation angegebenen Informationen eingeben, sieht der Parameter wie folgt aus

Diese Abfrage- und Anforderungsparameter sind optionale Felder, die Sie ausfüllen können, aber sie verleihen den Testergebnissen bei Bedarf mehr Spezifität.

{Output}}s

Die Ausgaben sind der Teil der Konnektorfunktion, der zeigt, welche Informationen direkt zurückgegeben werden. Sie sind in Punktnotation strukturiert. Achten Sie also genau auf das Format der Testergebnisse, um zu überprüfen, ob Ihre Notation einem genauen Pfad folgt. Die Ausgaben entsprechen den Variablen in den Anwendungen. Stellen Sie also sicher, dass Sie ihnen einen identifizierbaren und eindeutigen Namen geben.

Beachten Sie, dass Sie die Art der Ausgabe in Listen ändern können, indem Sie den Schalter Liste verwenden; diese Option verschachtelt variable Ausgaben innerhalb von Objekten und ordnet den Pfad der Punktnotation universell für alle verschachtelten Ausgaben in einer Objektliste zu.

Um festzustellen, ob Ihre Ausgaben korrekt zugeordnet sind, klicken Sie im Bereich Testergebnisse auf die Registerkarte Ausgaben und notieren Sie die Ergebnisse, die zurückgegeben werden.

Wenn die Ausgänge mit den Ergebnissen übereinstimmen, dann herzlichen Glückwunsch! Sie haben erfolgreich eine funktionierende Konnektorfunktion erstellt und können sie nun in Anwendungen verwenden. Die nächsten Schritte finden Sie unter Verwendung von HTTP-Konnektoren in Anwendungen.

Wenn Sie Probleme haben, dass Ihre Konnektorfunktion nicht richtig funktioniert, finden Sie in unserem Troubleshooting Guide Informationen darüber, was falsch laufen könnte.

Nehmen Sie am HTTP Connectors University Kurs teil, um einen Überblick über die Erstellung von Konnektoren zu erhalten.

Weitere Lektüre

• Ein Überblick über HTTP-Konnektoren
• Wie man HTTP-Konnektor-Ausgaben formatiert

Haben Sie gefunden, wonach Sie gesucht haben?

Sie können auch zu community.tulip.co gehen und Ihre Frage stellen oder sehen, ob andere eine ähnliche Frage hatten!