Erstellen von Github-Aktionen mit der Vonage Messages API

Für Teams und Einzelpersonen ist die Kommunikation sehr wichtig für das Wachstum eines Projekts. Nicht nur die Kommunikation zwischen den Mitgliedern, sondern auch die direkte Kommunikation mit dem Projekt. Den Status Ihrer Anwendung manuell zu überprüfen, kann anstrengend sein, und das ist der Vorteil, den die Automatisierung mithilfe von Kommunikations-APIs bieten kann. Sie können sich ganz einfach per Text, Sprachanruf, über soziale Medien oder auf andere Weise (je nach den Funktionen der API) benachrichtigen lassen, wenn in Ihrer Anwendung Ereignisse auftreten.

GitHub Actions ist eine wunderbare Integration in GitHub, die es Ihnen ermöglicht, Aktionen auf der Grundlage bestimmter Ereignisse auszulösen, die auftreten. Dies kann für viele Zwecke nützlich sein, je nachdem, wie kreativ ein Entwickler sein kann. Einer der Anwendungsfälle ist das Senden von Nachrichten über Kommunikations-APIs.

In diesem Artikel erfahren Sie, wie Sie GitHub Actions mit der Vonage Messages API unter Verwendung des WhatsApp-Kanals kombinieren können. Wir werden Nachrichten an eine WhatsApp-Nummer senden, wenn ein bestimmtes Ereignis eintritt. Sie können auch mit den anderen unterstützten Kanälen der API üben.

Erforderliches Wissen: Um das meiste aus diesem Artikel herauszuholen, ist ein gewisses Wissen darüber erforderlich, wie Node.js-Applikationen erstellt werden und wie GitHub-Aktionen funktionieren. Hier ist eine Einführung in GitHub-Aktionen Artikel, den Sie vielleicht zuerst lesen möchten.

Was sind Github-Aktionen?

Mit GitHub-Aktionen können Sie bestimmte Befehle ausführen, wenn ein Ereignis eintritt, z. B. wenn jemand eine Pull-Anfrage stellt, einen Zweig verschiebt und viele weitere Ereignisse.

GitHub-Aktionen können auf verschiedene Weise verwendet werden, einige davon sind:

• Tests für Pull-Anfragen durchführen

• automatische Bereitstellung nach Aktualisierung eines Zweigs

• Kommunikation von Anwendungsstatus, Problemen oder Pull-Requests mit Entwicklern

• viel mehr

Vonage Messages API - WhatsApp-Kanal

Mit der Messages API können Sie über den WhatsApp-Kanal Nachrichten an eine WhatsApp-Nummer senden. Um auf die API zuzugreifen, müssen Sie einen Account auf dem Vonage Developer Dashboard erstellen. Danach erhalten Sie kostenloses Guthaben, mit dem Sie die API testen können. Um den WhatsApp-Kanal zu nutzen, müssen Sie eine Sandbox einrichten.

Vonage API-Konto

Um dieses Tutorial durchzuführen, benötigen Sie ein Vonage API-Konto. Wenn Sie noch keines haben, können Sie sich noch heute anmelden und mit einem kostenlosen Guthaben beginnen. Sobald Sie ein Konto haben, finden Sie Ihren API-Schlüssel und Ihr API-Geheimnis oben auf dem Vonage-API-Dashboard.

Sind Sie bereit, mit dem Bau zu beginnen?

Erleben Sie nahtlose Konnektivität, Echtzeit-Messaging und kristallklare Sprach- und Videoanrufe - alles auf Knopfdruck.

Vonage Developer dashboard for setting up a sandbox

Fügen Sie dann den WhatsApp-Kanal zur Sandbox hinzu. Sie erhalten einen Link, der Sie zur WhatsApp-Anwendung führt, mit einer Standardnachricht im Eingabefeld, die Sie an Vonage senden können. Die Standardnachricht kann variieren. Für dieses Tutorial wurde die folgende Nachricht generiert "Join yam slice". Für die WhatsApp-Webanwendung finden Sie hier einen Screenshot:

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

Wenn Sie diese Nachricht senden, erhalten Sie eine Nachricht, die Ihnen mitteilt, dass Ihre Nummer in die Whitelist für die Sandbox aufgenommen wurde. Das bedeutet, dass Sie nun Nachrichten an diese Nummer senden können.

Wenn Sie weitere Nummern hinzufügen möchten, können Sie einfach denselben Text an denselben Empfänger senden und dabei die WhatsApp-Nummer verwenden, die Sie hinzufügen möchten.

Auf derselben Seite finden Sie etwas Ähnliches wie das hier:

Example code for using the WhatsApp API

Hier wird gezeigt, wie man die API aufruft, um eine Nachricht an eine Nummer auf der Whitelist zu senden. Diese POST-Anfrage zeigt:

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

• Den Benutzernamen und das Passwort in der -u Flagge (im Screenshot absichtlich verborgen). Der erste Satz vor dem Doppelpunkt ist Ihr API-Schlüssel und der zweite Satz ist das von Vonage generierte Passwort.

• Einige Kopfzeilen

• Die Daten, die die from (die WhatsApp-Nummer, die Sie von Vonage zum Versenden von Nachrichten erhalten haben), to (der Empfänger, der eine Whitelist-Nummer ist) und message Eigenschaft.

Dies werden wir in unseren GitHub-Aktionen zum Senden von Nachrichten verwenden.

Als Nächstes wollen wir eine Beispielanwendung einrichten, um zu sehen, wie die GitHub Actions und die Vonage Messages API verwendet werden.

Kombinieren von Github-Aktionen mit der WhatsApp-API

In diesem Beispiel werden wir eine npm-Bibliothek erstellen, die bei der Ausführung "Ich bin eine Bibliothek" zurückgibt. Es handelt sich um eine sehr einfache App, sodass wir uns darauf konzentrieren können, wie GitHub-Aktionen mit der WhatsApp-API funktionieren.

Einrichten der Umgebung

Navigieren Sie mit dem Terminal in das gewünschte Verzeichnis, in dem das Projekt gespeichert werden soll, und gehen Sie dann wie folgt vor:

• mkdir simple-lib: ein Verzeichnis namens "simple-lib" erstellen

• cd simple-lib: um in dieses Verzeichnis zu navigieren

• npm init -y: zum Einrichten package.json

• touch index.js: eine index.js-Datei erstellen, in der wir den Ausführungscode unserer Bibliothek ablegen

Fügen Sie den folgenden Code hinzu index.js:

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

module.exports = returnPhrase;

Nehmen wir an, wir wollen eine Testsuite für unsere Bibliothek einrichten. Führen Sie die folgenden Befehle in Ihrem Terminal aus:

Mocha ist ein Test-Framework für JavaScript-Applikationen. Wir werden die Testsuite in test.js mit dem folgenden Code:

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

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

Unter package.jsonbearbeiten Sie die test Eigenschaft auf den folgenden Wert:

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

Wenn Sie nun npm run test auf dem Terminal ausführt, erhält man:

Result of executing test script

Initialisieren Sie ein Git-Repository mit git init, übertragen Sie die Änderungen und pushen Sie sie in ein neues GitHub-Repository, das Sie für dieses Beispiel erstellt haben.

Einführung von WhatsApp Messaging

Wenn Sie GitHub-Aktionen ausführen, benötigen Sie einen Aktions-Läufer. Der Action-Runner stellt die Implementierung für die Messages API bereit, die wir verwenden wollen. Action-Runner benötigen zwei Dateien:

• action.yml die das Schema für den Läufer bereitstellt, wie z. B. zu empfangende Eingaben, auszugebende Variablen und vieles mehr.

• Die Hauptdatei (kann sein dist/index.js), die die eigentliche Implementierung bereitstellt, auf die in der action.yml.

Für dieses Beispiel erstellen Sie eine action.yml Datei mit der folgenden Konfiguration:

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

Erstellen wir eine whatsapp.js Datei, die wir zu dist/index.js. Diese Datei enthält den Code, der zum Senden von Nachrichten über den WhatsApp-Kanal erforderlich ist.

Hier ist der Inhalt der whatsapp.js Datei:

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 ist eine Bibliothek, die mehrere Funktionen für die Entgegennahme von Eingaben, den Export von Variablen und viele andere aktionsübergreifende Aufgaben enthält. Sie ist wichtig, um Eingaben von den Aktionsläufern auf GitHub zu erhalten. Sie muss installiert werden, also führen Sie sie aus:

Axios ist ein auf Versprechen basierender HTTP-Client für Netzanfragen. Er wird verwendet, um eine POST-Anfrage zu stellen. Er muss ebenfalls installiert werden, also führen Sie ihn aus:

process.env ermöglicht den Zugriff auf Umgebungsvariablen, die die von GitHub während der Workflow-Ausführung offengelegten Variablen enthalten würden. Zum Beispiel stellt GitHub die GITHUB_REPOSITORY Variable, auf die man mit process.env.GITHUB_REPOSITORY. Weitere Standard-Umgebungsvariablen von GitHub finden Sie hier.

A message Input erhalten (wie man das einrichtet, sehen wir im Abschnitt über die Konfiguration von GitHub-Aktionen), der dieselbe Nachricht ist, die wir an die WhatsApp-Nummer senden werden. Sie können jede beliebige Nummer auf der Whitelist verwenden, die Sie wollen, aber Vonage sagt das ausdrücklich:

"Verwenden Sie kein + oder 00, sondern beginnen Sie einfach mit der Landesvorwahl, z. B. 447700900000"

Dann wird die Postanfrage gestellt und die WhatsApp-Nachricht an die Nummer gesendet.

Genau wie im Beispielcode von Vonage geben wir den Benutzernamen und das Passwort für die Serverauthentifizierung an. Bei Axios geschieht dies mit dem auth Objekt, das die username und password Eigenschaft enthält..

Wie oben zu sehen, wird die WhatsApp-Nachricht in der Form gesendet:

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

Wir müssen noch ein weiteres Paket installieren: @vercel/ncc. Dieses Paket wird verwendet, um Node.js-Dateien in einer Datei zu bündeln. Wir würden dies verwenden, um whatsapp.js und alle verwendeten Abhängigkeiten in einer Datei zu bündeln.

Fügen Sie Folgendes hinzu package.json:

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

Vor dem Pushen müssen wir npm run build ausführen, damit alles in whatsapp.js nach dist/index.js.

Konfiguration für Github-Aktionen

Erstellen Sie zunächst ein workflows Verzeichnis im .github Dieses Verzeichnis würde alle Arbeitsabläufe enthalten, die wir für die App benötigen.

Erstellen Sie unter Workflows eine Datei namens "whatsapp-actions.yml". GitHub Actions verwenden die YAML Syntax für die Beschreibung von Arbeitsabläufen.

In diesem Beispiel wollen wir eine WhatsApp-Nachricht senden, wenn eine neue Übergabe an das Repository erfolgt und das Testskript fehlschlägt. Hier ist der Inhalt des Workflows:

# .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*"

Bevor wir weitermachen, sollten wir uns ein klares Bild von der obigen Konfiguration machen.

name: Whatsapp actions

Die Eigenschaft name Eigenschaft gibt den Namen des Workflows an. Diesen sehen Sie auf der Registerkarte "Aktionen" auf GitHub.

on: push

Die Eigenschaft on Eigenschaft gibt das Ereignis an, das den Workflow auslöst. In unserem Beispiel ist es das push das Ereignis aus. Das bedeutet, dass der Workflow immer dann ausgeführt wird, wenn jemand eine Änderung an einem Zweig im Repository vornimmt. Hier sind weitere Ereignisse die Sie verwenden können. Sie können auch mehrere Ereignisse.

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

Die Eigenschaft jobs Eigenschaft gibt die Aufträge an, die für diesen Arbeitsablauf ausgeführt werden sollen. Ich nenne den ersten Auftrag run-tests. GitHub zeigt jede Aufgabe, die in Ihrem Workflow läuft, auf der Registerkarte "Aktionen" an, indem sie unter dem jeweiligen Auftragsnamen gruppiert wird.

Die nächste Zeile (runs-on) gibt den Betriebssystemtyp und die Version an, die für die Ausführung des Workflows verwendet werden soll.

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*"

Unter dem Abschnitt "Berufe" finden Sie "Schritte", die Sie unternehmen können. Der steps Block beschreibt die Ausführung der Aufgaben, aus denen ein Auftrag besteht.

In den ersten beiden Schritten "verwendet" die Aktion actions/checkout@v2 und actions/setup-node@v1. actions/checkout@v2 ist ein Action Runner für das Auschecken eines Repositorys. Dies ist erforderlich, um Ihrer Arbeitsumgebung Zugriff auf den Code im Repository zu geben. actions/setup-node@v1 ist ein Action-Runner für das Herunterladen von Node. Dies ermöglicht den Zugriff auf npm die wir im dritten und vierten Schritt benötigen.

Eine Textvorlage für die Erstellung von GitHub-Aktionen finden Sie im Starter-Workflows-Repository. Wie dort zu sehen, uses: actions/checkout@v2 und actions/setup-node@v1 auch im Abschnitt Schritte verwendet. Dies sind zwei wichtige Schritte, denn sie ermöglichen die Ausführung des Codes, den Sie in Ihrem Repository mit npm.

Das Ausführen von npm i installiert alle Abhängigkeiten in package.json und npm test führt das test Skript aus.

Der nächste Schritt im Arbeitsablauf ist eine Gruppe von Schritten mit dem Namen "WhatsApp-Nachricht". Diese Zeilen lösen die WhatsApp-Nachricht unter Verwendung der Aktionskonfiguration aus, die wir in action.yml. Der Schritt hat eine Bedingung in der nächsten Zeile (if: ${{ failure() }}), die besagt, dass die verbleibenden Tests nur dann ausgeführt werden, wenn die vorherigen Schritte des Auftrags fehlschlagen. Sie können sich weitere Job-Status-Prüfungen.

Im Schritt WhatsApp-Nachricht "verwendet" die Aktion dillionmegida/github-actions@master (der Master-Zweig desselben Repositorys) als Action Runner für die Implementierung des Messages API-Codes. GitHub würde zu diesem Zeitpunkt nach action.yml im Stammverzeichnis dieses Repositorys, das wir bereits konfiguriert haben.

Die Aktion sendet eine Eingabe an den Action Runner (whatsapp.js) unter Verwendung der with Eigenschaft. Die Eingabe kommt mit einem Schlüssel message und Wert *TEST FAILED*. Die Sternchen werden hinzugefügt, damit WhatsApp den Text fett darstellen kann.

Testen der Github-Aktionen

Nun, da wir alles eingerichtet haben, können wir den Workflow auslösen, indem wir ihn in ein Repository pushen. Zuvor müssen wir sicherstellen, dass der Test fehlschlägt, damit die Implementierung der WhatsApp-Nachricht ausgeführt werden kann.

Bearbeiten Sie test.js zu den folgenden:

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

Wir können unsere Anwendung bündeln (mit npm run build) bündeln, die Änderungen festschreiben und an das Repository übergeben.

Beim Pushing wird der Workflow ausgelöst, und es tritt ein Fehler auf (siehe unten):

Error from running the workflow

Nach dem Fehler erhalten wir eine WhatsApp-Nachricht wie folgt:

Screenshot of WhatsApp message sent to a whitelisted number

Schlussfolgerung

Mit GitHub Actions können Sie eine Menge tun und mit den Vonage Kommunikations-APIs noch mehr. Sie können auch Nachrichten an Viber und Facebook Messenger senden.

In diesem Artikel haben wir gelernt, was GitHub Actions sind, einige Dienstprogramme, die GitHub Actions leistungsfähig machen, und wie man die Vonage Messages API integriert, um WhatsApp-Nachrichten zu versenden, wenn ein Testskript nach dem Pushen eines Commits an ein Repository fehlschlägt.