Partager:
){kind=small}
Julia s'engage à aider ses collègues développeurs en créant des tutoriels, des guides et des ressources pratiques. Grâce à son expérience en matière de sensibilisation et d'éducation, elle vise à rendre la technologie plus accessible et à améliorer l'expérience globale des développeurs. Vous pouvez souvent la trouver lors d'événements communautaires locaux.
Utilisation de variables et enchaînement de requêtes dans Postman
Temps de lecture : 4 minutes
Chez Vonage, nous utilisons OpenAPI pour décrire toutes nos API, et nous rendons également ces spécifications publiquement disponibles. L'une des choses que nous préférons faire avec un fichier OpenAPI que nous n'avons pas vu auparavant est de l'importer dans Postman. C'est pourquoi nous avons décidé d'en faire profiter les autres et de créer une Collection Postman pour nos API afin que l'évaluation et l'exploration de celles-ci soient plus rapides et plus faciles que jamais.
Dans cet article, nous expliquons comment vous pouvez rendre l'exploration de vos API dans Postman encore plus accessible. Nous utiliserons La collection Postman des API de Vonage à titre d'exemple, alors assurez-vous de consulter la liste des prérequis si vous souhaitez nous suivre.
To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.
This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.
Lorsque vous importez pour la première fois la Collection d'API de Vonage dans Postman, vous verrez apparaître un champ Vonage APIs apparaît sous Collections sur le côté gauche de votre écran.
Vous pouvez également remarquer la mention "36 demandes" sous le nom de la collection. En fonction du type d'authentification, cela représente plus ou moins 36 fois que quelqu'un doit ajouter api_key et api_secret comme paramètres de requête.
Heureusement, Postman prend en charge les variables d'environnement, les variables globales et les variables au niveau de la collection, ce qui rendra l'expérience beaucoup plus fluide et moins pénible. Au lieu d'effectuer des tâches répétitives, telles que le remplissage des mêmes valeurs de paramètres pour chaque requête, ces variables nous permettent d'obtenir ces valeurs de manière dynamique.
Notre collection est accompagnée d'un environnement Vonage où vous pouvez fournir votre clé et votre secret, et toutes les demandes utiliseront ces valeurs à l'avenir.
Ainsi, une requête simple comme la vérification du solde de votre compte avec l Account API devient un travail en un seul clic.
D'autres demandes peuvent nécessiter des paramètres supplémentaires. Par exemple, pour envoyer un SMSil faut remplir to, from et text dans le corps de la requête, mais api_key et api_secret seront toujours remplis automatiquement. Vous pouvez également choisir d'ajouter l'un ou l'autre de ces paramètres en tant que variables, comme le paramètre to a été enregistré en tant que variable de collection dans la requête présentée ci-dessous. Pour ce faire, vous pouvez soit modifier directement votre collection ou votre environnement, soit sélectionner la valeur codée en dur que vous souhaitez remplacer par une variable, puis cliquer sur Définir comme variable > Définir comme nouvelle variable.
Les variables dans Postman sont formidables, mais elles ne sont pas un outil universel pour résoudre toutes les choses encombrantes.
Par exemple, lorsque vous utilisez l'une des API de Vonage qui s'authentifie à l'aide de JWT, vous devez générer ce JWT avant de faire votre demande. Pour générer le JWT, vous aurez besoin d'un identifiant d'application et d'une clé privée, que vous obtiendrez tous deux lorsque vous créerez une application Vonage. Cela équivaut à trois demandes distinctes à effectuer, ce qui peut perturber quelqu'un qui explore l'API pour la première fois.
Heureusement, il existe une solution pour les prérequis à plusieurs étapes : l'enchaînement des demandes.
Postman offre deux zones de script, Script de pré-demande et Testsoù vous pouvez écrire tout le code JavaScript que vous souhaitez - oui, y compris une autre requête HTTP.
L'API Voice de Vonage s'authentifie à l'aide de jetons Web JSON (JWT). Créer un appel sortant nous devons d'abord :
Créer une application Vonage à l'aide de l'API Applications
Saisissez les
application_idetprivate_keyde l'objet de la réponse et les utilise pour générer un JWT.
// Check if we already have a JSON Web Token, continue if not
if (!pm.environment.has("JWT")) {
var btoa = require('btoa')
let base64keyandsecret = btoa(`${pm.environment.get("api_key")}:${pm.environment.get("api_secret")}`)
// (1) Create a Voice Application by making a request to the Vonage Applications API
pm.sendRequest({
url: 'https://api.nexmo.com/v2/applications',
method: 'POST',
header: [`Authorization:Basic ${base64keyandsecret}`, "Content-Type: application/json"],
body: JSON.stringify({
"name": "Demo Postman Application",
"capabilities": {
"voice": {
"webhooks": {
"answer_url": {
"address": "https://example.com/webhooks/answer",
"http_method": "POST"
},
"event_url": {
"address": "https://example.com/webhooks/event",
"http_method": "POST"
}
}
}
}
})
}, (err, res) => {
// (2) Generate JWT using the application ID as a claim and sign it with the private key
pm.sendRequest({
url: 'https://jwtapi-dev.netlify.app/.netlify/functions/generate',
method: 'POST',
header: ["Content-Type: application/json"],
body: JSON.stringify({
algorithm: "RS256",
private_key: res.json().keys.private_key,
claims: {
application_id: res.json().id,
exp: parseInt((Date.now() / 1000) + 3600, 10)
}
})
}, (err, res) => {
pm.environment.set("JWT", res.json().signed_jwt)
})
})
}
Postman vous permet d'ajouter des tests aux demandes individuelles, aux dossiers et aux collections. Ces tests sont extrêmement utiles pour s'assurer que votre API se comporte comme prévu et à des fins de débogage, mais il y a un hic : les tests sont des scripts JavaScript qui sont exécutés après qu'une qu'une requête a été faite. Cela signifie que la façon dont nous avons utilisé le script de pré-requêtenous pouvons tirer le meilleur parti de l'outil Test également.
Dans notre exemple d'appel vocal, une fois l'appel terminé avec succès, j'enregistre le fichier voice_call_uuid en tant que variable de collection à l'aide de la fonction pm.collectionVariables.set() à l'aide de la fonction Cette variable sera utile si je décide d'effectuer d'autres requêtes impliquant l'API Voice. Sinon, en cas d'échec, j'efface la valeur JWT à l'aide de l'expression pm.environment.unset("JWT") afin de pouvoir envoyer à nouveau ma requête et générer un nouveau JWT.
if (pm.response.code == "201") {
pm.collectionVariables.set("voice_call_uuid", pm.response.json().uuid);
} else {
pm.environment.unset("JWT")
}Pour en savoir plus sur la définition de variables dans les scripts, consultez les Postman docs.
Enfin, mettons tout cela ensemble pour passer un appel vocal en synthèse vocale. Vous pouvez utiliser l'extrait ci-dessous et fournir les éléments to et from comme des variables ou des valeurs codées en dur. N'oubliez pas que to est le numéro de destination que vous êtes sur le point d'appeler, et from est l'un de vos numéros Vonage. Obtenez-en un dans votre tableau de bord si ce n'est pas déjà fait.
Le NCCO est notre objet de contrôle des appels, qui répertorie toutes les actions à entreprendre une fois que l'appel a été pris. Consultez la Référence NCCO et voyez quelles autres actions vous pourriez inclure dans votre flux d'appels.
{
"to": [
{
"number": {{to}},
"type": "phone"
}
],
"from": {
"number": {{from}},
"type": "phone"
},
"ncco": [
{
"action": "talk",
"text": "This is a text to speech call from Vonage"
}
]
}Cette demande est maintenant prête à être traitée, alors poussez-la Envoyer et appuyez sur le bouton "Envoyer". Félicitations ! Et vous savez ce qu'il y a de mieux dans tout cela ? Si vous enregistrez vos modifications et Partager la collectionla personne suivante n'aura plus qu'à compléter les valeurs des variables manquantes et à appuyer sur le bouton Envoyer et d'appuyer sur le bouton Envoyer.
Comment utiliseriez-vous ces fonctions pratiques de Postman ? Vous avez des conseils et des astuces ? Faites-le nous savoir ; nous sommes impatients de voir ce que vous avez inventé !
Partager:
Julia s'engage à aider ses collègues développeurs en créant des tutoriels, des guides et des ressources pratiques. Grâce à son expérience en matière de sensibilisation et d'éducation, elle vise à rendre la technologie plus accessible et à améliorer l'expérience globale des développeurs. Vous pouvez souvent la trouver lors d'événements communautaires locaux.