Verwendung von Azure-Funktionen mit Python

Hier bei Vonage versuchen wir, unsere APIs so einfach wie möglich zu gestalten. Eine unangenehme Sache, die wir jedoch nicht vermeiden können, ist, dass viele unserer APIs, wie die Vonage Voice APIIhre Anwendung fragen müssen, was sie während eines Anrufs tun sollen. Das bedeutet, dass Sie Ihren eigenen Server. Oder wollen Sie das?

Serverlos mit Azure-Funktionen

Microsoft bietet Azure-Funktionen Unterstützung für Python, und die ist großartig! Es wurde viel Unterstützung bereitgestellt, damit Sie schnell loslegen können, und es funktioniert mit Standard-Python-Projekt-Idiomen, wie requirements.txt. Damit können Sie kleine, eigenständige Funktionen in Python schreiben und sie dann problemlos in der Azure-Cloud bereitstellen.

Es gibt eine kostenlose Version, die eine Million Funktionsausführungen pro Monat kostenlos zur Verfügung stellt. Das sollte für eine kleine Demo-App oder sogar eine kleine Produktions-App ausreichen!

Werden wir funktional

Ich zeige Ihnen, wie Sie eine einfache Vonage-App mit zwei auf Azure Functions gehosteten Webhooks erstellen können. Die Idee ist, dass der Benutzer eine Vonage-Nummer anruft (was den ersten Webhook auslöst) und von einer Roboterstimme begrüßt wird. Der Benutzer wird aufgefordert, seine Stimmung einzugeben. Sie geben eine 1 für "glücklich", eine 2 für "unglücklich" und jede andere Option ein, die Sie wünschen. An diesem Punkt wird der zweite Endpunkt mit der Eingabe aufgerufen, und beide generieren eine entsprechende Antwort.

Ich beschreibe alle Schritte zur Erstellung des Codes und der Konfiguration, die Sie benötigen, aber wenn Sie das Endergebnis sehen möchten, finden Sie den Code auf GitHub

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.

Anforderungen

Wie Sie unten sehen können, gibt es einige einige ein paar Dinge, die Sie einrichten oder installieren müssen, aber glauben Sie mir, es ist es wert.

• A frei Azure Account, damit Sie Ihre Azure-Funktionen veröffentlichen können.

• Installieren Sie das Vonage CLI-Werkzeug und lesen Sie diesen kurzen Blogbeitrag wie Sie damit anfangen können.

  Dies gibt Ihnen den vonage Befehl in Ihrer Konsole, mit dem Sie Vonage Voice Applications erstellen, virtuelle Numbers kaufen und beides miteinander verbinden können.

• installieren Ngrok

  Dies gibt Ihnen den ngrok Befehl in Ihrer Konsole, der Anfragen an Ihren Entwicklungsrechner tunnelt und es Vonage ermöglicht, Webhooks an Ihren Entwicklungsserver zu senden.

• Installieren Sie die Azure Functions Kern-Tools

  Dadurch erhalten Sie den func Befehl in Ihrer Konsole, mit dem Sie Ihr Azure Functions-Projekt booten und lokal für Entwicklung und Tests ausführen können.

• Installieren Sie die Azure CLI.

  Dadurch erhalten Sie den az Befehl in Ihrer Konsole. Damit können Sie verschiedene Objekte in Azure erstellen und Ihre Azure-Funktionen veröffentlichen!

Erstellen Ihrer ersten Funktion

Sobald Sie alle oben genannten Anforderungen installiert haben, öffnen Sie Ihre Konsole. Sie werden einen Standardcode erstellen, um mit der Erstellung Ihrer Azure-Funktionen zu beginnen.

Erstellen wir zunächst ein neues Azure Functions-Projekt mit dem Befehl Azure Functions Core Tools, func. Führen Sie func init um ein leeres Azure Functions-Projekt zu erstellen:

Wechseln Sie nun in das neue Projektverzeichnis und verwenden Sie func new um eine neue Azure-Funktion zur Beantwortung eines eingehenden Anrufs zu erstellen. Wenn Sie gefragt werden, welche Art von Funktion Sie erstellen möchten, wählen Sie "5", HTTP-Trigger. Dies ist die Art von Azure-Funktion, die auf HTTP-Anfragen antwortet. Wenn Sie gefragt werden, wie die Funktion genannt werden soll, geben Sie answer_inbound ein, da der Endpunkt zur Beantwortung eingehender Telefonanrufe verwendet werden soll.

Aus der obigen Ausgabe können Sie ersehen, dass func eine Python-Datei erstellt hat, __init__.py und eine Konfigurationsdatei, function.json.

Bearbeiten Sie function.json und setzen Sie "authlevel" auf "anonymous". Dies ermöglicht Vonage den Aufruf ohne zusätzliche Authentifizierung.

{
    "scriptFile": "__init__.py",
    "bindings": [
    {
        "authLevel": "anonymous",
        "type": "httpTrigger",
        ...

Führen Sie die Boiler-Plate-Python-Funktion aus, indem Sie den func host Befehl:

Wenn Sie Ihren Browser unter der URL http://localhost:7071/api/answer_inbound?name=bob aufrufen, sollten Sie "Hello bob!" sehen. Gut gemacht! Sie haben Ihre erste Azure-Funktion "geschrieben"!

Von der Azure-Funktion zum Telefonat

Sie möchten, dass Ihre Funktion einige NCCO-Aktionen ausgibt, so dass Vonage weiß, was zu tun ist, wenn jemand Ihre Nummer wählt. Dazu müssen Sie den Funktionscode durch den folgenden ersetzen:

def main(req: func.HttpRequest) -> func.HttpResponse:
    return func.HttpResponse(json.dumps([
        {
            'action': 'talk',
            'text': 'Welcome to the mood reporting hotline. Please enter 1 if you are happy, or 2 if you are unhappy.',
            'bargeIn': True,
        },
        {
            'action': 'input',
            'eventUrl': [ f'https://{req.headers["host"]}/api/mood_feedback' ],
            'maxDigits': 1,
            'timeOut': 10,
        },
    ]), mimetype='application/json')

Der obige Code gibt eine JSON-Antwort zurück, die zwei NCCO-Aktionen enthält. Eine NCCO-Action ist eine Anweisung an Vonage, die besagt, wie der Anruf zu behandeln ist. In diesem Fall haben wir zwei Aktionen:

• Die Aktion talk Aktion weist Vonage an, dem Anrufer eine Nachricht vorzulesen.

• Die Aktion input Aktion teilt Vonage mit, dass der Benutzer eine Zahl eingeben soll, die dann an die in eventURL

Denn wir haben uns bargeIn auf true in der talk gesetzt haben, wird Vonage, wenn der Anrufer eine Ziffer eingibt, bevor die input Aktion begonnen hat, geht Vonage davon aus, dass der Anrufer einfach nur ungeduldig war, und führt die folgende input Anweisung.

Wenn Sie func host start erneut ausführen, werden Sie beim Laden Ihres Browsers unter http://localhost:7071/api/answer_inbound?name=bob aufrufen, sollten Sie ein Bündel von JSON sehen, das die oben beschriebenen Aktionen enthält.

Tunnel zu Ihrem Entwicklungsserver

Während Sie noch am Entwickeln sind, möchten Sie, dass Vonage auf Ihre Funktionen zugreifen kann, damit Sie sie testen können. Ich empfehle, den Anweisungen meines Kollegen Aaron Bassett geschrieben hat, um Ihren lokalen Entwicklungsserver mit der Vonage-API über einen Ngrok-Tunnel zu verbinden.

Wenn Sie nun wissen, wie Ngrok funktioniert, können Sie in einem separaten Konsole ausführen:

Überprüfen Sie, ob Sie immer noch func host start im anderen Konsolenfenster und laden Sie die Ngrok-URL, die ausgedruckt wurde, gefolgt von /api/answer_inbound. Sie sollte in etwa so aussehen https://r4nd0m.ngrok.io/api/answer_inbound (aber mit Ihrem eigenen zufälligen Präfix anstelle von r4nd0m!).

Wenn das funktioniert, ist es an der Zeit, Vonage mitzuteilen, wie Sie Ihren Entwicklungsserver kontaktieren können!

Verbinden Sie Vonage mit Ihrem Entwicklungsserver

Wenn Sie dies noch nicht getan haben, müssen Sie die Vonage CLI nach der Installation mit Ihrem API-Schlüssel und dem Geheimnis konfigurieren.

Erstellen Sie eine neue Vonage Voice Application, indem Sie vonage apps:create und geben Sie ihr den Namen "Enter Your Mood", wenn Sie dazu aufgefordert werden. Folgen Sie den weiteren Anweisungen in der Befehlszeile, um Ihre Anwendung zu erstellen.

Dadurch wird eine App namens "Enter Your Mood" im Vonage API Dashboard erstellt. Wenn ein eingehender Anruf an eine mit dieser App verknüpfte Telefonnummer erkannt wird, ruft sie den Webhook unter https://r4nd0m.ngrok.io/api/answer_inboundauf und gibt die Details des eingehenden Anrufs bekannt. Es wird erwartet, dass die Azure-Funktion an diesem Endpunkt mit NCCO-Aktionen antwortet ... kommt Ihnen das bekannt vor? Es wurde auch ein privater Schlüssel in einer Datei namens "private.key" gespeichert, den wir im Moment nicht verwenden werden.

Sie müssen nun eine virtuelle Nummer kaufen und diese mit der Vonage-App verknüpfen. Notieren Sie sich also die soeben erstellte Anwendungs-ID (hier: "4f33ff5e-dbbc-11e9-8656-6bdabe7b8258").

Kaufen Sie eine virtuelle Nummer, wenn Sie nicht schon eine haben. Ich empfehle den Kauf über das Vonage API Dashboardzu kaufen, aber Sie können Sie können aber auch mit dem Vonage CLI-Tool nach Nummern suchen und sie kaufen. Sobald Sie eine Nummer haben, verknüpfen Sie sie mit dem folgenden Befehl mit der App, wobei Sie die Telefonnummer durch die gerade gekaufte Nummer und die Anwendungs-ID durch die oben notierte ersetzen:

Rufen Sie nun mit Ihrem Telefon die Nummer an, die Sie gerade verlinkt haben.

Was passieren sollte: Es meldet sich eine Voice mit der oben genannten Nachricht. Wenn Sie eine Nummer auf dem Ziffernblock Ihres Telefons eingeben, ertönt wahrscheinlich ein Signalton und der Anruf wird abgebrochen. Das liegt daran, dass die zweite URL, unter /api/mood_feedback noch nicht existiert!

Handhabung von Eingaben

Führen Sie dazu ähnliche Schritte aus wie oben:

• Führen Sie aus. func new, wählen Sie HTTP trigger und geben Sie als Funktionsnamen "mood_feedback" ein.

• Ändern Sie die function.json Datei und setzen Sie authLevel auf anonymous.

Öffnen Sie nun __init__.py und ersetzen Sie den Funktionscode durch den folgenden:

def main(req: func.HttpRequest) -> func.HttpResponse:
    try:
        req_body = req.get_json()
        return func.HttpResponse(json.dumps([
            {
                'action': 'talk',
                'text': 'Thank you for telling us how you feel.',
            },
        ]), mimetype='application/json')
    except ValueError:
        return func.HttpResponse(
            "Could not parse request body.",
            status_code=400
        )

Es gibt hier ein wenig zusätzlichen Code, der zum Extrahieren der vom Telefonanruf gesendeten Daten verwendet wird, aber im Moment sollten Sie einfach in der Lage sein, die Nummer erneut anzurufen, und dieses Mal Wenn Sie während des Anrufs eine Nummer eingeben, sollten Sie die Nachricht "Danke, dass Sie uns gesagt haben, wie Sie sich fühlen" hören.

Machen Sie die Antwort dynamisch

Wenn das funktioniert, sollten wir dafür sorgen, dass die Antwort auf den Aufruf etwas freundlicher ausfällt. Fügen Sie oberhalb der Funktion die folgenden globalen Variablen hinzu:

RESPONSES = {
    "1": "It's great that you're so happy!",
    "2": "I'm sorry that you're unhappy.",
}
UNEXPECTED_RESPONSE = "I'm sorry, I don't understand that feedback."

Ersetzen Sie nun in dem NCCO, das Sie zurückgeben, die Zeichenfolge durch RESPONSES.get(req_body['dtmf'], UNEXPECTED_RESPONSE). Dieser Ausdruck extrahiert den DTMF-Code aus der Anfrage (req_body['dtmf']), versucht, die zugehörige Antwort in RESPONSESzu finden, und wenn dieser Schlüssel nicht existiert, fällt er zurück auf UNEXPECTED_RESPONSE. Rufen Sie Ihre Nummer an und probieren Sie es aus!

Erstellen einer Funktions-App auf Azure

Was Sie bis jetzt getan haben, ist großartig - Solange Ihr Entwicklungsrechner eingeschaltet ist und Sie Konsolenfenster geöffnet haben, in denen func host & ngrok. Aber das ist unpraktisch. Deshalb zeige ich Ihnen jetzt, wie Sie den Code, den Sie geschrieben haben, in Azure Functions bereitstellen, damit Microsoft ihn für Sie hosten kann!

Um mit den Azure-Servern zu interagieren, verwenden wir den Befehl Azure CLI, az.

Zunächst müssen Sie sich bei Ihrem Azure Account anmelden, indem Sie az login. Es wird der Browser geladen und Sie werden aufgefordert, sich bei Ihrem Azure Account anzumelden. Wenn Sie sich noch nicht für ein Azure-Konto angemeldet haben, können Sie das jetzt tun.

Nun führen Sie die drei folgenden az Befehle aus - ich habe jedem von ihnen einen Kommentar hinzugefügt, damit Sie sehen können, was sie tun. Die einzige Änderung, die Sie vornehmen müssen, ist das Ersetzen von MYVONAGEFUNCTIONSTORE durch etwas global Eindeutiges ersetzen. Der tatsächliche Name, den Sie wählen, ist nicht wichtig - er ist nur ein Ort, an dem die Daten für Ihre laufenden Funktionen gespeichert werden, und wird von den Benutzern nicht gesehen. Sie müssen auch den Namen moodfeedbackapp in etwas global Eindeutiges ändern.

Veröffentlichen Sie Ihre Funktion in Azure

Sie können überprüfen, ob Ihre Funktionen ordnungsgemäß bereitgestellt werden, indem Sie zu https://moodfeedback.azurewebsites.net/api/answer_inbound (Sie müssen "moodfeedback" durch den Namen Ihrer eigenen Funktion ersetzen, den Sie oben gewählt haben.) im Browser aufrufen und bestätigen, dass die NCCO-JSON-Ausgabe erzeugt wird.

Aktualisieren Sie Ihre Vonage App

Vonage denkt immer noch, dass es Ihren Entwicklungsserver anrufen sollte, wenn jemand Ihre virtuelle Nummer anruft! Um dies zu beheben, aktualisieren Sie Ihre Vonage-Anwendung, um auf die neue URL zu verweisen. Führen Sie den folgenden Befehl aus, wobei Sie die Anwendungs-ID durch Ihre eigene ersetzen und "moodfeedbackapp" durch den Namen Ihrer eigenen Funktions-App.

Nächste Schritte

Das Ziel dieses Tutorials war es, Ihnen zu zeigen, wie Sie Webhook-Handler für Vonage Voice API-Aufrufe mit Azure Functions erstellen können. Obwohl dieses Beispiel nicht viel hergibt, können Sie mit Hilfe von Azure Storage und anderen APIs viel interessantere, praktische Beispiele erstellen.

Wenn Sie interessante Funktionen in Ihre Anwendung einbauen möchten, können Sie das tun:

• Senden Sie Feedback-Ergebnisse über die Vonage SMS API an einen Forscher.

• Integrieren Sie eine Voice-to-Text-API, um Spracheingaben anstelle von Zahlencodes zu verarbeiten.

• Speichern Sie die Rückmeldungen der einzelnen Anrufer in einer Datenbank, um Trends im Laufe der Zeit zu analysieren.

Andere Ressourcen

• Sehen Sie sich die NCCO-Referenzdokumente um zu sehen, was Sie mit Vonage Voice-Anrufen machen können.

• Lernen Sie, wie man Eine Azure-Funktion in Python schreiben

• Die Azure-Funktionen-Referenz ist sehr nützlich.

• Wie auch die Azure-Python-Dokumentation