Comment utiliser Azure Functions avec Python

Chez Vonage, nous essayons de rendre nos API aussi simples à utiliser que possible. Cependant, nous ne pouvons pas éviter une chose gênante, à savoir que beaucoup de nos API, comme le Voice API de Vonagede Vonage, doivent demander à votre application ce qu'elle doit faire pendant un appel. Cela signifie que vous devez exécuter votre propre serveur. Ou le faites-vous ?

Aller vers le sans serveur avec Azure Functions

Microsoft propose Azure Functions pour Python, et c'est génial ! De nombreux supports ont été fournis pour vous aider à être rapidement opérationnel, et cela fonctionne avec les idiomes standards des projets Python, tels que requirements.txt. Il vous permet d'écrire de petites fonctions autonomes en Python, puis de les déployer facilement dans le nuage Azure.

Il existe une version gratuite qui fournit un million d'exécutions de fonctions par mois. Cela devrait suffire pour une petite application de démonstration, ou même une petite application de production !

Soyons fonctionnels

Je vais vous montrer comment construire une application Vonage simple avec deux webhooks hébergés sur Azure Functions. L'idée est que l'utilisateur appelle un numéro Vonage, (ce qui déclenchera le premier webhook) et soit accueilli par une voix robotique. On lui demande d'indiquer son humeur. Il entre 1 pour "heureux", 2 pour "malheureux", et toutes les autres options souhaitées. À ce stade, le deuxième point d'accès sera appelé avec l'entrée, et tous deux généreront une réponse appropriée.

Je vais décrire toutes les étapes pour créer tout le code et la configuration dont vous aurez besoin, mais si vous voulez voir le résultat final, le code est hébergé sur GitHub

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.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Ready to start building?

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

Exigences

Comme vous pouvez le voir ci-dessous, il y a quelques quelques choses à configurer ou à installer, mais croyez-moi, cela en vaut la peine.

• Un libre Azure Account pour que vous puissiez publier vos Azure Functions.

• Installer l'outil Outil CLI de Vonage et lisez ce court article de blog sur la façon de commencer à l'utiliser.

  Cela vous donne la commande vonage dans votre console, ce qui vous permet de créer des Applications Voice Vonage, d'acheter des numéros virtuels et de relier les deux.

• Installer Ngrok

  Vous obtiendrez ainsi la commande ngrok dans votre console, qui acheminera les demandes vers votre machine de développement, ce qui permettra à Vonage d'envoyer des webhooks à votre serveur de développement.

• Installer les Azure Functions Core Tools

  Vous obtiendrez ainsi la commande func dans votre console, ce qui vous permet de démarrer votre projet Azure Functions et de l'exécuter localement à des fins de développement et de test.

• Installer la CLI Azure.

  Vous obtenez ainsi la commande az dans votre console. Cela vous permettra de créer divers objets dans Azure, et de publier vos fonctions Azure !

Création de la première fonction

Une fois toutes les conditions requises installées, ouvrez votre console. Vous allez créer un code de base pour démarrer la construction de vos fonctions Azure.

Commençons par créer un nouveau projet Azure Functions à l'aide de la commande Azure Functions Core Tools, func. Exécuter func init pour créer un projet Azure Functions vide :

Allez maintenant dans le répertoire du nouveau projet et utilisez func new pour créer une nouvelle fonction Azure afin de répondre à un appel entrant. Lorsque l'on vous demande quel type de fonction vous souhaitez créer, sélectionnez "5", HTTP trigger. Il s'agit du type de fonction Azure qui répond aux requêtes HTTP. Lorsque l'on vous demande comment appeler la fonction, tapez answer_inbound car le point de terminaison sera utilisé pour répondre aux appels téléphoniques entrants.

Vous pouvez voir dans la sortie ci-dessus que func a créé un fichier Python, __init__.py et un fichier de configuration, function.json.

Modifier function.json et mettre "authlevel" à "anonymous". Cela permettra à Vonage de l'appeler sans authentification supplémentaire.

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

Exécutez la fonction Python standard à l'aide de la commande func host à l'aide de la commande

Si vous chargez votre navigateur à l'URL http://localhost:7071/api/answer_inbound?name=bob vous devriez voir "Hello bob !" Bravo ! Vous avez "écrit" votre première Azure Function !

De la fonction Azure à l'appel téléphonique

Vous voudrez que votre fonction produise des actions NCCO, afin que Vonage sache quoi faire lorsque quelqu'un compose votre numéro. Pour ce faire, vous devrez remplacer le code de la fonction par ce qui suit :

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')

Le code ci-dessus renvoie une réponse JSON contenant deux actions NCCO. Une action NCCO est une instruction donnée à Vonage, lui indiquant comment traiter l'appel téléphonique. Dans ce cas, nous avons deux actions :

• L'action talk demande à Vonage de lire un message à l'appelant.

• L'action input indique à Vonage que l'utilisateur doit entrer un chiffre, qui sera ensuite envoyé à l'URL spécifiée dans l'action eventURL

Parce que nous avons mis bargeIn à true dans l'action talk si l'appelant entre un chiffre avant que l'action input l'action a commencé, Vonage supposera qu'il a simplement été impatient et exécutera l'instruction suivante. input instruction.

Si vous exécutez à nouveau func host start une nouvelle fois, lorsque vous chargez votre navigateur à l'adresse http://localhost:7071/api/answer_inbound?name=bob vous devriez voir un tas de JSON contenant les actions décrites ci-dessus.

Connexion à votre serveur de développement

Pendant que vous êtes encore en train de développer, vous voudrez que Vonage puisse accéder à vos fonctions, afin que vous puissiez les tester. Je vous recommande de suivre les instructions de mon collègue Aaron Bassett pour connecter votre serveur de développement local à l'API de Vonage à l'aide d'un tunnel Ngrok.

En supposant que vous sachiez maintenant comment fonctionne Ngrok, dans un distincte distincte, exécutez :

Vérifiez que vous exécutez toujours func host start dans l'autre fenêtre de la console, et chargez l'URL de Ngrok qui a été imprimée, suivie de /api/answer_inbound. Cela devrait ressembler à quelque chose comme https://r4nd0m.ngrok.io/api/answer_inbound (mais avec votre propre préfixe au lieu de r4nd0m !).

Si cela fonctionne, il est temps d'indiquer à Vonage comment contacter votre serveur de développement !

Connectez Vonage à votre serveur de développement

Si vous ne l'avez pas encore fait, vous devrez configurer le CLI de Vonage, après l'installation, avec votre clé d'api et votre secret.

Créez une nouvelle application Voice de Vonage en exécutant la commande vonage apps:create et nommez-la "Enter Your Mood" lorsque vous y êtes invité. Suivez le reste des invites de la ligne de commande pour créer votre application.

Cela crée une application appelée " Enter Your Mood " dans le tableau de bord de l'API de Vonage. Lorsqu'un appel entrant est détecté vers un numéro de téléphone lié à cette application, celle-ci appelle le webhook à l'adresse https://r4nd0m.ngrok.io/api/answer_inboundaffichant les détails de l'appel entrant. La fonction Azure à ce point d'extrémité est censée répondre par des actions NCCO ... cela vous rappelle quelque chose ? Elle a également enregistré une clé privée, que nous n'utiliserons pas pour l'instant, dans un fichier appelé "private.key"

Vous devez maintenant acheter un numéro virtuel et le lier à l'appli Vonage. Prenez donc note de l'identifiant de l'Applications qui vient d'être créé (ici, c'est " 4f33ff5e-dbbc-11e9-8656-6bdabe7b8258 ").

Achetez un numéro virtuel, si vous n'en avez pas déjà un. Je recommande de l'acheter en utilisant le tableau de bord API de Vonagemais vous pouvez rechercher des numéros et les acheter à l'aide de l'outil CLI de Vonage. Une fois que vous avez un numéro, reliez-le à l'application avec la commande suivante, en remplaçant le numéro de téléphone par celui que vous venez d'acheter et l'identifiant de l'application par celui que vous avez noté ci-dessus :

Maintenant, avec votre téléphone, appelez le numéro que vous venez de lier.

Ce qui doit se passer : Une Voice devrait répondre, avec le message ci-dessus. Si vous entrez un numéro sur le pavé numérique de votre téléphone, l'appel émettra probablement un signal sonore avant de s'éteindre. C'est parce que la deuxième URL, à /api/mood_feedback n'existe pas encore !

Traitement des données

Pour ce faire, suivez les mêmes étapes que celles décrites ci-dessus :

• Exécuter func newsélectionnez HTTP trigger et entrez "mood_feedback" comme nom de fonction.

• Modifier le fichier function.json et mettre authLevel à anonymous.

Ouvrez maintenant __init__.py et remplacez le code de la fonction par ce qui suit :

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
        )

Il y a un peu de code supplémentaire ici, qui sera utilisé pour extraire les données envoyées par l'appel téléphonique, mais pour l'instant, vous devriez être en mesure d'appeler à nouveau le numéro, et cette fois lorsque vous entrez un numéro pendant l'appel, vous devriez entendre le message "merci de nous avoir dit ce que vous ressentez".

Rendre la réponse dynamique

Si cela fonctionne, assurons-nous que la réponse à l'appel est un peu plus sympathique. Au-dessus de la fonction, ajoutez les variables globales suivantes :

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

Maintenant, dans le BCN que vous renvoyez, remplacez la chaîne par RESPONSES.get(req_body['dtmf'], UNEXPECTED_RESPONSE). Cette expression extrait le code DTMF de la requête (req_body['dtmf']), tente de trouver la réponse associée dans RESPONSESet si cette clé n'existe pas, elle revient à UNEXPECTED_RESPONSE. Appelez votre numéro et essayez-le !

Créer une application fonctionnelle sur Azure

Ce que vous avez fait jusqu'à présent est très bien - tant que votre machine de développement est allumée et que vous avez des fenêtres de console ouvertes qui exécutent func host & ngrok. Mais ce n'est pas pratique, alors maintenant je vais vous montrer comment déployer le code que vous avez écrit dans Azure Functions, de sorte que Microsoft puisse l'héberger pour vous !

Pour interagir avec les serveurs Azure, nous utiliserons la commande CLI Azure, az.

Vous devez d'abord vous connecter à votre Account Azure en exécutant az login. Le navigateur s'ouvrira et vous demandera de vous connecter à votre Account Azure. Si vous n'avez pas encore ouvert de compte Azure, vous pouvez le faire maintenant.

Maintenant, vous allez exécuter les trois commandes az ci-dessous - j'ai ajouté un commentaire à chacune d'entre elles, afin que vous puissiez voir ce qu'elles font. La seule chose que vous devrez changer est de remplacer MYVONAGEFUNCTIONSTORE par quelque chose d'unique au niveau mondial. Le nom que vous choisissez n'est pas important - c'est juste un endroit où stocker les données pour vos fonctions en cours d'exécution, et qui ne sera pas vu par les utilisateurs. Vous devrez également remplacer moodfeedbackapp par quelque chose d'unique au niveau mondial.

Publier votre fonction sur Azure

Vous pouvez vérifier que vos fonctions sont bien déployées en vous rendant sur le site https://moodfeedback.azurewebsites.net/api/answer_inbound (vous devrez remplacer "moodfeedback" par le nom de votre propre application de fonction que vous avez choisi ci-dessus) dans le navigateur et confirmer que la sortie JSON du NCCO est produite.

Mise à jour de l'application Vonage

Vonage pense toujours qu'il doit appeler votre serveur de développement lorsque quelqu'un appelle votre numéro virtuel ! Pour résoudre ce problème, mettez à jour votre application Vonage pour qu'elle pointe vers la nouvelle URL. Exécutez la commande suivante, en remplaçant l'ID de l'application par le vôtre, et en remplaçant "moodfeedbackapp" par le nom de votre propre application fonctionnelle.

Prochaines étapes

L'objectif de ce tutoriel était de vous montrer comment construire des gestionnaires de webhook pour les appels de l'API Voice de Vonage avec Azure Functions. Bien que cet exemple ne fasse pas grand-chose, vous serez en mesure de construire des exemples beaucoup plus intéressants et pratiques à l'aide du stockage Azure et d'autres API.

Si vous souhaitez intégrer des fonctionnalités intéressantes dans votre application, vous pouvez le faire :

• Envoyer les résultats du feedback à un chercheur, via l'API SMS de Vonage.

• Intégrer une API de conversion de la parole en texte pour gérer la saisie vocale, au lieu des codes numériques.

• Stocker les commentaires de chaque appelant dans une base de données, afin d'analyser les tendances au fil du temps.

Autres ressources

• Consultez les documents de référence du documents de référence du NCCO pour voir ce que vous pouvez faire avec les appels Vonage Voice.

• Apprenez à Écrire une fonction Azure en Python

• Les fonctions Azure Référence Azure Functions est très utile.

• Tout comme la documentation Azure Python