Wie man mit Node.js und Google Cloud Run SMS-Nachrichten sendet und empfängt

2019 organisierte ich eine Reihe von Veranstaltungen mit einem "Cloud Run Club" im Finsbury Square Garden und Victoria in London, gefolgt von einem Google Cloud Run Workshop. Heute wird nicht gelaufen, sondern Sie lernen, wie Sie eine SMS-Applikation erstellen und bereitstellen. Node.js, Expressund der Vonage Messages API auf Google Cloud Run.

Leider kann ich im laufenden Betrieb nicht auf Null skalieren, aber mit Google Cloud Run können Sie containerisierte Applications bereitstellen, die automatisch skalieren. Sie zahlen nur für das, was Sie nutzen. Das ist ideal für die Erstellung von Webhooks und APIs, da Sie keine Server verwalten müssen. Ihre Anwendung wird auf Null skaliert, wenn es keinen Datenverkehr gibt.

Gliederung und Voraussetzungen

• Node.js v18 oder höher installiert

• Google Cloud CLI installiert und konfiguriert

• A Google Cloud-Konto mit aktivierter Abrechnung

• Ein grundlegendes Verständnis von JavaScript und Node.js.

• Der vollständige Code auf GitHub

Projektstruktur

Sie finden den den kompletten Code auf GitHub. Der Projektbaum sieht wie folgt aus.

blog-messages_api-cloud_run-sms/

├── index.js, contains our JavaScript

├── package.json, for our dependencies

├── .env.example, you can copy and create a .env from it to add your environment variables

├── .gitignore, for any files or folders not to be committed

└── private.key

Erstellen einer Vonage-Anwendung

In den folgenden Schritten zeige ich Ihnen, wie Sie eine neue Vonage Anwendung über das Dashboard erstellen können. Alternativ können Sie auch die CLI verwenden, um eine Anwendung zu erstellen.

Messages API-Fähigkeit und Konfigurieren von Webhooks

Schalten Sie unter Fähigkeiten die Option Nachrichten ein. Wir verwenden die Messages API v1.

Setzen Sie vorerst Platzhalter-URLs. Wir werden diese nach der Bereitstellung aktualisieren:

• Eingehende URL: https://example.com/webhooks/inbound

• Status-URL: https://example.com/webhooks/status

Speichern Sie Ihre Bewerbung und notieren Sie sich Ihre Bewerbungs-ID.

Messages Capability

Verknüpfen einer virtuellen Telefonnummer mit der Anwendung

Sobald wir unsere Nummer ausgewählt haben, müssen wir sie mit unserer Vonage-Anwendung verknüpfen. Gehen Sie zu Your Numbers und klicken Sie auf das Stiftsymbol neben Ihrer Nummer. Wählen Sie Ihre Anwendung unter "Nachrichten" aus. Bei [00:01:19], können Sie sehen wie man eine virtuelle Nummer kauft und verknüpft.

Messages API als Standard festlegen

Gehen Sie zu Einstellungen und scrollen Sie nach unten zu "SMS-Einstellungen". Stellen Sie sicher, dass "Messages API" als Standard-API für SMS ausgewählt ist, und klicken Sie dann auf "Änderungen speichern".

SMS SettingsVonage verfügt über zwei APIs für den Versand von SMS: die SMS API und die Messages API. Dieses Lernprogramm verwendet die Messages API. Wenn Sie diese Einstellung nicht ändern, erhalten Ihre Webhooks ein anderes Payload-Format, und der Code funktioniert nicht korrekt.

Initialisieren Sie das Projekt

Erstellen Sie ein Verzeichnis für Ihre Anwendung und wechseln Sie dorthin. Führen Sie aus. npm init -y um Ihr Projekt zu initialisieren.

mkdir blog-messages_api-cloud_run-sms

cd blog-messages_api-cloud_run-sms

npm init -y

Abhängigkeiten installieren

Wir werden die folgenden Abhängigkeiten in unserem Projekt verwenden: express, @vonage/server-sdk, @vonage/jwt. Sie können sie installieren, indem Sie den folgenden Befehl in Ihrem Terminal oder der Eingabeaufforderung ausführen.

npm install express @vonage/server-sdk @vonage/jwt

Server-Einrichtung

Erstellen Sie die index.js Datei und initialisieren Sie Ihren Server mit den erforderlichen Paketen. Konfigurieren Sie einen Vonage-Client mithilfe von Umgebungsvariablen, die aus der .env-Datei gelesen werden, die aus der Datei .env.example erstellt wird.

const express = require('express');

const path = require('path');

const { Vonage } = require('@vonage/server-sdk');

const { verifySignature } = require('@vonage/jwt');

const app = express();

app.use(express.json());

app.use(express.urlencoded({ extended: true }));

// Initialize Vonage client

const vonage = new Vonage({

  applicationId: process.env.VONAGE_APPLICATION_ID,

  privateKey: path.join(__dirname, 'private.key')

});

const FROM_NUMBER = process.env.VONAGE_NUMBER;

Wir verwenden path.join(__dirname, 'private.key') um den absoluten Pfad zur Schlüsseldatei zu erhalten, so dass sie sowohl lokal als auch bei der Bereitstellung in Cloud Run funktioniert.

Hinzufügen der Home Page

Fügen Sie den Inhalt und die Gestaltung des Formulars hinzu, das der Benutzer ausfüllen muss, um SMS-Nachrichten zu versenden. Der Benutzer muss seine Telefonnummer und eine Nachricht eingeben und dann auf die Schaltfläche "Senden" klicken, um die SMS zu senden.

app.get('/', (req, res) => {

  res.send(`

    <!DOCTYPE html>

    <html>

    <head>

      <title>Vonage SMS on Cloud Run</title>

      <style>

        body { font-family: Arial, sans-serif; max-width: 600px; margin: 50px auto; padding: 20px; }

        h1 { color: #7b00ff; }

        form { display: flex; flex-direction: column; gap: 15px; }

        input, textarea { padding: 10px; font-size: 16px; }

        button { padding: 12px; background: #7b00ff; color: white; border: none; cursor: pointer; }

      </style>

    </head>

    <body>

      <h1> Send SMS with Vonage </h1>

      <form action="/send" method="POST">

        <label>Phone Number (e.g. 444155551234)</label>

        <input type="tel" name="to" required>

        <label>Message</label>

        <textarea name="text" rows="4" required></textarea>

        <button type="submit">Send SMS</button>

      </form>

    </body>

    </html>

  `);

});

Hinzufügen des Sendeendpunkts

Fügen Sie den Endpunkt hinzu, der die SMS über die Vonage Messages API sendet. Die vonage.messages.send() Methode akzeptiert ein Objekt mit Kanal gesetzt auf 'sms' und Nachrichtentyp eingestellt auf 'text'. Die Antwort enthält eine message_uuid die Sie verwenden können, um die Nachricht zu verfolgen.

app.post('/send', async (req, res) => {

  const { to, text } = req.body;

 try {

    const response = await vonage.messages.send({

      message_type: 'text',

      to: to,

      from: FROM_NUMBER,

      channel: 'sms',

      text: text

    });

    console.log('SMS sent:', response.message_uuid);

    res.sendSMS sent! Message ID: ${response.message_uuid});

  } catch (error) {

    console.error('Error sending SMS:', error);

    res.status(500).sendFailed to send SMS: ${error.message});

  }

});

Webhook-Endpunkte hinzufügen

Wenn jemand eine SMS an Ihre virtuelle Vonage-Nummer sendet, die Sie zuvor erworben haben, kommt die SMS-Nachricht bei Vonage an, und Vonage sendet eine POST-Anfrage an Ihren Google Cloud Run /webhooks/inbound Endpunkt, und schließlich verarbeitet Ihre Anwendung die Nachricht und antwortet mit 200 OK, wenn alles gut funktioniert. Fügen Sie die Webhook-Endpunkte hinzu, die diese Überprüfung verwenden, wie unten gezeigt. Der Status-Webhook (/webhooks/status) empfängt Zustellungsquittungen. So wissen Sie, ob Ihre Nachricht zugestellt wurde oder fehlgeschlagen ist.

app.post('/webhooks/inbound', (req, res) => {

  verifyJWT(req);

  console.log('Inbound SMS received:');

  console.log('From:', req.body.from);

  console.log('Text:', req.body.text);

  

  res.status(200).send('OK');

});

app.post('/webhooks/status', (req, res) => {

  verifyJWT(req);

  console.log('Status update:', req.body.status);

  res.status(200).send('OK');

});

const verifyJWT = (req) => {
  // Verify if the incoming request came from Vonage
  const jwtToken = req.headers.authorization.split(" ")[1];
  if(!verifySignature(jwtToken, process.env.VONAGE_API_SIGNATURE_SECRET)) {
    console.error("Signature does not match");
    throw new Error("Not a Vonage API request");
  }

  console.log("JWT verified");
}

npm install @vonage/jwt

Starten Sie den Server

Cloud Run setzt die PORT Umgebungsvariable automatisch, also verwenden wir diese, falls vorhanden. Fügen Sie den Code zum Starten des Servers hinzu:

const PORT = process.env.PORT || 8080;

app.listen(PORT, () => {

  console.logServer running on port ${PORT});

});

Begrenzte lokale Tests

Sie können die Anwendung lokal ausführen, um zu prüfen, ob sie fehlerfrei startet, aber Sie können noch keine SMS-Nachrichten senden. Die Vonage Messages API muss Ihre Webhook-URLs erreichen, um Anfragen zu verifizieren und Statusaktualisierungen zu senden. Aus diesem Grund stellen wir zuerst in Cloud Run bereit.

Wenn Sie verifizieren wollen, dass die Anwendung läuft, führen Sie die JavaScript-Datei aus.

node index.js

Öffnen Sie http://localhost:3000, um das Formular zu sehen. Die App sollte ohne Fehler starten, aber das Senden von Nachrichten wird fehlschlagen, bis wir die Webhooks einsetzen und konfigurieren.

Bereitstellen in Google Cloud Run

Da die App nun lokal funktioniert, können wir sie in Google Cloud Run bereitstellen, damit sie im Internet zugänglich ist und Webhooks von Vonage empfangen kann.

Google Cloud einrichten

Wenn Sie noch kein Google Cloud-Konto haben, erstellen Sie eines wie in den Voraussetzungen gefordert.

Installieren Sie die Google Cloud CLI

Herunterladen und Installieren der Google Cloud CLI für Ihr Betriebssystem herunter. Im nächsten Unterabschnitt zeige ich, wie man es unter macOS macht, aber Sie können den Link oben für andere Betriebssysteme verwenden. Ich wollte die Schritte zeigen, die ich selbst durchgeführt habe, weil ich auf einige Fehler gestoßen bin, und einige Tipps geben, die helfen könnten.

Unter macOS

# Download the archive (Apple Silicon)

curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-arm.tar.gz

# Extract it

tar -xzf google-cloud-cli-darwin-arm.tar.gz

# Run the install script

./google-cloud-sdk/install.sh

Falls ein Fehler in der Python-Version auftritt: Das gcloud CLI benötigt Python 3.10 oder höher. Wenn Sie einen TypeError über nicht unterstützte(n) Operandentyp(en) für |sehen, ist Ihr Python zu alt. Installieren Sie eine neuere Version mit Homebrew wie unten gezeigt (oder auf eine andere Weise, die Sie bevorzugen) und verweisen Sie gcloud darauf:

brew install python@3.12

export CLOUDSDK_PYTHON=$(brew --prefix python@3.12)/bin/python3.12

./google-cloud-sdk/install.sh

Das Installationsskript wird Sie fragen, ob Sie gcloud zu Ihrem PATH hinzufügen möchten. Wählen Sie Ja. Starten Sie dann die Eingabeaufforderung/das Terminal neu oder führen Sie es aus:

source ~/.zshrc

Initialisieren Sie nun gcloud:

gcloud init

Daraufhin öffnet sich ein Browserfenster, in dem Sie sich bei Ihrem Google Account anmelden und ein neues Google Cloud-Projekt auswählen oder erstellen können.

Ein Google Cloud-Projekt erstellen

Wenn Sie noch kein Projekt haben, legen Sie eines an. Die Projekt-IDs müssen weltweit eindeutig sein, daher können Sie einige zufällige Zeichen hinzufügen.

gcloud projects create vonage-sms-yourname --name="Vonage Messages API Demo"

gcloud config set project vonage-sms-yourname

Sie können ein Projekt auch über die Google Cloud-Konsole.

Aktivieren eines Google Cloud Billing Accounts

Für Cloud Run muss die Rechnungsstellung aktiviert sein. Gehen Sie zur Seite Abrechnung und verknüpfen Sie ein Abrechnungskonto mit Ihrem Projekt.

Erforderliche Google Cloud-APIs aktivieren

Aktivieren Sie die Cloud Build und Cloud Run APIs:

gcloud services enable cloudbuild.googleapis.com run.googleapis.com

Bereitstellen in Google Cloud Run

Für produktive Anwendungen sollten Sie Folgendes verwenden Google Geheimnis-Manager um sensible Werte zu speichern. In diesem Lernprogramm werden wir Umgebungsvariablen direkt übergeben.

Stellen Sie sicher, dass Ihr "private.key" Datei im Projektverzeichnis liegt. Sie wird bei der Bereitstellung mit Ihrem Quellcode gebündelt.

Einsetzen:

gcloud run deploy vonage-sms \

  --source . \

  --region us-central1 \

  --allow-unauthenticated \

  --set-env-vars "VONAGE_APPLICATION_ID=your_app_id" \

  --set-env-vars "VONAGE_NUMBER=444155551234" \

  --set-env-vars "VONAGE_API_SIGNATURE_SECRET=your_signature_secret"

Erstes Deployment: Sie sehen eine Aufforderung zum Erstellen eines Artifact Registry Repository namens cloud-run-source-deploy um Ihre Container-Images zu speichern. Geben Sie ein. y um fortzufahren.

Die erste Bereitstellung dauert nur ein paar Minuten. Wenn sie abgeschlossen ist, sehen Sie eine URL wie https://vonage-sms-abc123-uc.a.run.app.

Vonage Webhooks aktualisieren

Da Sie nun Ihre Cloud Run URL haben, gehen Sie zurück zu Ihrer Vonage-Anwendung und aktualisieren Sie die Webhook-URLs:

• Eingehende URL: https://your-cloud-run-url/webhooks/inbound

• Status-URL: https://your-cloud-run-url/webhooks/status

Vergessen Sie nicht, unten rechts auf der Seite auf Änderungen speichern zu klicken.

Testen Sie es aus

Es ist an der Zeit, alles, was wir eingerichtet haben, zu testen und zu sehen, wie es läuft!

Eine SMS senden

Öffnen Sie Ihre Cloud Run URL in einem Browser (die URL, die Sie nach der Bereitstellung erhalten haben, z. B. https://vonage-sms-abc123-uc.a.run.app). Sie sollten das SMS-Formular sehen, das wir erstellt haben. Geben Sie Ihre Telefonnummer und eine Nachricht ein und drücken Sie dann auf Senden. Wenn alles richtig konfiguriert ist, erhalten Sie die SMS innerhalb weniger Sekunden auf Ihrem Telefon. Sie können prüfen länderspezifische Funktionen und Einschränkungen.

Empfangen einer SMS

Testen Sie nun die andere Richtung. Senden Sie eine SMS von Ihrem Telefon an die Vonage-Nummer, die Sie erworben und mit der von Ihnen erstellten Anwendung verknüpft haben. Dies löst den von uns eingerichteten eingehenden Webhook aus. Sie können die Protokolle an zwei Stellen überprüfen:

Über die Befehlszeile

gcloud run logs read vonage-sms --region us-central1

Über das Vonage Dashboard

Gehen Sie zu Ihrer Vonage-Applikation, klicken Sie auf Ihre Anwendung und überprüfen Sie den Abschnitt Logs, um die Nachrichtenaktivität und eventuelle Webhook-Fehler zu sehen. Sie sollten Ihre eingehende Nachricht mit der Nummer und dem Text des Absenders protokolliert sehen.

Schlussfolgerung

Sie haben eine SMS-Anwendung auf Google Cloud Run unter Verwendung der Vonage Messages API erstellt und bereitgestellt. Die Anwendung kann Nachrichten über ein Webformular senden und eingehende Nachrichten über Webhooks empfangen.

Weitere Lektüre

• Vonage Messages API-Dokumentation

• Google Cloud Run Dokumentation

• Wie man mit Node.js und Express SMS-Nachrichten sendet und empfängt

• SMS-Nachrichten mit Cloud-Funktionen für Firebase Gen 2 versenden

• Wie man Umgebungsvariablen in Node.js verwendet