Construire des actions Github avec l'API Messages de Vonage

Pour les équipes et les individus, la communication est très importante pour le développement d'un projet. Non seulement la communication entre les membres, mais aussi la communication directe avec le projet. Vérifier manuellement le statut de votre application peut être laborieux, et c'est l'avantage que l'automatisation à l'aide d'API de communication peut apporter. Vous pouvez facilement être notifié par texte, par appel vocal, par les médias sociaux ou par tout autre moyen (selon les fonctionnalités de l'API) lorsque des événements se produisent dans votre application.

GitHub Actions est une belle intégration dans GitHub qui vous permet de déclencher des actions basées sur des événements spécifiques qui se produisent. Cela peut s'avérer utile dans de nombreux cas, en fonction de la créativité du développeur. L'un des cas d'utilisation est l'envoi de messages via les API de communication.

Dans cet article, nous allons apprendre à combiner les actions GitHub avec l'API Messages de Vonage en utilisant le canal WhatsApp. Nous allons envoyer des messages à un numéro WhatsApp lorsqu'un événement spécifique se produit. Vous pouvez également vous entraîner avec les autres canaux pris en charge par l'API.

Connaissances requises : Pour tirer le meilleur parti de cet article, une connaissance passable de la façon dont les applications Node.js sont créées et du fonctionnement des actions GitHub serait nécessaire. Voici une Introduction aux actions GitHub que vous pouvez consulter en premier.

Que sont les actions Github ?

Les actions GitHub vous permettent d'exécuter des commandes spécifiques lorsqu'un événement se produit ; par exemple, lorsque quelqu'un fait une demande d'extraction, pousse sur une branche, et et bien d'autres événements.

Les actions GitHub peuvent être utilisées de différentes manières, dont voici quelques exemples :

• Exécution de tests sur les demandes d'autorisation d'exportation (pull requests)

• déploiement automatique après la mise à jour d'une branche

• communiquer aux développeurs l'état de l'application, les problèmes ou les demandes d'extension (pull requests)

• beaucoup plus

Vonage Messages API - Canal WhatsApp

L'API Messages vous permet d'envoyer des messages à un numéro WhatsApp via le canal WhatsApp. Pour accéder à l'API, vous devez créer un Account sur le tableau de bord Vonage Developer. Ensuite, vous recevrez des crédits gratuits pour commencer à tester l'API. Pour utiliser le canal WhatsApp, vous devez configurer un bac à sable.

Vonage API Account

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.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Vonage Developer dashboard for setting up a sandbox

Ensuite, ajoutez le canal WhatsApp au bac à sable. Vous obtiendrez un lien qui navigue vers l'application WhatsApp, avec un message par défaut dans le champ de saisie, prêt à être envoyé à Vonage. Le message par défaut varie. Pour ce tutoriel, le message généré était "Join yam slice" (Rejoindre la tranche d'igname). Pour l'application web WhatsApp, voici une capture d'écran :

WhatsApp app after clicking generated link gotten after adding WhatsApp channel to sandbox

Lorsque vous envoyez ce message, vous recevez un message vous informant que votre numéro a été inscrit sur la liste blanche de l'Environnement de test. Cela signifie que vous pouvez désormais envoyer des messages à ce numéro.

Si vous souhaitez ajouter d'autres numéros, il vous suffit d'envoyer le même texte au même destinataire en utilisant le numéro WhatsApp que vous souhaitez ajouter.

Sur la même page, vous trouverez quelque chose de similaire à ceci :

Example code for using the WhatsApp API

Ceci montre comment appeler l'API pour envoyer un message à un numéro inscrit sur la liste blanche. Cette requête POST montre :

• L'URL : https://messages-sandbox.nexmo.com/v0.1/messages

• Le nom d'utilisateur et le mot de passe dans l'indicateur -u (intentionnellement cachés dans la capture d'écran). La première série avant les deux points est votre clé API et la deuxième série est le mot de passe généré par Vonage.

• Quelques en-têtes

• Les données, qui contiennent le from (le numéro WhatsApp qui vous a été donné par Vonage pour l'envoi de messages), to (le destinataire, qui est un numéro figurant sur la liste blanche), et message la propriété.

C'est ce que nous utiliserons dans nos actions GitHub pour envoyer des messages.

Ensuite, configurons une application d'exemple pour voir l'utilisation des Actions GitHub et de l'API Messages de Vonage.

Combiner les actions Github avec l'API WhatsApp

Pour cet exemple, nous allons créer une bibliothèque npm qui renvoie "I am a library" lorsqu'elle est exécutée. Il s'agit d'une application très simple, de sorte que nous pouvons nous concentrer sur la façon dont les actions GitHub fonctionnent avec l'API WhatsApp.

Mise en place de l'environnement

À l'aide du terminal, naviguez jusqu'au répertoire de votre choix où vous souhaitez que le projet soit installé, puis procédez comme suit :

• mkdir simple-libpour créer un répertoire appelé "simple-lib"

• cd simple-libpour naviguer dans ce répertoire

• npm init -y: à mettre en place package.json

• touch index.jspour créer un fichier index.js dans lequel nous placerons le code d'exécution de notre bibliothèque

Ajoutez le code suivant à index.js:

function returnPhrase() {
  return "I am a library";
}

module.exports = returnPhrase;

Supposons que nous voulions mettre en place une suite de tests pour notre bibliothèque. Exécutez les commandes suivantes dans votre terminal :

Mocha est un cadre de test pour les applications JavaScript. Nous aurons la suite de tests dans test.js avec le code suivant :

const assert = require("assert");
const returnPhrase = require(".");

describe("returnPhrase", function () {
  it("should print the right phrase", function () {
    assert.strictEqual(returnPhrase(), "I am a library");
  });
});

En package.json, modifiez la propriété test à la valeur suivante :

"scripts": {
  "test": "mocha"
},

Maintenant, lorsque vous exécutez npm run test dans le terminal, vous obtiendrez

Result of executing test script

Initialiser un dépôt Git en utilisant git init, valider les modifications, et pousser vers un nouveau dépôt GitHub que vous avez créé pour cet exemple.

Mise en œuvre de la messagerie WhatsApp

Lorsque vous exécutez des actions GitHub, vous avez besoin d'un gestionnaire d'actions. Le programme d'exécution d'action fournit l'implémentation de l'API Messages que nous voulons utiliser. Les gestionnaires d'action ont besoin de deux fichiers :

• action.yml qui fournit le schéma de l'exécutant, tel que les entrées à recevoir, les variables produites, et bien d'autres choses encore.

• Le fichier principal (qui peut être dist/index.js) qui fournit l'implémentation réelle référencée par le fichier action.yml.

Pour cet exemple, créez un fichier action.yml avec la configuration suivante :

name: 'Vonage WhatsApp Action'
description: 'Action to send WhatsApp messages'
runs:
  using: 'node12'
  main: 'dist/index.js'
inputs:
  message:
    description: The message you want to send to the WhatsApp number
    required: true

Créons un fichier whatsapp.js qui sera compilé en dist/index.js. Ce fichier contient le code nécessaire pour envoyer des messages en utilisant le canal WhatsApp.

Voici le contenu du fichier whatsapp.js fichier :

const core = require("@actions/core");
const { default: axios } = require("axios");

const env = process.env;

const messageFromInput = core.getInput("message");

const messageToSend =
  `${messageFromInput}\n\n` +
  `Repository: ${env.GITHUB_REPOSITORY}\n` +
  `Workflow name: ${env.GITHUB_WORKFLOW}\n` +
  `Job name: ${env.GITHUB_JOB}`;

Const VONAGE_NUMBER = “<Number from Vonage>”
const WHATSAPP_NUMBER = "<A recipient>";
const API_KEY = “<API Key from your dashboard>”
const API_SECRET = “<API Secret from your dashboard>”

(async () => {
  try {
    await axios({
      method: "post",
      url: "https://messages-sandbox.nexmo.com/v0.1/messages",
      auth: {
        username: API_KEY,
        password: API_SECRET,
      },
      data: {
        from: {
          type: "whatsapp",
          number: VONAGE_NUMBER,
        },
        to: {
          type: "whatsapp",
          number: WHATSAPP_NUMBER,
        },
        message: {
          content: {
            type: "text",
            text: messageToSend,
          },
        },
      },
    });
  } catch (error) {
    core.setFailed(error.message);
  }
})();

@actions/core est une bibliothèque qui contient plusieurs fonctions permettant d'accepter des entrées, d'exporter des variables et de faire beaucoup d'autres choses à travers les actions. L'importance de cette bibliothèque est de recevoir des entrées de la part des gestionnaires d'actions sur GitHub. Elle doit être installée, donc lancez :

Axios est un client HTTP basé sur des promesses pour effectuer des requêtes réseau. Il est utilisé pour effectuer une requête POST. Il a également besoin d'être installé, alors lancez-le :

process.env donne accès aux variables d'environnement qui contiennent les variables exposées par GitHub pendant l'exécution du flux de travail. Par exemple, GitHub expose la variable GITHUB_REPOSITORY qui peut être accessible avec process.env.GITHUB_REPOSITORY. Vous pouvez trouver d'autres variables d'environnement par défaut de GitHub ici.

A message sera reçu (nous verrons comment mettre cela en place dans la section de configuration des actions GitHub), qui serait le même message que nous enverrons au numéro WhatsApp. Vous pouvez utiliser n'importe quel numéro sur liste blanche que vous voulez là, mais Vonage dit spécifiquement :

"N'utilisez pas de + ou de 00, commencez par le code du pays, par exemple 447700900000".

Ensuite, la demande de poste est effectuée et le message WhatsApp est envoyé au numéro.

Comme dans l'exemple de code de Vonage, nous spécifions le nom d'utilisateur et le mot de passe pour l'authentification du serveur. Pour Axios, cela se fait avec l'objet auth qui contient les objets username et password propriété.

Comme indiqué ci-dessus, le message WhatsApp est envoyé sous la forme :

"**TEST FAILED!!**
Repository: <Repository name>
Workflow name: <Workflow name>
Job name: <Job name>"

Nous devons également installer un autre paquet : @vercel/ncc. Ce paquetage est utilisé pour regrouper les fichiers Node.js en un seul fichier. Nous l'utiliserons pour regrouper whatsapp.js et toutes les dépendances utilisées dans un seul fichier.

Ajouter ce qui suit à package.json:

"scripts": {
  "test": "mocha",
  "build": "ncc build whatsapp.js -o dist"
},

Avant de pousser, nous devons exécuter npm run build pour que tout ce qui se trouve dans whatsapp.js soit exporté vers dist/index.js.

Configuration des actions Github

Tout d'abord, créez un répertoire workflows dans le répertoire .github Ce répertoire contiendra tous les flux de travail que nous voulons pour l'application.

Sous workflows, créez un fichier appelé "whatsapp-actions.yml". Les actions GitHub utilisent le format YAML pour décrire les flux de travail.

Pour cet exemple, nous voulons envoyer un message WhatsApp lorsqu'un nouveau commit est poussé vers le dépôt et que le script de test échoue. Voici le contenu du flux de travail :

# .github/workflows/whatsApp-actions.yml
name: Whatsapp actions

on: push

jobs:
  run-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
      - run: npm i
      - run: npm test
      - name: WhatsApp Message
        if: ${{ failure() }}
        uses: dillionmegida/github-actions@master
        with:
          message: "*TEST FAILED*"

Avant d'aller plus loin, il convient de bien comprendre la configuration ci-dessus.

name: Whatsapp actions

La propriété name spécifie le nom du flux de travail. C'est ce que vous voyez dans l'onglet actions sur GitHub.

on: push

La propriété on spécifie l'événement qui déclenche le flux de travail. Dans notre exemple, c'est l'événement push est l'événement qui déclenche le flux de travail. Cela signifie que le flux de travail est exécuté à chaque fois que quelqu'un apporte une modification à une branche du référentiel. Voici d'autres d'autres événements que vous pouvez utiliser. Vous pouvez également spécifier plusieurs événements.

jobs:
  run-tests:
    runs-on: ubuntu-latest

La propriété jobs spécifie les travaux qui seront exécutés pour ce flux de travail. Je nomme le premier travail run-tests. GitHub affiche toutes les tâches exécutées dans votre flux de travail sous l'onglet actions en les regroupant sous leur nom de travail respectif.

La ligne suivante (runs-on) spécifie le type et la version du système d'exploitation à utiliser pour exécuter le flux de travail.

steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
      - run: npm i
      - run: npm test
      - name: WhatsApp Message
        if: ${{ failure() }}
        uses: dillionmegida/github-actions@master
        with:
          message: "*TEST FAILED*"

Sous la rubrique "emplois" figurent des "mesures" à prendre. Le bloc steps décrit l'exécution des tâches qui composent un travail.

Dans les deux premières étapes, l'action "utilise" actions/checkout@v2 et actions/setup-node@v1. actions/checkout@v2 est un exécuteur d'action pour l'extraction d'un référentiel. Cette action est nécessaire pour permettre à votre environnement de travail d'accéder au code contenu dans le référentiel. actions/setup-node@v1 est un programme d'exécution d'action pour télécharger Node. Il permet d'accéder à npm dont nous aurons besoin aux troisième et quatrième étapes.

Un modèle de référence pour la création d'actions GitHub peut être trouvé dans le référentiel dépôt de workflows de démarrage. Comme on peut le voir ici, uses: actions/checkout@v2 et actions/setup-node@v1 sont également utilisés dans la section des étapes. Ce sont deux étapes essentielles car elles permettent d'exécuter le code que vous avez dans votre référentiel en utilisant la commande npm.

Exécution npm i installe toutes les dépendances dans package.json et npm test exécute le test script.

L'étape suivante du flux de travail est un groupe d'étapes intitulé "WhatsApp Message". Ces lignes déclenchent l'envoi d'un message WhatsApp à l'aide de la configuration d'action que nous avons dans action.yml. L'étape est assortie d'une condition à la ligne suivante (if: ${{ failure() }}), qui indique que les tests restants ne s'exécuteront que si les étapes précédentes du travail échouent. Vous pouvez consulter d'autres vérifications de l'état des tâches.

Dans l'étape WhatsApp Message, l'action "utilise" dillionmegida/github-actions@master (qui est la branche principale du même dépôt) en tant que gestionnaire d'action pour la mise en œuvre du code de l'API Messages. À ce stade, GitHub rechercherait action.yml dans le répertoire racine de ce dépôt, que nous avons déjà configuré.

L'action envoie une entrée au gestionnaire d'action (whatsapp.js) à l'aide de la propriété with à l'aide de la propriété L'entrée est accompagnée d'une clé message et une valeur *TEST FAILED*. Les astérisques sont ajoutés pour que WhatsApp puisse mettre le texte en gras.

Test des actions Github

Maintenant que tout est en place, nous pouvons déclencher le flux de travail en le poussant vers un référentiel. Avant cela, nous devons nous assurer que le test échoue, afin que l'implémentation du message WhatsApp soit exécutée.

Modifier test.js à ce qui suit :

assert.strictEqual(returnPhrase(), "I am not a library");

Nous pouvons regrouper notre application (en utilisant npm run build), valider les changements, et la pousser vers le dépôt.

Lors de la poussée, le flux de travail est déclenché et nous obtenons une erreur comme indiqué ci-dessous :

Error from running the workflow

Après l'erreur, nous recevrons un message WhatsApp comme suit :

Screenshot of WhatsApp message sent to a whitelisted number

Conclusion

Vous pouvez faire beaucoup de choses avec GitHub Actions et encore plus avec les API de communication de Vonage. Vous pouvez également envoyer des messages sur Viber et Facebook Messenger.

Dans cet article, nous avons appris ce que sont les Actions GitHub, quelques utilitaires qui rendent les Actions GitHub puissantes, et comment intégrer l'API Messages Vonage pour envoyer des messages WhatsApp lorsqu'un script de test échoue après avoir poussé un commit vers un dépôt.