La version 3 du CLI de Vonage est maintenant disponible en général

Avast Ye Scallywags ! Un nouveau CLI de Vonage a pris le large ! La version précédente ? Eh bien, elle est passée à la trappe et repose maintenant dans le casier de Davy Jones. Ce récit retrace les eaux traîtresses que nous avons bravées pour effectuer le changement, l'abondance des changements que nous avons découverts et la façon dont cette grande révision fait du CLI de Vonage un navire plus puissant - plus doux à naviguer, plus rapide à commander et prêt pour les débutants comme pour les chiens de mer salés !

Ok, pourquoi est-ce que je parle comme un pirate ? Parce que la version 3 de l'interface de programmation de Vonage est arrivée, elle a été complètement réécrite à partir de la base en utilisant l'interface de programmation pirate yargs sur le thème des pirates. Dans cet article, je vais expliquer pourquoi nous avons fait ce changement, ce qui a changé, et comment cette refonte rend l'interface CLI plus facile à utiliser, plus flexible et plus puissante pour les nouveaux utilisateurs comme pour les professionnels chevronnés.

Pourquoi la nouvelle version ?

Les versions précédentes utilisaient oclif. Bien qu'oclif soit un excellent cadre, le CLI de Vonage rencontrait ses limites. Yargs fournit un cadre simple dans lequel il suffit de créer une fonction de traitement qui accepte les arguments de la ligne de commande analysée. Cela facilite les tests en exigeant le passage des arguments attendus et en validant la sortie. Yargs ne gère qu'une seule chose, l'analyse des arguments. Oclif gère les arguments, exécute les commandes, analyse la sortie et contrôle l'expérience de l'utilisateur. Dans les versions précédentes, le système de plugins d'oclif était tentant à utiliser car il permettait d'ajouter des commandes bêta sans impacter les commandes de base. Cependant, il s'est avéré déroutant car certains utilisateurs pouvaient ne pas avoir installé cette commande, ce qui les amenait à penser qu'il y avait un bogue dans l'interface de programmation. Il s'est également avéré difficile de suivre les normes dans les plugins, ce qui a conduit à des cas où certaines commandes acceptaient --api-key, --apiKey ou --api_key.

Nous devions repartir à zéro et adopter une approche pragmatique de la CLI. Pour chaque commande, nous nous sommes posé la question suivante : "Qui va utiliser cette commande et à quoi va-t-elle servir ? Pour répondre à la question " qui ", nous voulions que l'interface de commande soit facile à utiliser pour les nouveaux utilisateurs (ceux qui utilisent pour la première fois des programmes d'interface de commande et ceux qui n'ont jamais utilisé Vonage auparavant) et pour les super utilisateurs. Chaque commande peut produire du JSON ou du YAML, ce qui facilite l'écriture de scripts pour les super utilisateurs et du texte brut pour ceux qui ne connaissent pas Vonage. Nous voulions également essayer de rendre le nouveau CLI aussi accessible que possible. Nous avons essayé de suivre les idéaux d'Ericsson (une entreprise suédoise).

Ceci étant dit, nous allons nous plonger dans la version 3 de la CLI de Vonage.

Installer

Avant l'installation, vous devez avoir NodeJS (version 18 ou supérieure). Une fois que vous l'avez, vous pouvez l'installer en utilisant npm:

npm install -g @vonage/cli

Cela rendra le vonage sera disponible sur l'ensemble du système pour votre utilisateur. C'est tout ce qu'il y a à faire. Vous êtes prêt à utiliser le CLI. Mais... vous devez fournir vos informations d'identification Vonage chaque fois que vous exécutez une commande. Voir ci-dessous pour des instructions sur la configuration de la CLI.

Mises à jour automatiques

La V3 comprend également des fonctions de mise à jour automatique. Lorsque vous exécutez une commande, le CLI contacte NPM pour vérifier la présence d'une nouvelle version (cette opération n'a lieu qu'une fois par jour). Si une nouvelle version a été publiée, un message s'affiche à la fin de l'exécution de la commande. Un fichier dans votre répertoire personnel est créé dans le répertoire .vonage contenant la dernière vérification et la dernière version.

Remarque : en cas de mise à jour critique, le CLI ne fonctionnera pas tant que vous n'aurez pas effectué la mise à jour.

Configuration

Le système de configuration des anciennes versions était confus. Il y avait le fichier vonage.json dans le répertoire de travail, les variables d'environnement, les arguments transmis et un fichier de configuration global. Comme chaque endroit pouvait contenir des valeurs différentes, l'exécution d'une commande pouvait avoir des effets indésirables. Nous avons donc simplifié les choses. Les paramètres d'authentification suivent cette hiérarchie : Arguments passés dans la commande -> un fichier local .vonagerc -> un fichier global config.json global situé dans $HOME/.vonage. Les valeurs seraient également fusionnées entre les différentes couches. Supposons que vous ayez une clé privée configurée localement et un identifiant d'application configuré globalement. Dans ce cas, vous risquez de ne pas pouvoir vous authentifier correctement, car l'identifiant de l'application n'est pas associé à la clé privée.

La V3 a simplifié la configuration. Les valeurs de configuration ne sont plus fusionnées. Au lieu de cela, la CLI chargera la configuration dans l'ordre suivant :

1. Options de la ligne de commande --api-key, --api-secret, --private-keyet --app-id.

2. Un fichier de configuration local dans le répertoire de travail actuel .vonagerc.

3. Un fichier de configuration global dans le répertoire .vonage dans votre répertoire personnel $HOME/.vonage/config.json.

Voici comment sauvegarder vos informations d'identification en utilisant vonage auth set:

vonage auth set --api-key=<your api key> --api-secret=<your api secret>

Cette opération permet de définir la clé et le secret de l'API, puis de confirmer que les paramètres sont valides :

✅ Checking API Key Secret

API Key: <Your api key>
API Secret: **************

Conseil de pro : Utiliser --local si vous ne voulez enregistrer ces paramètres que dans le répertoire où vous vous trouvez actuellement.

Vos informations d'identification sont maintenant sauvegardées dans <Votre répertoire personnel>/.vonage/config.json. Plus tard, si vous oubliez ce que vous avez défini, vonage auth show affichera (et vérifiera) les paramètres d'authentification.

Conseil : Ajoutez --show-all si vous voulez voir les valeurs non expurgées.

vonage auth show

Global credentials found at: /Users/manchuck/.vonage/config.json

API Key: 76009afe
API Secret: dWB**************

✅ Checking API Key Secret

Certaines commandes ne fonctionneront qu'avec une application Vonage Vonage. Vous pouvez définir les paramètres de l'application en utilisant --app-id et --private-key

Note : Vous devrez également fournir la --api-key et --api-secret.

API Key: 76009afe
API Secret: dWB**************
App ID: 4f4d4831-1491-41d4-be82-689c78e09997
Private Key: Is Set

✅ Checking API Key Secret
✅ Checking App ID and Private Key

Vous pouvez désormais utiliser l'interface de programmation sans avoir à fournir d'informations d'identification à chaque appel.

Utilisation

Je ne passerai pas en revue toutes les commandes (elles sont nombreuses et nous en ajoutons constamment), mais vous pouvez utiliser la commande --help n'importe où pour voir toutes les commandes disponibles et comment les utiliser. Je mettrai l'accent sur deux groupes importants.

Commandes JWT

Il existe deux commandes JWT : vonage jwt create, et vonage jwt validate. (Nous utilisons la commande create dans nos extraits de code extraits de code cURL). Validate peut être utile si vous rencontrez des problèmes d'authentification lors des appels à l'API. Maintenant, puisque nous avons configuré l'interface de programmation dans la section précédente, l'exécution de la commande vonage jwt create utilisera ces informations d'identification :

vonage jwt create
... A created JWT token is outputted ...

Vous pouvez également, dans une ACL, soumettre et définir un délai d'expiration personnalisé :

vonage jwt create \
--app-id='00000000-0000-0000-0000-000000000000' \
--private-key=./private.key \
--sub='Alice' \
--acl='{"paths":{"/*/rtc/**":{},"/*/users/**":{},"/*/conversations/**":{},"/*/sessions/**":{},"/*/devices/**":{},"/*/image/**":{},"/*/media/**":{},"/*/applications/**":{},"/*/push/**":{},"/*/knocking/**":{},"/*/legs/**":{}}}' \
--exp=872827200

... A created JWT token is outputted ...

Astuce : Sous MacOS, la commande pbcopy permet d'afficher une commande dans le presse-papiers. Pour ce faire, il suffit d'ajouter un pipe après la commande vonage jwt create | pbcopy.

La commande validate permet de vérifier que le jeton est correctement signé dans votre application, mais elle peut également vérifier les autres revendications :

vonage jwt create <JWT Token> \
--app-id='00000000-0000-0000-0000-000000000000' \
--private-key=./private.key \
--sub='Alice' \
--acl='{"paths":{"/*/rtc/**":{},"/*/users/**":{},"/*/conversations/**":{},"/*/sessions/**":{},"/*/devices/**":{},"/*/image/**":{},"/*/media/**":{},"/*/applications/**":{},"/*/push/**":{},"/*/knocking/**":{},"/*/legs/**":{}}}' \
--exp=872827200

✅ Token was signed with the correct private key
✅ Token has not expired
✅ Application Id [00000000-0000-0000-0000-000000000000] matches [00000000-0000-0000-0000-000000000000]
✅ Subject [Alice] matches [Alice]
✅ ACL matches
  ✅ [ANY]  /*/rtc/**
  ✅ [ANY]  /*/users/**
  ✅ [ANY]  /*/conversations/**
  ✅ [ANY]  /*/sessions/**
  ✅ [ANY]  /*/devices/**
  ✅ [ANY]  /*/image/**
  ✅ [ANY]  /*/media/**
  ✅ [ANY]  /*/applications/**
  ✅ [ANY]  /*/push/**
  ✅ [ANY]  /*/knocking/**
  ✅ [ANY]  /*/legs/**
✅ All checks complete! Token is valid

Commandes d'applications

Je veux mettre en évidence les applications vonage puisqu'elles sont les plus utilisées et qu'elles ont été modifiées de manière significative dans cette version. Le principal changement concerne la création d'applications. La version précédente vous permettait de créer l'application et de définir tous les paramètres de capacité simultanément. La V3 divise cette opération en deux commandes distinctes. Au fur et à mesure que nous avons élargi nos gammes de produits, le nombre de drapeaux nécessaires pour configurer toutes ces capacités a augmenté. De plus, si vous vouliez apporter une petite modification à une capacité, vous deviez passer toute la configuration ou risquer de modifier des capacités qui n'ont rien à voir entre elles. Voyons maintenant comment configurer une application pour laquelle les fonctionnalités de messages et de Verify ont été configurées.

Commencez par créer une nouvelle application :

vonage apps create "My Vonage Application"

✅ Creating Application
✅ Saving private key
Application created

Name: My Vonage Application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  None Enabled

Note : Pour ceux qui connaissent la V1, l'interface de programmation ne génère plus de nom pour votre application ; vous devez en spécifier un.

Ensuite, nous allons configurer les messages en utilisant vonage apps capabilities update <application id> messages:

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 messages \
--messages-inbound-url='https://example.com/messages/inboud' \
--messages-status-url='https://example.com/messages/status \
--messages-version='v1' \
--no-messages-authenticate-media

✅ Fetching Application
✅ Adding messages capability to application: My Vonage Application

Name: My Vonage Application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  MESSAGES:
	Authenticate Inbound Media: Off
	Webhook Version: v1
	Status URL: [POST] https://example.com/messages/status
	Inbound URL: [POST] https://example.com/messages/inboud

Et maintenant, nous ajoutons la vérification en changeant simplement messages en Verify:

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 verify \
--verify-status-url='https://example.com/verify'

✅ Fetching Application
✅ Adding verify capability to application: My Vonage Application

Name: My Vonage Application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  MESSAGES:
	Authenticate Inbound Media: Off
	Webhook Version: v1
	Status URL: [POST] https://example.com/messages/status
	Inbound URL: [POST] https://example.com/messages/inboud

  VERIFY:
	Webhook Version: v2
	Status URL: https://example.com/verify

Conseil : si vous souhaitez désactiver une valeur (par exemple, l'URL de l'état des messages), vous pouvez ajouter l'élément suivant remove comme valeur : --messages-status-url='__remove__'.

Commentaires finaux

L'utilisation d'un CLI en 2025 peut sembler démodée, mais vous ne souhaitez peut-être pas partager les informations d'identification du tableau de bord avec tous les membres de votre organisation. Notre API Subaccounts vous permet de créer des comptes isolés avec leurs clés API et leurs secrets. Les programmes CLI facilitent également les processus d'automatisation. Créez une application Vonage de test pour votre environnement de mise à l'essai afin de vous assurer que votre code fonctionnera avec les services Vonage. (Gardez un œil sur vonage Verify qui ajoutera bientôt le MFA en toute simplicité).

Nous n'avons pas fini d'ajouter de nouvelles commandes et fonctionnalités à la CLI. Utilisez la commande --help n'importe où pour voir toutes les commandes disponibles et comment les utiliser. Vous pouvez également consulter notre page "Getting Started with Vonage CLI" (Démarrer avec l'interface de commande de Vonage) page ou le dépôt GitHub GitHub