Verständnis von API und JSON in Vonage AI Studio mit Burger-Beispielen

Grillen - die Grundlagen

In diesem Blog werden wir die Concepts von JSON-Objekten, API-Antworten und Response Mapping in Vonage AI Studio vereinfachen. Wir behandeln diese Themen mit einfachen, nachvollziehbaren Burger-Beispielen (inspiriert von Bob's Burgers). Unabhängig davon, ob Sie ein erfahrener Entwickler oder ein Neuling auf dem Gebiet der API-Integration sind, wird dieser Leitfaden wertvolle Einblicke in die optimale Nutzung der Funktionen von Vonage AI Studio bieten. Wie Linda Belcher sagen würde: "Die wahre Tragödie ist, dass ich keine Zeit habe, Nachos zu holen, bevor wir anfangen".

Verwendung von Webhooks mit Vonage AI Studio

Webhooks sind in modernen Web Applications unverzichtbar und dienen als Kanal für die Datenübertragung in Echtzeit. In Vonage AI Studio ist der Webhook-Knoten eine zentrale Rolle und ermöglicht die Interaktion mit externen Diensten und APIs. In AI Studio fungieren Webhooks als Hörer für Ereignisse von externen Diensten und lösen vordefinierte Aktionen innerhalb Ihrer Workflows aus. Wenn ein Webhook Daten empfängt, können Sie mit der Antwortzuordnungsfunktion bestimmte Informationen aus der Antwort extrahieren und in nachfolgenden Schritten Ihres Workflows verwenden. Diese Fähigkeit ist für die Erstellung dynamischer und reaktionsschneller Anwendungen von entscheidender Bedeutung.

Tricks und Tools zum Auffinden von JSON-Objekten

Das Verstehen und Navigieren durch JSON-Antworten (JavaScript Object Notation) ist eine wichtige Fähigkeit bei der Arbeit mit REST-APIs, einschließlich derer von Vonage. Wie ich bereits erwähnt habe, arbeite ich gerne mit JSON, weil es leicht lesbar und einfach ist. Beim Umgang mit komplexen oder großen JSON-Strukturen kann es jedoch schwierig sein, genau die Daten zu finden, die Sie benötigen. Zum Glück gibt es benutzerfreundliche Tools, die das Auffinden von JSON-Objekten einfach machen, selbst für diejenigen, die noch nicht mit API-Antworten arbeiten.

Was ist ein JSON-Objekt?

Zunächst sollten wir verstehen, was ein JSON-Objekt ist. In seiner einfachsten Form ist ein JSON-Objekt eine Sammlung von Schlüssel-Wert-Paaren, die in geschweifte Klammern eingeschlossen sind {}. Jeder Schlüssel ist ein eindeutiger Bezeichner (in der Regel eine Zeichenkette), und der zugehörige Wert kann eine Zahl, eine Zeichenkette, ein boolescher Wert, ein anderes Objekt, ein Array oder null sein. Zum Beispiel:

{
  "item": "burger",
  "quantity": 2,
  "withFries": true,
  "extras": ["cheese", "lettuce"],
  "specialInstructions": null
}

In diesem JSON-Objekt:

• item (Text): Der bestellte Artikel ist ein "burger".

• quantity (Zahl): Die Menge wird als Zahl dargestellt, 2.

• withFries (boolesch): Dieser Schlüssel gibt an, ob Pommes frites in der Bestellung enthalten sind (true oder false). Hier ist es true.

• extras (Array): Listet die zusätzlichen Toppings als Array auf, einschließlich "cheese" und "lettuce".

• specialInstructions (Null): Wird für alle zusätzlichen Anweisungen verwendet, hat derzeit keinen Wert (null).

Dieses Beispiel bietet eine klare und einfache Darstellung einer Burger-Bestellung, die verschiedene Arten von Werten im JSON-Format verwendet.

In diesem Beispiel, item, quantity, withFries, extras, und specialInstructions sind Schlüssel, und "burger", 2, true, ["cheese", "lettuce"], und null sind ihre jeweiligen Werte.

Navigieren in JSON-Antworten

1. Verstehen der JSON-Struktur: Machen Sie sich zunächst mit der Struktur der JSON-Antwort vertraut. Erkennen Sie die Hierarchie von Objekten und Arrays (Listen von Werten).

2. Formatierung für mehr Klarheit: JSON-Antworten von APIs können manchmal kompakt und schwer zu lesen sein. Verwenden Sie ein Formatierungswerkzeug um das JSON zu "verschönern" und es lesbarer zu machen. Tools wie JSONLint (jsonlint.com) bieten diese Funktionalität. Sie nehmen eine kompakte JSON-Zeichenkette und formatieren sie mit korrekter Einrückung und Zeilenumbrüchen.

Werkzeuge zum Auffinden von JSON-Objekten

1. JSONLint: Wie bereits erwähnt, ist JSONLint hervorragend für die Formatierung von JSON geeignet. Es validiert auch die JSON-Syntax und hilft Ihnen dabei, Fehler zu finden und zu korrigieren, die ein ordnungsgemäßes Parsing verhindern könnten.

2. JSONPath Finder: Für komplexere JSON-Strukturen können Tools wie JSONPath Finder von unschätzbarem Wert sein. Mit diesen Tools können Sie bestimmte Teile des JSON abfragen und extrahieren. Sie geben einen "Pfad" mit einer Abfragesprache ähnlich XPath für XML ein, und das Tool gibt den Teil des JSON zurück, der Ihrer Abfrage entspricht.

Stellen Sie sich vor, Sie möchten wissen, wie viele Aufträge wir heute mit Pommes frites verkauft haben. $.orders[*].withFries. Ähnlich könnten Sie in einer JSON-Antwort von Vonage, die eine Liste von Anrufdatensätzen enthält, die Anrufer-ID aus jedem Datensatz extrahieren wollen. Mit einer JSONPath-Abfrage wie $.calls[*].callerIDkönnen Sie schnell alle Anrufer-IDs aus der Liste abrufen.

Wie man REST-API-Antworten versteht

REST API steht für "Representational State Transfer Application Programming Interface".

• Repräsentative Zustandsübertragung (REST) ist ein architektonischer Stil für die Entwicklung vernetzter Applications. Er basiert auf einem zustandslosen Client-Server-Kommunikationsprotokoll, fast immer HTTP (Hypertext Transfer Protocol).

• Application Programming Interface (API) ist ein Satz von Regeln und Definitionen, die es verschiedenen Software-Applikationen ermöglichen, miteinander zu kommunizieren.

Im Zusammenhang mit Webdiensten bietet eine REST-API Anwendungen die Möglichkeit, mit Webdiensten unter Verwendung von Webprotokollen (z. B. HTTP) zu interagieren, und umfasst in der Regel die Anforderung und Übertragung von Daten unter Verwendung von Operationen wie GET, POST, PUT und DELETE. REST-APIs sind aufgrund ihrer Einfachheit, Skalierbarkeit und Vielseitigkeit weit verbreitet. Das macht sie zum Rückgrat der Webkommunikation, und das Verständnis ihrer Antworten ist der Schlüssel zur erfolgreichen Integration.

API-Antworten kommen oft im JSON-Format. Als visueller Mensch bin ich absolut liebe wie leichtgewichtig und lesbar die JSON-Struktur ist, wenn sie aufgehübscht wird. Wir werden die Feinheiten von REST-API-Antworten untersuchen und die Rolle des JSON-Formats bei der Gewährleistung eines effizienten Datenaustauschs und der Integration mit Vonage AI Studio hervorheben.

Erstellen eines Objektpfads

Bei der Arbeit mit JSON-Antworten von APIs, insbesondere in Tools wie Vonage AI Studio, ist das Verständnis und die Erstellung von "Objektpfaden" eine der wichtigsten Fähigkeiten.

Was ist ein Objektpfad?

Ein Objektpfad ist eine Folge von Schlüsseln, mit denen Sie durch ein JSON-Objekt navigieren, um die gewünschten Daten zu erreichen. Stellen Sie sich einen Objektpfad als eine GPS-Route vor, die Sie genau zu der Information führt, die Sie innerhalb einer JSON-Struktur benötigen. In einem JSON-Objekt, das eine Person darstellt, könnte der Objektpfad zum Auffinden ihrer E-Mail beispielsweise so aussehen person.contact.email.

So konstruieren Sie einen Objektpfad

1. Beginnen Sie mit der Wurzel: Die Wurzel eines JSON-Objekts ist seine äußerste Ebene. Von hier aus ermitteln Sie den ersten Schlüssel, der Sie näher an Ihre Daten heranführt.

2. Durch Ebenen navigieren: Wenn der Wert eines Schlüssels ein anderes Objekt oder ein Array ist, fahren Sie fort, indem Sie den nächsten Schlüssel oder Array-Index angeben.

3. Wiederholen Sie den Vorgang, bis Sie Ihre Daten erreicht haben: Geben Sie so lange Schlüssel oder Indizes ein, bis Sie die gewünschten Daten gefunden haben.

Praktisches Beispiel in Vonage AI Studio

Lassen Sie uns anhand einer einfachen JSON-Antwort veranschaulichen, wie ein Objektpfad konstruiert wird. Stellen Sie sich vor, Sie haben die folgende JSON-Antwort von einer Vonage-API:

{
  "order": {
    "details": {
      "item": "burger",
      "size": "large",
      "customizations": {
        "extras": ["cheese", "lettuce", "tomato"],
        "exclude": ["pickles"],
        "sauces": ["ketchup", "mustard"]
      }
    },
    "customerInfo": {
      "name": "Bob",
      "contact": {
        "email": "bob@bobsburgers.com",
        "phone": "555-6789"
      }
    }
  }
}

• Zielsetzung: Angenommen, wir wollen die ausgeschlossenen Artikel in der Burger-Bestellung extrahieren.

• Konstruktion des erweiterten Objektpfads:

  1. Beginnen Sie an der Wurzel: Der Stammschlüssel ist order.

  2. Erste Schicht: Innerhalb ordernavigieren wir zu details.

  3. Zweite Schicht: Unter detailsfinden wir customizations.

  4. Endstation: Das customizations Objekt enthält den Schlüssel exclude.

• Endgültiger Objektpfad: Der Objektpfad zum Auffinden der Liste der Saucen lautet order.details.customizations.exclude.

Verwendung von Objektpfaden in Vonage AI Studio

In Vonage AI Studio müssen Sie beim Einrichten von Antwort-Mappings oder beim Konfigurieren von Knoten im Webhook-Knoten häufig diese Objektpfade angeben, um dem Studio genau mitzuteilen, wo es die benötigten Daten aus einer API-Antwort finden und extrahieren soll. Objektpfade sind unerlässlich, da sie es Ihnen ermöglichen, nur die Daten zu finden und zu extrahieren, die Sie aus potenziell komplexen JSON-Strukturen benötigen, was Ihre Datenverarbeitung effizient und fehlerfrei macht.

Übergeben/Hinzufügen von Abfrageparametern zu API-Anforderungen

In diesem Abschnitt werden wir untersuchen, wie das Festlegen von Parametern in API-Interaktionen dem Anpassen einer Essensbestellung ähnelt. Genauso wie Sie in einem Restaurant angeben können, wie Sie Ihren Burger haben möchten, können Sie mit Parametern in einer API-Anfrage genau festlegen, welche Daten Sie benötigen. Wir werden dieses Konzept anhand einer einfachen Analogie zur Bestellung eines Burgers erläutern und anhand eines Beispieldatensatzes zeigen, wie es in einem praktischen Szenario angewendet wird.

Beispiel: Eine Burger-Bestellung

Stellen Sie sich vor, Sie sind bei Bob's Burgers und möchten einen Burger bestellen. Du magst aber keine Gurken. Also sagen Sie dem Kellner: "Ich hätte gerne einen Cheeseburger, aber bitte ohne Gewürzgurken." Hier ist "ohne Gewürzgurken" ein spezieller Wunsch oder Parameter, der Ihre Bestellung anpasst.

Was sind Abfrageparameter?

• Analogie zur realen Welt: Abfrageparameter sind wie Ihre Präferenzen bei einer Essensbestellung. Wenn Sie etwas Bestimmtes wünschen, z. B. einen Burger ohne Gurken, legen Sie Parameter für Ihre Bestellung fest.

• In API-Begriffen: Parameter sind die Werte, die Sie mit Ihrer API-Anforderung senden. Sie geben an, welche Informationen Sie von der API benötigen. Wenn Sie beispielsweise Informationen über einen Benutzer anfordern, könnte ein Parameter die ID des Benutzers sein. Mit ihnen können Sie Ihre Datenabfrage anpassen. Die Verwendung von Parametern bedeutet, dass Sie genau und nur das von einer API erhalten, was Sie benötigen.

Übersetzen in API-Parameter

• API-Anfrage: In der Welt der APIs ist eine Anfrage wie eine Bestellung in der Küche. Die Angaben, die Sie machen (z. B. "keine Essiggurken"), sind Parameter, mit denen diese Anfrage angepasst wird.

• Parameter festlegen: Wenn Sie bestimmte Details in Ihrer API-Anfrage angeben, legen Sie Parameter fest. Diese Parameter teilen der API genau mit, wie sie Ihre Daten "aufbereiten" soll.

Einstellen von Parametern in Vonage AI Studio

1. Identifizieren Sie Ihren Datenbedarf: Machen Sie sich klar, welche spezifischen Informationen Sie von der API benötigen und welche Informationen sie liefern kann. Wenn Sie zum Beispiel eine Pizza bei Bob's Burgers bestellen, wird die Küche einen Fehler zurückgeben, da dies kein Abfrageparameter ist, mit dem sie umgehen kann.

2. Verwenden Sie die Oberfläche von Vonage AI Studio: Das Studio bietet eine intuitive Möglichkeit, Parameter zu setzen. Wenn Sie zum Beispiel Benutzerdaten abrufen, können Sie einen Parameter für die "userID" festlegen.

3. Geben Sie Ihre Parameterwerte ein: Diese Werte sollten mit den Daten übereinstimmen, die Sie abrufen wollen. In unserem Beispiel wäre dies die tatsächliche ID des Benutzers.

Beispieldaten für API-Anfrage

Erstellen wir einen Beispieldatensatz, um dies zu veranschaulichen:

{
  "order": {
    "item": "burger",
    "extras": ["cheese", "lettuce", "tomato"],
    "exclude": []
  }
}

Praktisches Beispiel: Anpassen Ihrer Bestellung in Vonage AI Studio

1. Ursprüngliche Bestellung: Anhand der Beispieldaten ist Ihre Erstbestellung ein Burger mit Käse, Salat und Tomate.

2. Parameter für die Anpassung festlegen: Angenommen, Sie möchten keine Gewürzgurken auf Ihrem Burger. In einer API-Einstellung, wie z. B. Vonage AI Studio, würden Sie den Parameter "Exclude" um "Pickles" erweitern.

3. Geänderte Bestelldaten:

   {
     "order": {
       "item": "burger",
       "extras": ["cheese", "lettuce", "tomato"],
       "exclude": ["pickles"]
     }
   }

   Kopieren

4. Das Ergebnis: Die API verarbeitet diese Anfrage und gibt eine Antwort zurück, die Ihre individuelle Bestellung widerspiegelt - einen Burger mit Käse, Salat und Tomate, aber ohne Gurken.

So würde es in einer Datenbanktabelle aussehen:

Kommen Sie auf die Burger-Gästeliste von Vonage

In diesem Artikel haben wir die Grundlagen des Umgangs mit JSON-Objekten, API-Antworten und Response Mapping in Vonage AI Studio anhand von leicht verständlichen, von Bob's Burgers inspirierten Beispielen gelernt. Wenn Ihnen gefallen hat, was Sie gelesen haben, schließen Sie sich unserem "Burgerladen" von Entwicklern auf Slack und folgen Sie uns auf X, früher bekannt als Twitter. Wenn Sie diesen Blog in irgendeiner Weise hilfreich fanden, teilen Sie bitte Ihre Bewertung und taggen Sie mich - Ich würde mich freuen, von Ihrem "Essenserlebnis" zu hören!