Abfrage des Status der Londoner U-Bahn mit der SMS API von Vonage

Heute werden wir eine Anwendung erstellen, mit der wir den Status einer bestimmten Linie der Londoner U-Bahn mithilfe der Vonage SMS API. Wir werden die Transport for London (TFL API) nutzen, um Echtzeitdaten über den Status einer vom Benutzer ausgewählten U-Bahn-Linie abzurufen. Der Auslöser wird eine eingehende SMS an unsere virtuelle Nummer sein. Klingt das wie ein Plan? Dann befolgen Sie dieses Tutorial. Wir werden denselben Status erhalten wie auf der ihrer Website per SMS direkt auf unser Mobiltelefon. Dies ist besonders praktisch, wenn Sie aus irgendeinem Grund keinen Internetzugang haben, um Google Maps/Citymapper zu überprüfen, oder wenn Sie Ihr monatliches Datenvolumen überschritten haben.

Unser Anwendungs-Workflow wird in etwa wie das folgende Diagramm aussehen:

sketch diagram of workflow

Ich weiß, 😌 wahrscheinlich leben Sie nicht in London, und Sie denken vielleicht, dass dieses Tutorial für Sie nicht relevant ist. Ich glaube aber wirklich, dass dies ein sehr anschauliches Beispiel dafür ist, was man auf Vonage aufbauen kann.

Diese Anleitung führt Sie durch alle Schritte, um diese Anwendung von Grund auf zu erstellen. Wenn Sie jedoch lieber auf das fertigen Repositoryzugreifen möchten, schauen Sie es sich bitte an!

Voraussetzungen

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.

In diesem Lernprogramm wird auch eine virtuelle Telefonnummer verwendet. Um eine zu erwerben, gehen Sie zu Rufnummern > Rufnummern kaufen und suchen Sie nach einer Nummer, die Ihren Anforderungen entspricht.

Sind Sie bereit, mit dem Bau zu beginnen?

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

Für den ersten Teil des Tutorials benötigen wir:

• Grundkenntnisse in Javascript/node.js.

• Sie müssen Folgendes verwenden ngrok verwenden, um Ihren lokalen Server für das Internet freizugeben, damit Vonage ihn erreichen kann. Wir haben eine ausführliche Anleitung zu diesem Thema.

Wenn Sie Ihre Anwendung auf Heroku bereitstellen möchten, benötigen Sie außerdem:

• A Heroku Account (wir werden nur die Free-Tier-Version verwenden).

• Einige grundlegende git Befehle, um unsere Anwendung auf Heroku bereitzustellen.

Unser Projekt einrichten

Erstellen Sie einen Projektordner mit dem Namen tubestatus auf Ihrem lokalen Rechner und wechseln Sie dorthin.

mkdir tubestatus && cd tubestatus

Erstellen wir unsere Hauptdatei, in der wir unseren Code speichern werden. Außerdem erstellen wir unsere .env Datei, in der wir unsere Vonage- und Anmeldedaten sowie einige andere Variablen speichern werden.

Der nächste Schritt ist die Erstellung der package.json Datei.

Installieren und speichern wir die erforderlichen Abhängigkeiten.

Jetzt müssen wir eine Vonage-App erstellen und eine Nummer kaufen.

Installieren Sie die Vonage CLI global mit diesem Befehl:

npm install @vonage/cli -g

Als nächstes konfigurieren Sie die CLI mit Ihrem Vonage-API-Schlüssel und -Geheimnis. Sie finden diese Informationen im Entwickler-Dashboard.

vonage config:set --apiKey=VONAGE_API_KEY --apiSecret=VONAGE_API_SECRET

Lassen Sie ngrok auf demselben Port laufen, auf dem unser lokaler Server lauscht (in meinem Fall 3000).

ngrok http 3000

Verwenden Sie nun die CLI, um eine Vonage-Anwendung zu erstellen und einen Webhook zu Ihrer ngrok-URL zu erstellen.

Sie sollten den Ausweis, der nach dem Ausfüllen des Formulars ausgedruckt wird, speichern. Application created:. Sie werden ihn in Kürze benötigen.

Jetzt brauchen Sie eine Nummer, damit Sie Anrufe empfangen können. Sie können eine Nummer mieten, indem Sie den folgenden Befehl verwenden (ersetzen Sie die Landesvorwahl durch Ihre Vorwahl). Wenn Sie sich zum Beispiel in den USA befinden, ersetzen Sie GB durch US:

Verknüpfen Sie nun die Nummer mit Ihrer App:

vonage apps:link --number=VONAGE_NUMBER APP_ID

Füllen Sie schließlich die Datei .env Datei mit dem Vonage-API-Schlüssel für apiKey, dem Vonage-Geheimnis für apiSecretund der soeben erworbenen Nummer für from. Als nächstes fügen Sie Ihre TFL app_id und app_key.

Beginnen wir mit den lustigen Dingen

Wie immer benötigen wir zu Beginn unseres Projekts alle Abhängigkeiten. Wir werden das express Framework, um unsere Anwendung zu erstellen. Wir werden die dotenv Bibliothek, damit wir mit Umgebungsvariablen arbeiten können. Wir verwenden body-parser damit wir die eingehenden Anfragen vom Vonage-Server analysieren können. Für die API-Anfragen an die TFL-API habe ich die request Bibliothek gewählt, da ich sie für recht einfach halte, aber Sie können auch jede andere verwenden, wie z.B. axios. Schließlich, und das ist das Wichtigste, 😊 benötigen wir die Vonage-Bibliothek, um den Leitungsstatus an den Benutzer zurückzusenden.

Fügen Sie den folgenden Code in Ihre neu erstellte Datei ein. Wir importieren alle installierten Abhängigkeiten und haben eine Variable definiert, die alle akzeptierten Zeilennamen enthält, die von der TFL-API bereitgestellt werden. Wir wollen keine Anfrage an die TFL-API senden, wenn der Benutzer keinen gültigen Zeilennamen angibt (ich werde gleich erklären, warum alle Werte groß geschrieben werden). Die Variable mit der Bezeichnung status enthält alle relevanten Statusangaben in Bezug auf den Status der besagten Leitung. Fügen Sie außerdem die verschiedenen Anmeldeinformationen hinzu, die Sie benötigen, um die APIs von Vonage bzw. TFL zu nutzen. Diese werden aus der Datei .env Datei:

const Vonage = require('@vonage/server-sdk')
const express = require('express');
const bodyParser = require('body-parser');
const port = process.env.PORT || 3000;
const request = require('request');
const dotenv = require('dotenv');

let status = []

dotenv.config();

const lines =['CENTRAL','BAKERLOO', 'DISTRICT', 'VICTORIA', 'NORTHERN', 'CIRCULAR', 'HAMMERSMITH-CITY', 'JUBILEE', 'METROPOLITAN', 'PICCADILLY', 'WATERLOO-CITY' ];

const vonage = new Vonage({
  apiKey: process.env.apiKey,
  apiSecret: process.env.apiSecret
})

In den folgenden Zeilen initiieren wir unsere Anwendung und definieren einige grundlegende Middleware. Beachten Sie, dass wir den Port 3000 für unseren Server definiert haben, aber Sie können auch einen anderen wählen. Berücksichtigen Sie, dass dazwischen etwas Platz ist (auskommentiert), der mit unserer Route für eingehende Anfragen ausgefüllt werden wird:

const app = express();

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

//We will define our route here

app.listen(port, ()=>{console.log('App listening in port ', port)});

Lassen Sie uns zwei Funktionen definieren, um den Code ein wenig aufzuräumen. Die erste Funktion sendSms() nimmt zwei Parameter entgegen: die Telefonnummer des Benutzers und den Text, der an den Benutzer zurückgesendet werden soll. Wir werden einen kleinen Teil des Codes wiederverwenden.

function sendMessage(to, message){
  vonage.message.sendSms(process.env.from, to, message, (err, responseData) => {
    if (err) {
        console.log(err);
    } else {
        if(responseData.messages[0]['status'] === "0") {
            console.log("Message sent successfully.");
        } else {
            console.log(`Message failed with error: ${responseData.messages[0]['error-text']}`);
        }
    }
})
}

Die zweite Funktion checkLineStatus() nimmt zwei Parameter entgegen: den Namen der Leitung und die Telefonnummer des Benutzers, da wir eine Nachricht mit den angeforderten Informationen an den Benutzer zurücksenden werden.

function checkLineStatus(Line, number) {

    var options = {
        json: true,
        url: 'https://api.tfl.gov.uk/Line/' + Line + '/status?app_id=' + app_id + '&app_key=' + app_key,
    }

    request(options, function (err, res, body) {
        if (err) {
            console.log(err)

        }
        else {
            if (body[0].lineStatuses[0].statusSeverityDescription === 'Good Service') {
                sendMessage(number, 'There is a ' + body[0].lineStatuses[0].statusSeverityDescription + ' operating on ' + body[0].name + ' line')

            }
            else {
                for (let i = 0; i < body.length; i++) {
                    for (let j = 0; j < body[i].lineStatuses.length; j++) {
                        status.push(body[i].lineStatuses[j].reason)
                    }
                }
                sendMessage(number, status)
                console.log(status)
            }
        }
    })
}

Wenn der Status der angegebenen Leitung "Good Service" ist (beachten Sie, dass die TFL-API dies immer zurückgibt, wenn der normale Dienst läuft), senden Sie dies an den Benutzer zurück. Andernfalls ist es wichtig zu berücksichtigen, dass die TFL-API bei einer Leitungsunterbrechung eine reason innerhalb des lineStatus Objekt. Das ist es, was wir für jede Unterbrechung in unser Array schieben (hoffentlich keine für die Pendler 😂). Vergessen Sie nicht, dass wir innerhalb dieser Funktion auch die Funktion sendSms() Funktion aufrufen, um dem Benutzer in beiden Szenarien den Leitungsstatus zu übermitteln.

Als Letztes werden wir unsere eingehende Route ausfüllen, um eingehende Nachrichten von den Benutzern abzuhören. Schauen wir uns einmal an, wie eine eingehende Nachricht von Vonage aussieht.

Um unser Ziel zu erreichen, müssen wir zwei der oben genannten Parameter speichern: den vom Benutzer gesendeten Text (Zeilenname) und die Nummer des Benutzers. Diese werden in unseren neuen Variablen gespeichert (Tube_line und Number_msisdn ) gespeichert, sobald unsere /inbound Route getroffen wird.

Es ist wichtig zu beachten, dass wir die Tube-Zeile groß schreiben. Der Grund dafür ist, dass wir eine angegebene Zeichenkette mit einer anderen Zeichenkette vergleichen wollen, ohne Rücksicht auf Groß- und Kleinschreibung (der Benutzer kann uns Zentrale, CENTRAL oder zentral). Indem wir die Eingabe des Benutzers großschreiben und sie mit unserem lines Array (bereits großgeschrieben) umgehen wir dies. Fügen Sie den folgenden Code an der Stelle ein, die wir für unsere Route reserviert haben.

app.post('/inbound', (req, res) => {
    let Tube_Line = req.body.text.toUpperCase()
    let Number_msisdn = req.body.msisdn

    if ((lines.indexOf(Tube_Line) > -1)) {
        checkLineStatus(Tube_Line, Number_msisdn)
    }
    else {
        sendMessage(Number_msisdn, 'Valid values are ' + lines)

    }

    res.status(204).send()
})

Das (lines.indexOf(Tube_Line) > -1) Bit ermöglicht es uns zu prüfen, ob der Wert, der in Tube_line gespeicherte Wert mit einem der Werte in dem lines Array übereinstimmt. Diese Methode gibt den ersten Index zurück, bei dem das gegebene Element in einem Array gefunden werden kann, oder -1, wenn es nicht in einem Array vorhanden ist. Wir wollen den Status einer bestimmten Zeile nur überprüfen, wenn die Eingabe mit einem der gültigen Werte übereinstimmt. Andernfalls erhalten wir einen schönen HTTP 404 von der TFL-API zurück. Angenommen, wir sind sanft genug, um dem Benutzer mitzuteilen, dass er einen falschen Wert eingegeben hat, senden wir ihm eine Nachricht mit den gültigen Werten zurück. Dies geschieht, wenn die indexOf-Methode, wie oben erläutert, gleich -1 ist.

Also gut, es ist Zeit, das auszuprobieren 🙈. Nehmen wir unser Telefon und senden wir eine SMS mit einem beliebigen Leitungsnamen, der zu unserem lines Array übereinstimmt, an Ihre Vonage-Nummer. Als Beispiel werde ich den Namen der Leitung abfragen, mit der ich jeden Tag zur Arbeit fahre.

demo of app performance on phone

💃💃 Wie Sie sehen können, erhalten wir kurz nach dem Senden einer Nachricht an unsere zuvor konfigurierte virtuelle Nummer eine SMS mit dem Status der angeforderten Leitung. Gut gemacht und danke, dass Sie so weit gekommen sind!

Mocking Inbound-Nachrichten

Wenn Sie aus irgendeinem Grund nicht die Möglichkeit haben, Ihr Mobiltelefon zu benutzen, oder wenn Sie keine SMS manuell senden möchten, um die Anwendung zu testen, haben wir auch für Sie gesorgt. Eine eingehende Nachricht wird einfach als GET- oder POST-Anfrage an Ihren Webhook dargestellt. Sie können die Methode, die Vonage für die Zustellung Ihrer eingehenden Nachrichten verwenden soll, in Ihren Vonage Dashboard-Einstellungen. Ich verwende für dieses Tutorial POST.

Unter Berücksichtigung dieser Tatsache können wir das Verhalten einer eingehenden Nachricht simulieren, indem wir manuell auf unseren lokalen Server zugreifen, der mit ngrok ausgesetzt ist, um zu sehen, ob die Anwendung wie gewünscht funktioniert. Ich werde Folgendes verwenden POSTMAN aber Sie können auch jeden anderen Dienst Ihrer Wahl verwenden. Wir werden eine POST-Anfrage an unseren Inbound-Webhook stellen und einen generischen rohen JSON-Body definieren (wie der, den Vonage für eine Inbound-Nachricht senden würde). Denken Sie jedoch daran, die msisdn zu ändern, damit unsere Anwendung weiß, wo sie antworten soll. Ersetzen Sie auch den text Parameter, um mit verschiedenen Werten für den Zeilennamen zu spielen. Sie können absichtlich einen ungültigen Wert eingeben, damit Sie eine Nachricht mit den zulässigen Werten erhalten. Meine API-Anfrage sieht etwa so aus:

In diesem Fall ist der to Parameter nicht relevant, also habe ich ihn auf einen Zufallswert gesetzt. Es ist wichtig, die Content-Type Kopfzeile hinzuzufügen und sie auf application/json zu setzen, damit unsere Anwendung weiß, wie sie mit diesen Daten umgehen soll. Wie Sie unten rechts sehen können, gibt unsere Anwendung eine HTTP 204 zurück, wie sie in unserer /inbound Route über die Funktion res.status(204).send()

Was kommt als Nächstes? Bereitstellen auf Heroku

Heroku ist eine Plattform zur einfachen Bereitstellung Ihrer Webanwendung und zur Skalierung Ihrer Dienste entsprechend Ihren Anforderungen. Es werden auch einige nützliche Add-ons angeboten, um einige tägliche Aufgaben zu vereinfachen. Wir werden Heroku nutzen, weil es ziemlich einfach zu bedienen ist und die Dokumentation auf der Heroku-Website. Durch die Verwendung von Heroku können wir uns den Aufwand ersparen, unseren Server zu mieten und zu konfigurieren.

Das Konzept der dynos existiert innerhalb der Heroku-Plattform. Dies ist nichts anderes als ein Container, in dem Ihre Anwendung bereitgestellt wird. Die Nutzung Ihrer Anwendung verbraucht Dyno-Stunden (nur wenn sie läuft), aber keine Sorge, es werden 550 kostenlose Stunden pro Monat angeboten oder 1000 Stunden, wenn Sie sich bereit erklären, Ihren Account durch Angabe einer Kreditkarte zu verifizieren. Sie können Ihre Anwendung unter Berücksichtigung des Verkehrsaufkommens problemlos vergrößern oder verkleinern, aber das würde den Rahmen dieses Tutorials sprengen.

Wenn Sie noch nie eine Heroku-Anwendung bereitgestellt haben, lohnt es sich vielleicht, die Dokumentationen zu lesen, oder zumindest den Teil, in dem erklärt wird wie man eine node.js-Anwendung einsetzt. Um zu bestimmen, wie Ihre Anwendung gestartet werden soll, sucht Heroku zunächst nach einem Procfile. Dabei handelt es sich um eine Datei, in der die Befehle festgelegt sind, die von der Anwendung beim Start ausgeführt werden. Wenn kein Procfile für eine Node.js-App existiert, versucht Heroku, einen Standard-Webprozess über das Startskript in Ihrer package.json zu starten.

Bearbeiten wir unsere package.jsonso, dass der Teil, der die Skripte Eigenschaft enthält, dieses Bit enthält:

"scripts": {
    "start": "node server.js"
  },

Dann werden wir eine .gitignore Datei, um sicherzustellen, dass lokale Umgebungsvariablen, Build-bezogene Ausgaben und Module nicht in das Git-Repository übertragen werden

/node_modules
npm-debug.log
.DS_Store
/*.env

Der einzige Nachteil bei der Verwendung der freien Schicht ist, dass es nach 30 Minuten Inaktivität ein wenig dauern kann, bis Ihre Anwendung wieder aufwacht (wenn sie eine neue Anfrage erhält). Pragmatisch ausgedrückt bedeutet dies, dass es zu einer leichten Verzögerung beim Empfang der Nachricht von Vonage kommen kann, wenn die Anwendung eine Zeit lang inaktiv war. Dies liegt daran, dass die Anfrage an die TFL-API bearbeitet wird, sobald die Anwendung erneut gestartet wird. Dies ist akzeptabel, da diese Anwendung nicht zeitkritisch ist. Wenn Ihnen dies jedoch nicht ausreicht, können Sie auf den kostenpflichtigen Dienst umsteigen und einen eigenen Dyno für Ihre Anwendung laufen lassen.

Um zu bestimmen, wie Ihre Anwendung gestartet werden soll, sucht Heroku zunächst nach einem Procfile. Wenn kein Procfile für eine Node.js-App existiert, versucht Heroku, einen Standard-Webprozess über das Startskript in Ihrer package.json zu starten. Der Befehl in einem Web-Prozesstyp muss sich an die in der Umgebungsvariablen PORT angegebene Portnummer binden. Wenn dies nicht der Fall ist, wird der Dyno nicht gestartet.

Vergewissern Sie sich, dass Sie über die Heroku CLI installiert haben und führen Sie dann die folgenden Befehle nacheinander in Ihrem Projektordner aus:

Zu diesem Zeitpunkt haben wir ein neues Git-Repository erstellt, alle Änderungen zu unserem Repository hinzugefügt und unseren ersten Commit eingereicht. Jetzt erstellen wir unsere Anwendung und stellen sie auf Heroku bereit:

In diesen wenigen Zeilen haben wir unsere Heroku-Anwendung erstellt und die Änderungen an Heroku übertragen. Wenn alles wie erwartet gelaufen ist, sollten Sie Ihre eigene Anwendung erstellt haben. Außerdem wird Ihnen die URL mitgeteilt, unter der Ihre Anwendung nach der Bereitstellung zu finden ist. Gut gemacht!

Schließlich müssen wir unserer Anwendung mitteilen, wo sie die Umgebungsvariablen findet, da wir keine angegeben haben .env file. Führen Sie diesen Befehl aus, um die erforderlichen Konfigurationsvariablen zu setzen

Sie können überprüfen, ob diese Variablen korrekt hinzugefügt wurden, indem Sie einen Blick auf Ihre Anwendungseinstellungen unter Heroku Dashboard. So sieht unsere Anwendung im Heroku-Dashboard aus. Wenn wir auf Konfig-Variablen aufdeckenklicken, sehen wir die Umgebungsvariablen, die über die Heroku-CLI konfiguriert wurden.

Zusammenfassend lässt sich sagen, dass dieser Prozess relativ einfach war! Ich war in der Lage, dies innerhalb von wenigen Minuten zum Laufen zu bringen, was hervorragend ist. Jetzt müssen wir nur noch unsere Nummer aktualisieren, damit sie auf unseren neuen Webhook verweist. Dazu können Sie einfach die obigen Schritte wiederholen (als wir unsere Nummer über die Numbers API konfiguriert haben). Zur Erinnerung: Vergessen Sie nicht, das /inbound am Ende der URL, die der Route in unserem Skript entspricht.

Wenn wir eine SMS senden, sobald wir die Inbound-Webhook-URL für unsere Nummer aktualisiert haben, wird dies hoffentlich wie erwartet funktionieren. So sieht ein Unterbrechungsstatus aus. Es scheint, dass es notwendig gewesen wäre, unsere Reise zu verschieben, wenn wir über die District Line nach Heathrow gereist wären, als ich dies getestet habe.

Das war's für heute, aber wenn Sie weiter mit unseren APIs herumspielen wollen, finden Sie vielleicht die folgenden Links hilfreich:

• Dokumentation für die verschiedenen APIs auf dem Entwicklerportal

• Reihe von Anleitungen für verschiedene Vonage APIs

• Wenn Sie uns brauchen, versuchen Sie den Vonage Community Slack-Kanal

• Lassen Sie uns wissen, was Sie denken, indem Sie tweeten unter @VonageDev