Cómo utilizar Azure Functions con Python

En Vonage, intentamos que nuestras API sean lo más fáciles de usar posible. Sin embargo, algo incómodo que no podemos evitar es que muchas de nuestras API, como la Voice API de Vonagenecesitan preguntarle a tu aplicación qué hacer durante una llamada. Esto significa que tienes que ejecutar tu propio servidor. ¿O no?

Sin servidor con Azure Functions

Microsoft proporciona Azure Functions para Python, ¡y es genial! Se ha proporcionado mucho soporte para ayudarte a ponerte en marcha rápidamente, y funciona con modismos de proyecto estándar de Python, como requirements.txt. Te permite escribir pequeñas funciones independientes en Python y luego desplegarlas fácilmente en la nube de Azure.

Hay un nivel gratuito que proporciona un millón de ejecuciones de la función de ejecuciones de funciones al mes. Eso debería ser suficiente para una pequeña aplicación de demostración, o incluso una pequeña aplicación de producción.

Seamos funcionales

Te voy a mostrar cómo construir una aplicación sencilla de Vonage con dos webhooks alojados en Azure Functions. La idea es que el usuario llame a un número de Vonage (que activará el primer webhook) y sea recibido por una voz robótica. Se le pedirá que introduzca su estado de ánimo. Introducirá 1 para "feliz", 2 para "infeliz" y cualquier otra opción que desee. En este punto, se llamará al segundo punto final con la entrada, y ambos generarán una respuesta apropiada.

Describiré todos los pasos para crear todo el código y la configuración que necesitarás, pero si quieres ver el resultado final, el código está alojado en 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.

Requisitos

Como puede ver a continuación, hay pocos cosas que tendrás que configurar o instalar, pero créeme, vale la pena.

• A gratis Azure Account para que pueda publicar sus Azure Functions.

• Instalar la Herramienta CLI de Vonage y lee esta breve publicación del blog sobre cómo comenzar a usarla.

  Esto te da el vonage en tu consola, que te permite crear Voice Applications de Vonage, comprar números virtuales y vincular ambos.

• Instalar Ngrok

  Esto te da el comando ngrok en tu consola, que canalizará las solicitudes a tu máquina de desarrollo, permitiendo que Vonage envíe webhooks a tu servidor de desarrollo.

• Instale las Herramientas básicas de Azure Functions

  Esto le proporciona el comando func en tu consola, que te permite arrancar tu proyecto Azure Functions y ejecutarlo localmente para desarrollo y pruebas.

• Instale la Azure CLI.

  Esto le da el comando az en tu consola. Esto te permitirá crear varios objetos dentro de Azure, ¡y publicar tus funciones Azure!

Creación de la primera función

Una vez que tengas instalados todos los requisitos anteriores, abre tu consola. Vas a crear algo de código para empezar a construir tus funciones Azure.

Primero vamos a crear un nuevo proyecto Azure Functions usando el comando Azure Functions Core Tools, func. Ejecute func init para crear un proyecto Azure Functions vacío:

Ahora entra en el directorio del nuevo proyecto y usa func new para crear una nueva función Azure para responder a una llamada entrante. Cuando te pregunte qué tipo de función quieres crear, selecciona '5', HTTP trigger. Este es el tipo de función Azure que responde a peticiones HTTP. Cuando te pregunte cómo llamar a la función, escribe answer_inbound porque el endpoint se utilizará para responder a las llamadas telefónicas entrantes.

Puedes ver en la salida anterior que func ha creado un archivo Python __init__.py y un archivo de configuración, function.json.

Edite function.json y establece "authlevel" en "anonymous". Esto permitirá que Vonage lo llame sin ninguna autenticación adicional.

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

Ejecute la función de Python, utilizando el comando func host comando:

Si carga su navegador en la URL http://localhost:7071/api/answer_inbound?name=bob ¡deberías ver "Hello bob!" ¡Bien hecho! ¡Has "escrito" tu primera Función Azure!

De la función Azure a la llamada telefónica

Querrás que tu función genere algunas acciones NCCO para que Vonage sepa qué hacer cuando alguien marque tu número. Para que esto suceda, deberás reemplazar el código de la función por lo siguiente:

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

El código anterior devuelve una respuesta JSON que contiene dos NCCO Actions. Una acción NCCO es una instrucción para Vonage, que le indica cómo manejar la llamada telefónica. En este caso tenemos dos acciones:

• La acción talk acción indica a Vonage que lea un mensaje a la persona que llama.

• La acción input le indica a Vonage que espere que el usuario ingrese un dígito, que luego se enviará a la URL especificada en eventURL

Porque hemos puesto bargeIn en true en la acción talk si la persona que llama ingresa un dígito antes de que la acción input acción se haya iniciado, Vonage asumirá que simplemente han sido impacientes, y ejecutará la siguiente input instrucción.

Si ejecuta func host start de nuevo, cuando cargue su navegador en http://localhost:7071/api/answer_inbound?name=bob deberías ver un montón de JSON que contiene las acciones descritas anteriormente.

Túnel a su servidor de desarrollo

Mientras sigues desarrollando, querrás que Vonage pueda acceder a tus funciones para poder probarlas. Te recomiendo seguir las instrucciones de mi colega Aaron Bassett ha escrito para conectar tu servidor de desarrollo local a la API de Vonage mediante un túnel Ngrok.

Asumiendo que ahora sabes cómo funciona Ngrok, en un consola separada, ejecute

Comprueba que sigues ejecutando func host start en la otra ventana de la consola, y cargue la URL de Ngrok que se imprimió, seguida de /api/answer_inbound. Debería parecerse a https://r4nd0m.ngrok.io/api/answer_inbound (¡pero con tu propio prefijo aleatorio en lugar de r4nd0m!).

Si eso funciona, ¡es hora de decirle a Vonage cómo comunicarse con tu servidor de desarrollo!

Conecta Vonage a tu servidor de desarrollo

Si aún no lo has hecho, deberás configurar la CLI de Vonage, luego de la instalación, con tu clave api y tu secreto.

Crea una nueva aplicación de voz de Vonage ejecutando vonage apps:create y nómbrala "Ingresa tu estado de ánimo" cuando se te solicite. Sigue el resto de las indicaciones de la línea de comandos para crear tu aplicación.

Esto crea una aplicación llamada "Ingresa tu estado de ánimo" en el panel de la API de Vonage. Cuando se detecte una llamada entrante a cualquier número de teléfono vinculado a esta aplicación, se llamará al webhook en https://r4nd0m.ngrok.io/api/answer_inboundy publicará los detalles de la llamada entrante. Se espera que la función Azure en este punto final responda con acciones NCCO... ¿te suena familiar? También ha guardado una clave privada, que no usaremos por ahora, en un archivo llamado "private.key"

Ahora necesitas comprar un número virtual y vincularlo a la aplicación de Vonage. Así que toma nota del ID de la aplicación que acabas de crear (aquí es '4f33ff5e-dbbc-11e9-8656-6bdabe7b8258').

Compra un número virtual, si aún no lo tienes. Recomiendo comprarlo usando el Panel API de Vonagepero puedes puedes también buscar números y comprarlos usando la herramienta CLI de Vonage. Una vez que tengas un número, vincúlalo a la aplicación con el siguiente comando, reemplazando el número de teléfono por el que acabas de comprar y el ID de la aplicación por el que anotaste anteriormente:

Ahora, con tu teléfono, llama al número que acabas de vincular.

Lo que debería ocurrir: Debería responder una voz, con el mensaje anterior. Si introduces un número en el teclado numérico de tu teléfono, es probable que la llamada emita un pitido y luego se corte. Esto se debe a que el segundo URL, en /api/mood_feedback todavía no existe.

Manipulación de entradas

Para ello, siga pasos similares a los anteriores:

• Ejecute func newseleccione HTTP trigger e introduzca "mood_feedback" como nombre de la función.

• Modifique el archivo function.json y establezca authLevel a anonymous.

Ahora, abre __init__.py y sustituye el código de la función por el siguiente

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
        )

Hay un poco de código extra aquí, que se utilizará para extraer los datos enviados desde la llamada telefónica, pero por ahora, sólo debe ser capaz de llamar al número de nuevo, y esta vez cuando introduzcas un número durante la llamada, deberías oír el mensaje "gracias por decirnos cómo te sientes".

Dinamizar la respuesta

Si eso funciona, asegurémonos de que la respuesta a la llamada es un poco más simpática. Sobre la función, añade las siguientes variables globales:

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

Ahora, en la OCN que devuelves, sustituye la cadena por RESPONSES.get(req_body['dtmf'], UNEXPECTED_RESPONSE). Esta expresión extrae el código DTMF de la solicitud (req_body['dtmf']), intenta encontrar la respuesta asociada en RESPONSESy, si esa clave no existe, vuelve a UNEXPECTED_RESPONSE. Llame a su número y pruébelo.

Creación de una aplicación de funciones en Azure

Lo que has hecho hasta ahora es genial - siempre y cuando tu máquina de desarrollo esté encendida y tengas ventanas de consola abiertas ejecutando func host & ngrok. Pero eso es poco práctico, así que ahora te mostraré cómo desplegar el código que has escrito en Azure Functions, ¡para que Microsoft lo aloje por ti!

Para interactuar con los servidores de Azure, utilizaremos el comando Azure CLI, az.

En primer lugar, debe iniciar sesión en su cuenta Azure ejecutando az login. Se cargará el navegador y le pedirá que inicie sesión en su cuenta de Azure. Si aún no te has registrado en una Account de Azure, puedes hacerlo ahora.

Ahora, ejecuta los tres comandos az He añadido un comentario a cada uno de ellos, para que puedas ver lo que hacen. Lo único que tendrás que cambiar es reemplazar MYVONAGEFUNCTIONSTORE con algo globalmente único. El nombre real que elija no es importante - es sólo un lugar para almacenar los datos para sus funciones en ejecución, y no será visto por los usuarios. También tendrá que cambiar moodfeedbackapp por algo globalmente único.

Publique su función en Azure

Puede comprobar que sus funciones se despliegan correctamente accediendo a https://moodfeedback.azurewebsites.net/api/answer_inbound (tendrás que sustituir "moodfeedback" por el nombre de tu propia aplicación de funciones que elegiste anteriormente) en el navegador y confirmar que se está produciendo la salida NCCO JSON.

Actualiza tu aplicación de Vonage

Vonage aún cree que debe llamar a tu servidor de desarrollo cuando alguien llama a tu número virtual. Para solucionar esto, actualiza tu aplicación de Vonage para que apunte a la nueva URL. Ejecuta el siguiente comando, reemplazando el ID de la aplicación por el tuyo y "moodfeedbackapp" por el nombre de tu aplicación de función.

Próximos pasos

El objetivo de este tutorial era mostrarte cómo crear controladores de webhook para llamadas de Voice API de Vonage con Azure Functions. Aunque este ejemplo no hace mucho, podrás construir ejemplos mucho más interesantes y prácticos con la ayuda de Azure storage y otras APIs.

Si quieres incorporar funciones interesantes a tu aplicación, puedes hacerlo:

• Envía los resultados de los comentarios a un investigador, a través de la API de SMS de Vonage.

• Integre una API de voz a texto para gestionar la entrada de voz, en lugar de códigos numéricos.

• Almacenar los comentarios de cada persona que llama en una base de datos, para analizar las tendencias a lo largo del tiempo.

Otros recursos

• Consulte los documentos de referencia de NCCO para ver qué puedes hacer con las llamadas de Vonage Voice.

• Aprenda a Escribir una función Azure en Python

• En Referencia de Azure Functions es muy útil.

• Al igual que la documentación de Azure Python