JSON & Variable Mapper in Legal Bot API Workflows verstehen

API Connector – Teil 3 – Technische Erklärung

Willkommen zum dritten Teil der API-Connector-Reihe. In Teil eins haben wir gelernt, wie man API-Konnektoren zu unserem Konto hinzufügt, und in Teil zwei haben wir gelernt, wie man die API-Konnektoren in einem Bot verwendet, um Wetterbedingungen abzurufen.

In Teil drei werden wir einige technische Details erläutern, die in den vorherigen Tutorials nicht besprochen wurden. Diese zusätzlichen Informationen werden allen Bot-Erstellern, auch ohne IT-Hintergrund, helfen, die Funktion von APIs und Variable Mappern besser zu verstehen.

Um die Wetterinformationen zu erhalten, benötigen wir einen API-Connector-Node. API-Konnektoren sind Tools, die es verschiedenen Softwaresystemen ermöglichen, miteinander zu kommunizieren, indem sie Daten senden und empfangen. Sie fungieren wie Brücken, die Apps und Dienste verbinden, um Informationen auszutauschen. Dies hilft, Aufgaben zu automatisieren und Funktionen plattformübergreifend zu integrieren.

Erinnerst du dich, dass wir AccuWeather als Anbieter mit „Weather – Get City ID“ als unseren Konnektor ausgewählt haben? Die AccuWeather-API verwendet „City IDs“, um bestimmte Orte eindeutig zu identifizieren. Diese IDs sind eindeutige Nummern, die AccuWeather jeder Stadt oder jedem Ort in ihrer Datenbank zuweist, was hilft, Verwechslungen zwischen Städten mit ähnlichen Namen zu vermeiden. Wenn du die AccuWeather-API nach Wetterdaten abfragst, musst du die City ID anstelle des Stadtnamens angeben. Daher bitten wir den API Connector an dieser Stelle, die ID für unsere ausgewählte Stadt herauszufinden, damit wir im nächsten Schritt die Wettervorhersage für diese bestimmte Stadt anfordern können.

Beim Einrichten des API-Konnektors haben wir Get als unsere Konnektor-Methode ausgewählt. Du musst wissen, dass API-Konnektoren Anwendungen ermöglichen, über eine Reihe von Protokollen und Methoden miteinander zu kommunizieren. Diese Methoden bilden die Grundlage dafür, wie APIs Ressourcen auf einem Server verwalten und manipulieren. Je nach Anwendungsfall hätten wir eine oder mehrere der Methoden zur Auswahl.

Die Methoden sind:

• GET, das zum Abrufen von Daten verwendet wird;
• POST, das zum Senden von Daten verwendet wird, um etwas Neues zu erstellen;
• PUT, das eine gesamte Ressource aktualisiert oder ersetzt;
• DELETE, das zum Entfernen einer Ressource verwendet wird; und
• PATCH, das einen Teil einer Ressource aktualisiert.

Zurück zu unserem Beispiel, der Wettervorhersage: Wie der Name schon sagt, versuchen wir, die Wetterdaten von AccuWeather abzurufen. Daher ist unsere einzig logische Methode Get.

Da du den Bot so gestaltest, dass er über verschiedene Wetterbedingungen in Städten berichtet, sollte dein Wert im Konnektor-Konfigurationsfenster als Variable festgelegt werden, und aus dem Dropdown-Menü haben wir die Variable ausgewählt, die in unserem Beispiel Text – City Name ist. Wenn wir jedoch die Wetterbedingungen nur für eine bestimmte Stadt melden wollten, müssten wir Text als Werttyp auswählen und den genauen Stadtnamen in das Feld eingeben.

Auf dem Node siehst du die Abschnitte Content type und Content. Diese beiden Bereiche sind für Fälle gedacht, in denen du eine Form von Inhalt hast, die du deiner Abfrage anhängen möchtest. Zum Beispiel könnte das Aktualisieren einer Liste in SharePoint ein Anwendungsfall sein. Da wir in unserem Beispiel jedoch keine zusätzlichen Informationen zu unserer Abfrage hinzufügen möchten, lassen wir diesen Abschnitt auf None.

Sobald du den Trigger und den Button-Namen festgelegt hast, musst du den Variable Mapper Node hinzufügen. Einfach ausgedrückt, fungiert ein Variable Mapper wie ein Übersetzer, der sicherstellt, dass dein Bot dieselbe „Sprache“ wie die API spricht, was den Informationsaustausch zwischen ihnen erleichtert. In unserem Beispiel extrahiert und formatiert der Mapper die City ID aus der AccuWeather-API-Antwort korrekt.

Jetzt müssen wir die Einstellungen für unseren Variable Mapper vornehmen. Der Quell-Node ist API 1, da wir den Variable Mapper verwenden, um Informationen von API 1 in unser gewünschtes Format zu übersetzen. Für den Quelltyp haben wir die Optionen Text, JSON und File. Da wir keine Dateien extrahieren wollen, wird diese Option weggelassen. Es bleiben uns zwei Optionen: Text und JSON. In unserem Tutorial haben wir gezeigt, dass wir JSON ausgewählt und auch die Variablen gemappt haben.

Um zu erklären, warum wir das getan haben, wählen wir hier stattdessen Text aus und zeigen dir die Ausgabe des Variable Mappers. Wir gehen zur Vorschau und sehen, was der Bot uns als Ergebnis zurückgibt.

Wir geben Frankfurt als unsere Teststadt ein und klicken auf „Get Information“. Du fragst dich vielleicht, was dieses seltsame Stück Text ist? Einfach ausgedrückt, was du hier siehst, ist die Antwort von AccuWeather auf unsere Abfrage nach der City ID im JSON-Format. Was wir tun müssen, ist, es in ein besser lesbares Format umzuwandeln. Technisch gesehen wird dieser Prozess als „Flattening des JSON“ bezeichnet.

Um das JSON zu „flatten“, verwenden wir die Funktion „Extract from JSON“ aus „Map variables“. Kopiere also das vollständige JSON hierher, damit wir es im Bot verwenden können. Gehe zurück zu unserem Variable Mapper Node, ändere den Quelltyp von Text zu JSON. Klicke auf „Map variables“ und dann auf „Extract from JSON“. Wähle „replace all current data with extracted data“ und füge das JSON in das Feld ein. Sobald du auf „Confirm“ klickst, wirst du sehen, dass der Node seine Magie entfaltet, indem er alle JSON-Schlüssel und ihre zugehörigen Variablennamen auflistet.

Erinnerst du dich, dass wir zu diesem Zeitpunkt nur den City ID Schlüssel benötigten? In unserem Beispiel ist der JSON-Schlüssel für die City ID Zero.Key. Du kannst den Variablennamen gerne nach Belieben umbenennen; lösche alle nicht benötigten zusätzlichen JSON-Schlüssel und klicke auf Speichern.

Mit diesen Einstellungen schauen wir uns an, was der Bot im Frontend zurückgibt. Im Text-Node aktualisieren wir das Feld Input und wählen Mapper 1.City ID. Speichere die Änderungen und klicke auf Vorschau. Du siehst, dass wir die exakte City ID ohne den ganzen seltsamen JSON-Text haben.

Bis zu diesem Schritt haben wir gelernt, wie der erste API Connector mithilfe des Variable Mappers die richtige City ID für den Bot extrahiert.

Nun müssen wir diese ID-Nummer verwenden, um Wetterinformationen zu erhalten. In unserem Tutorial haben wir erklärt, dass wir eine logische Bedingung hinzufügen, damit sie als Gateway fungieren kann, das dem API-Node und dem Variable Mapper Node ermöglicht, Informationen für die Verarbeitung im nächsten Schritt zeitnah zu erhalten, um sicherzustellen, dass diese Informationen eine gültige Eingabe für die nächsten Nodes sind.

Im zweiten API-Konnektor wählen wir den Konnektor „Weather current data“. Der für den Konnektor ausgewählte Wert ist „Mapper 1.city ID“, der uns nun die angeforderte City ID liefert, die der Variable Mapper dann in die Informationen übersetzt, die API 2 abruft. Der Rest dieses Prozesses ist dem vorherigen Schritt ziemlich ähnlich.

Wir haben uns angesehen, wie JSON als Quelltyp verwendet werden kann; in diesem Schritt können wir den Anwendungsfall von Text als Quelltyp sehen.

Da wir zusätzlich zur Temperatur auch eine Zusammenfassung der Wetterbedingungen wünschen, werden wir die KI-Ausgabe verwenden, um eine Zusammenfassung für uns zu generieren. Die Auswahl von Text als Quelltyp ermöglicht es uns, die vollständige API-Antwort zu nutzen, die Informationen wie Datum, Wetterbedingungen und Niederschlag enthält.

Der Rest des Bots beinhaltet die logische Bedingung und den AI Output Node, die in anderen Tutorial-Videos ausführlich behandelt werden.