Comprendre l'API et JSON dans Vonage AI Studio avec des exemples de Burger

Les bases de la grillade

Dans ce blog, nous allons simplifier les concepts d'objets JSON, de réponses API et de mappage de réponses dans Vonage AI Studio. Nous aborderons ces sujets à l'aide d'exemples de burgers simples et réalistes (inspirés de l'émission Bob's Burgers). Que vous soyez un développeur chevronné ou un novice en matière d'intégrations API, ce guide vous fournira des indications précieuses pour tirer le meilleur parti des capacités de Vonage AI Studio. Comme le dirait Linda Belcher : " La vraie tragédie, c'est que je n'ai pas le temps d'acheter des nachos avant de commencer ".

Comment utiliser les Webhooks avec Vonage AI Studio

Les webhooks sont essentiels dans les applications web modernes, car ils servent de canal pour la transmission de données en temps réel. Dans Vonage AI Studio, le nœud nœud webhooks joue un rôle essentiel en permettant des interactions avec des services externes et des API. Dans AI Studio, les webhooks agissent comme des auditeurs d'événements provenant de services externes, déclenchant des actions prédéfinies au sein de vos flux de travail. Lorsqu'un webhook reçoit des données, la fonction de mappage de la réponse vous permet d'extraire des informations spécifiques de la réponse et de les utiliser dans les étapes suivantes de votre flux de travail. Cette capacité est cruciale pour créer des applications dynamiques et réactives.

Trucs et outils pour localiser les objets JSON

Comprendre et naviguer dans les réponses JSON (JavaScript Object Notation) est une compétence essentielle lorsque l'on travaille avec des API REST, y compris celles de Vonage. Comme je l'ai mentionné précédemment, j'aime travailler avec JSON en raison de sa lisibilité et de sa simplicité. Cependant, lorsqu'il s'agit de structures JSON complexes ou volumineuses, il peut être difficile de trouver les données exactes dont vous avez besoin. Heureusement, il existe des outils conviviaux qui facilitent la localisation des objets JSON, même pour ceux qui n'ont pas l'habitude de travailler avec des réponses d'API.

Qu'est-ce qu'un objet JSON ?

Tout d'abord, il convient de comprendre ce qu'est un objet JSON. Dans sa forme la plus simple, un objet JSON est une collection de paires clé-valeur entre accolades {}. Chaque clé est un identifiant unique (généralement une chaîne), et la valeur qui lui est associée peut être un nombre, une chaîne, un booléen, un autre objet, un tableau ou null. Par exemple :

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

Dans cet objet JSON :

• item (Texte) : L'article commandé est un "burger".

• quantity (Nombre) : La quantité est représentée par un nombre, 2.

• withFries (booléen) : Cette clé indique si les frites sont incluses dans la commande (true ou false). Ici, c'est true.

• extras (tableau) : Liste les garnitures supplémentaires sous la forme d'un tableau, y compris "cheese" et "lettuce".

• specialInstructions (Nul) : Utilisé pour toute instruction supplémentaire, n'a actuellement aucune valeur (null).

Cet exemple fournit une représentation claire et simple d'une commande de hamburger, en utilisant différents types de valeurs au format JSON.

Dans cet exemple, item, quantity, withFries, extras, et specialInstructions sont des clés, et "burger", 2, true, ["cheese", "lettuce"], et null sont leurs valeurs respectives.

Comment naviguer dans les réponses JSON

1. Comprendre la structure JSON : Commencez par vous familiariser avec la structure de la réponse JSON. Identifiez la hiérarchie des objets et des tableaux (listes de valeurs).

2. Formatage pour plus de clarté : Les réponses JSON des API peuvent parfois être compactes et difficiles à lire. Utilisez un outil de formatage pour "embellir" le JSON et le rendre plus lisible. Des outils tels que JSONLint (jsonlint.com) offrent cette fonctionnalité. Ils prennent une chaîne JSON compacte et la formatent avec une indentation et des sauts de ligne appropriés.

Outils de localisation des objets JSON

1. JSONLint : Comme nous l'avons mentionné, JSONLint est très utile pour formater JSON. Il valide également la syntaxe JSON, ce qui vous aide à détecter et à corriger les erreurs susceptibles d'empêcher une analyse correcte.

2. JSONPath Finder : Pour les structures JSON plus complexes, des outils tels que JSONPath Finder peuvent s'avérer inestimables. Ces outils vous permettent d'interroger et d'extraire des parties spécifiques du JSON. Vous saisissez un "chemin" à l'aide d'un langage d'interrogation similaire à XPath pour XML, et l'outil renvoie la partie du JSON qui correspond à votre requête.

En reprenant l'exemple des commandes, imaginons que nous voulions savoir combien de commandes nous avons vendues avec des frites aujourd'hui. $.orders[*].withFries. De même, dans une réponse JSON de Vonage comprenant une liste d'enregistrements d'appels, vous pourriez vouloir extraire l'identifiant de l'appelant de chaque enregistrement. Avec une requête JSONPath comme $.calls[*].callerIDvous pouvez rapidement obtenir tous les numéros d'appel de la liste.

Comment comprendre les réponses de l'API REST

L'acronyme REST API signifie "interface de programmation d'applications de transfert d'état représentationnel".

• Le transfert d'état représentationnel (REST) est un style architectural pour la conception d'applications en réseau. Il repose sur un protocole de communication client-serveur sans état, presque toujours HTTP (Hypertext Transfer Protocol).

• Interface de programmation d'applications (API) est un ensemble de règles et de définitions qui permet à différentes applications logicielles de communiquer entre elles.

Dans le contexte des services web, une API REST permet aux applications d'interagir avec les services web à l'aide des protocoles du web (comme HTTP) et implique généralement la demande et le transfert de données à l'aide d'opérations telles que GET, POST, PUT et DELETE. Les API REST sont largement utilisées en raison de leur simplicité, de leur évolutivité et de leur polyvalence. C'est ce qui en fait l'épine dorsale de la communication web, et la compréhension de leurs réponses est la clé d'une intégration réussie.

Les réponses des API sont souvent au format JSON. En tant que personne visuelle, j'adore j'adore la légèreté et la lisibilité de la structure JSON lorsqu'elle est rendue plus attrayante. Nous explorerons les nuances des réponses de l'API REST, en mettant l'accent sur le rôle du format JSON pour garantir un échange de données et une intégration efficaces avec AI Studio de Vonage.

Création d'un chemin d'accès à un objet

Lorsque l'on travaille avec des réponses JSON provenant d'API, notamment dans des outils comme Vonage AI Studio, l'une des compétences les plus cruciales est la compréhension et la création de " chemins d'objets. "

Qu'est-ce qu'un chemin d'accès ?

Un chemin d'objet est une séquence de clés que vous suivez pour naviguer dans un objet JSON afin d'atteindre les données spécifiques que vous souhaitez. Considérez un chemin d'objet comme un itinéraire GPS qui vous conduit à l'information exacte dont vous avez besoin au sein d'une structure JSON. Par exemple, dans un objet JSON représentant une personne, le chemin d'accès à son adresse électronique pourrait être le suivant person.contact.email.

Comment construire un chemin d'objets

1. Commencer par la racine : La racine d'un objet JSON est son niveau le plus externe. C'est à partir de là que vous identifiez la première clé qui vous rapproche de vos données.

2. Naviguer à travers les couches : Si la valeur d'une clé est un autre objet ou un tableau, vous continuez en spécifiant la clé suivante ou l'index du tableau.

3. Répétez l'opération jusqu'à ce que vous obteniez vos données : Continuez à spécifier des clés ou des index jusqu'à ce que vous obteniez les données dont vous avez besoin.

Exemple pratique dans Vonage AI Studio

Utilisons une simple réponse JSON pour illustrer la construction d'un chemin d'accès aux objets. Imaginez que vous ayez la réponse JSON suivante provenant d'une API de Vonage :

{
  "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"
      }
    }
  }
}

• Objectif : Supposons que nous voulions extraire le(s) article(s) exclu(s) dans la commande de hamburgers.

• Construction du chemin d'accès à l'objet étendu :

  1. Commencer par la racine : La clé racine est order.

  2. Première couche : Intérieur orderNous naviguons vers details.

  3. Deuxième couche : A l'intérieur de detailsnous trouvons customizations.

  4. Destination finale : L'objet customizations contient la clé exclude.

• Chemin d'accès final à l'objet : Le chemin d'objet pour trouver la liste des sauces est le suivant order.details.customizations.exclude.

Comment utiliser les chemins d'objets dans AI Studio de Vonage

Dans Vonage AI Studio, lorsque vous configurez des mappages de réponses ou des nœuds dans le nœud webhook, vous devrez souvent spécifier ces chemins d'objets pour indiquer au Studio exactement où trouver et extraire les données dont vous avez besoin à partir d'une réponse d'API. Les chemins d'accès aux objets sont essentiels, car ils vous permettent de localiser et d'extraire uniquement les données dont vous avez besoin à partir de structures JSON potentiellement complexes, ce qui rend votre traitement des données efficace et exempt d'erreurs.

Comment passer/ajouter des paramètres de requête aux demandes d'API ?

Dans cette section, nous verrons comment la définition de paramètres dans les interactions API est similaire à la personnalisation de votre commande de nourriture. Tout comme vous pouvez spécifier la façon dont vous voulez votre hamburger dans un restaurant, les paramètres d'une requête d'API vous permettent de définir exactement les données dont vous avez besoin. Nous utiliserons l'analogie directe de la commande d'un hamburger pour expliquer ce concept, ainsi qu'un échantillon de données pour illustrer la façon dont il s'applique dans un scénario pratique.

Exemple : Une commande de hamburger

Imaginez que vous êtes chez Bob's Burgers et que vous voulez commander un hamburger. Mais vous n'aimez pas les cornichons. Vous dites donc au serveur : "Je voudrais un cheeseburger, mais s'il vous plaît, pas de cornichons" Ici, "pas de cornichons" est une demande spéciale ou un paramètre qui personnalise votre commande.

Que sont les paramètres de requête ?

• Analogie avec le monde réel : Les paramètres d'une requête sont comme vos préférences dans une commande de nourriture. Lorsque vous demandez quelque chose de spécifique, comme un hamburger sans cornichons, vous définissez les paramètres de votre commande.

• En termes d'API : Les paramètres sont les valeurs que vous envoyez avec votre demande d'API. Ils indiquent les informations que vous souhaitez obtenir de l'API. Par exemple, si vous demandez des informations sur un utilisateur, un paramètre peut être l'ID de l'utilisateur. Ils vous permettent de personnaliser votre demande de données. L'utilisation de paramètres vous permet d'obtenir exactement et uniquement ce dont vous avez besoin de la part d'une API.

Traduction en paramètres API

• Demande d'API : Dans le monde des API, une demande est comme votre commande à la cuisine. Les détails que vous fournissez (comme "pas de cornichons") sont des paramètres qui personnalisent cette demande.

• Définition des paramètres : Lorsque vous spécifiez certains détails dans votre demande d'API, vous définissez des paramètres. Ces paramètres indiquent à l'API comment "préparer" vos données.

Définition des paramètres dans Vonage AI Studio

1. Identifiez vos besoins en matière de données : Comprenez quelles informations spécifiques vous attendez de l'API et quelles informations elle est capable de fournir. Par exemple, si vous commandez une pizza chez Bob's Burgers, la cuisine vous renverra une erreur car ce n'est pas un paramètre de requête qu'elle sait traiter.

2. Utilisez l'interface de Vonage AI Studio : Le studio offre une façon intuitive de définir les paramètres. Par exemple, si vous récupérez des données sur les utilisateurs, vous pouvez définir un paramètre pour l'identifiant de l'utilisateur.

3. Saisissez les valeurs de vos paramètres : Ces valeurs doivent correspondre aux données que vous essayez de récupérer. Dans notre exemple, il s'agirait de l'identifiant de l'utilisateur.

Exemple de données pour une demande d'API

Créons un exemple d'ensemble de données pour visualiser cela :

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

Exemple pratique : Personnalisation de votre commande dans Vonage AI Studio

1. Commande initiale : En utilisant les données de l'échantillon, votre commande initiale est un hamburger avec du fromage, de la laitue et des tomates.

2. Définition des paramètres de personnalisation : Supposons que vous ne voulez pas de cornichons sur votre hamburger. Dans un paramètre API, tel que Vonage AI Studio, vous ajouteriez " pickles " au paramètre " exclude ".

3. Données de commande modifiées :

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

   Copie

4. Résultat : L'API traite cette demande et renvoie une réponse qui reflète votre commande personnalisée - un hamburger avec du fromage, de la laitue et des tomates, mais sans cornichons.

Voici ce que cela donnerait dans une table de base de données :

Rejoindre la "liste d'invités" de Vonage's Burger

Dans cet article, nous avons appris l'essentiel de la manipulation des objets JSON, des réponses API et du mappage des réponses dans Vonage AI Studio, le tout à l'aide d'exemples faciles à comprendre inspirés de Bob's Burgers. Si vous avez aimé ce que vous avez lu, rejoignez notre " magasin de burgers " de développeurs sur Slack et suivez-nous sur Xanciennement connu sous le nom de Twitter. Si vous avez trouvé ce blog utile d'une manière ou d'une autre, veuillez partager votre commentaire et m'étiqueter - J'aimerais beaucoup connaître votre "expérience gastronomique" !