Ejercicio: Escritura de datos con enlaces de salida

15 minutos

En el ejercicio anterior, se ha implementado un escenario para buscar marcadores en una base de datos de Azure Cosmos DB. Hemos configurado un enlace de entrada para leer datos de nuestra colección de marcadores. Pero, podemos hacer más. Expandamos el escenario e incluyamos la escritura. Considere este diagrama de flujo:

Decision flow diagram illustrating the process of adding a bookmark in Azure Cosmos DB back-end and returning a response.

En este escenario, recibimos solicitudes para agregar marcadores a nuestra colección. Las solicitudes se pasan en la clave deseada, o identificador, junto con la dirección URL del marcador. Como puede ver en el diagrama de flujo, respondemos con un error si la clave ya existe en el back-end.

Si no se encuentra la clave que se ha pasado, agregamos el marcador nuevo a la base de datos. Nos podríamos detener ahí, pero hagamos un poco más.

¿Ve otro paso en el diagrama de flujo? Hasta ahora no hemos hecho mucho con los datos que recibimos en términos de procesamiento. Lo que recibimos lo movemos a una base de datos. Pero en una solución real, es posible que los datos se procesen de algún modo. Se puede realizar todo el procesamiento en la misma función, pero en este ejercicio se muestra un patrón que delega el procesamiento posterior en otro componente o elemento de la lógica de negocios.

¿Cuál podría ser un buen ejemplo de la descarga de trabajo en nuestro escenario de marcadores? ¿Y qué pasaría si enviáramos el nuevo marcador a un servicio de generación de código QR? A su vez, ese servicio podría generar un código QR para la dirección URL, almacenar la imagen en Blob Storage y agregar la dirección de la imagen QR en la entrada de la colección de marcadores. Llamar a un servicio para generar una imagen QR consume mucho tiempo. Por lo tanto, en lugar de esperar al resultado, la tarea se entrega a una función y se deja que se complete de forma asincrónica.

Del mismo modo en que Azure Functions admite los enlaces de entrada para varios orígenes de integración, también tiene un conjunto de plantillas para enlaces de salida a fin de facilitar la escritura de datos en los orígenes de datos. Los enlaces de salida también se configuran en el archivo function.json. Como verá en este ejercicio, podemos configurar la función para que sea compatible con varios servicios y orígenes de datos.

Importante

Este ejercicio se basa en los recursos y recursos del espacio aislado que ha creado en unidades anteriores, en concreto, la base de datos de Azure Cosmos DB, los marcadores y los enlaces de entrada. Si no ha completado los ejercicios en unidades anteriores, no podrá finalizar este ejercicio.

Creación de una función desencadenada con HTTP

En Azure Portal, vaya a la aplicación de funciones que creó seleccionando el nombre de la aplicación de funciones en la ruta de acceso de la ruta de navegación en la parte superior de la página de funciones HttpTrigger2.
En la pestaña Funciones de la página Información general, debe tener las funciones de desencadenador HTTP que creó.
Seleccione Crear en la pestaña Funciones. Aparece el panel Crear función.
En la sección Seleccionar una plantilla, seleccione Desencadenador de HTTP y, a continuación, seleccione Crear. Se abre el panel Información general de la función HttpTrigger3.

Adición de un enlace de entrada de Azure Cosmos DB

Vamos a agregar otro enlace de entrada de Azure Cosmos DB.

En el menú Función de HttpTrigger3, seleccione Integración. Aparecerá el panel de Integración.
En el cuadro Entradas, seleccione Agregar entrada. Aparece el panel Crear entrada.
En la lista desplegable Tipo de enlace, seleccione Azure Cosmos DB.
El valor Conexión de la cuenta de Cosmos DB debería estar rellenado previamente con la conexión que ha creado en el ejercicio anterior.

Si no ve la conexión en la lista, siga estos pasos para crear una.
1. En la sección Detalles de Azure Cosmos DB, en la opción Conexión de cuenta de Cosmos DB, seleccione el vínculo Nuevo.
2. Cuando aparezca el cuadro de diálogo Nueva conexión de Cosmos DB, seleccione Aceptar para crear la conexión. Se crea una nueva conexión a la cuenta de Cosmos DB.

Escriba los valores siguientes para las demás opciones de configuración de este panel. En cualquier momento, para obtener más información sobre el propósito de un valor, puede seleccionar el icono de información situado a la derecha.

Configuración	valor	Descripción
Nombre del parámetro de documento	`bookmark`	Nombre que se usa para identificar este enlace en el código.
Nombre de la base de datos	`func-io-learn-db`	Base de datos con la que se va a trabajar. Este valor es el nombre de la base de datos que se ha establecido antes en esta lección.
Nombre de la colección	`Bookmarks`	Nombre de la colección a partir de la cual se leen los datos. Este valor se ha definido antes en la lección.
Id. de documento	`{id}`	Agregue `{id}` para usar la expresión de enlace correcta y acepte el parámetro que se pasa en la cadena de consulta.
Clave de partición	`{id}`	De nuevo, agregue `{id}` para usar la expresión de enlace correcta y acepte el parámetro que se pasa en la cadena de consulta.
Consulta SQL (opcional)	Déjelo en blanco	Solo se recupera un elemento cada vez a partir de su identificador. Por tanto, en este caso filtrar por valor Documento es mejor que usar una consulta SQL. Se podría elaborar una consulta SQL para devolver una entrada (`SELECT * from b where b.ID = /id`). Esa consulta devolvería, en efecto, un elemento, pero lo devolvería en una colección de elementos. Nuestro código tendría que manipular una colección sin necesidad. Use el enfoque de consulta SQL cuando quiera obtener varios documentos.

Al igual que el enlace de entrada que se ha creado en el ejercicio anterior, el objetivo es buscar un marcador con un identificador específico, por lo que se enlaza el identificador de documento que la función recibe en la cadena de consulta al enlace, conocido como expresión de enlace. La función la desencadena una solicitud HTTP que usa una cadena de consulta para especificar el identificador que se va a buscar. El enlace devuelve 0 (no encontrado) o 1 (encontrado) documentos.

Seleccione Aceptar para guardar esta configuración de enlace de entrada.

Ya tenemos un enlace de entrada de Azure Cosmos DB. Agregaremos un enlace de salida para poder escribir nuevas entradas en la colección.

Adición de un enlace de salida de Azure Cosmos DB

En el panel Integración de HttpTrigger3, en el cuadro Salidas, seleccione Agregar salida. Aparece el panel Crear salida.
En Tipo de enlace, en la lista desplegable, seleccioneAzure Cosmos DB.
El valor Conexión de cuenta de Cosmos DB debería estar ya rellenado con la conexión que ha creado de manera previa. Si no es así, expanda la lista desplegable y seleccione la conexión que definió para el enlace de entrada HttpTrigger3.

Escriba los valores siguientes para el resto de la configuración del enlace de salida.

Setting	valor	Descripción
Nombre del parámetro de documento	`newbookmark`	Nombre empleado para identificar este enlace en su código. Este parámetro se usa para escribir una nueva entrada de marcador.
Nombre de la base de datos	`func-io-learn-db`	Base de datos con la que se va a trabajar. Este valor es el nombre de la base de datos que se ha establecido antes en esta lección.
Nombre de la colección	`Bookmarks`	Nombre de la colección a partir de la cual se leen los datos. Este valor es el nombre del contenedor que definimos anteriormente en la lección.
Clave de partición	`/id`	Agregue la clave de partición que se ha definido anteriormente al crear el contenedor Bookmarks de Azure Cosmos DB. La clave introducida aquí (especificada en la configuración del enlace de entrada `<key>`) debe coincidir con la del contenedor.

Seleccione Aceptar para guardar esta configuración de enlace de salida.

Ya tenemos un enlace para leer de la colección y otro para escribir en ella.

Adición de un enlace de salida de Azure Queue Storage

Azure Queue Storage es un servicio para almacenar mensajes a los que se puede acceder desde cualquier lugar del mundo. El tamaño de un único mensaje puede ser de hasta 64 KB, y una cola puede contener millones de mensajes, hasta la capacidad total de la cuenta de almacenamiento en la que se defina. En este diagrama se muestra en líneas generales cómo se usa una cola en el escenario.

Illustration showing a storage queue with a function pushing and another function popping messages.

En este ejemplo, puede ver que una función denominada add-bookmark agrega mensajes a una cola, y otra función denominada gen-qr-code saca mensajes de la misma cola y procesa la solicitud. Como los mensajes se escriben (o insertan) en la cola desde add-bookmark, agregamos un nuevo enlace de salida a la solución.

Vamos a crear el enlace a través del portal.

En el panel Integración de la función, en el cuadro Salidas, seleccione Agregar salida. Aparece el panel Crear salida.
En la lista desplegable Tipo de enlace, seleccione Azure Queue Storage.

Si aparece un mensaje que le pide instalar la extensión Microsoft.Azure.WebJobs.Extensions.Storage, seleccione Instalar y espere a que finalice.

A continuación, vamos a configurar una conexión de la cuenta de almacenamiento en la que se va a hospedar la cola.

En Conexión de cuenta de Storage, seleccione Nuevo. Aparece el cuadro de diálogo Conexión de la nueva cuenta de almacenamiento.
Al principio de este módulo, cuando creó la aplicación de funciones, también se creó una cuenta de almacenamiento. Seleccione esta opción en la lista desplegable y, después, seleccione Aceptar.

El valor Conexión de la cuenta de almacenamiento se rellena con el nombre de una conexión.

Si bien podríamos conservar los valores predeterminados, vamos a cambiar algunas configuraciones para dar más significado a las propiedades restantes.

Complete la configuración en el panel Crear salida, reemplazando los siguientes valores antiguos por los nuevos:

Configuración	Valor anterior	Valor nuevo	Descripción
Nombre del parámetro de mensaje	outputQueueItem	newmessage	Propiedad de enlace que se usa en el código.
Nombre de la cola	outqueue	bookmarks-post-process	El nombre de la cola en la que colocamos marcadores para que otra función pueda procesarlos aún más.

Seleccione Aceptar para guardar la configuración de salida de Azure Queue Storage.

Actualización de la implementación de función

Ya están configurados todos los enlaces. Es el momento de usarlos en la función.

Para abrir el archivo index.js en el editor de código, seleccione la función, HttpTrigger3.
En el menú, en Desarrollador, seleccione Code + Test (Código y prueba). Aparece el panel Código y prueba de la función.

Reemplace todo el código del archivo index.js por el del fragmento de código siguiente y, en la barra de comandos, seleccione Guardar.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark;
    if(bookmark){
            context.res = {
            status: 422,
            body : "Bookmark already exists.",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    else {
        
        // Create a JSON string of our bookmark.
        var bookmarkString = JSON.stringify({ 
            id: req.body.id,
            url: req.body.url
        });

        // Write this bookmark to our database.
        context.bindings.newbookmark = bookmarkString;

        // Push this bookmark onto our queue for further processing.
        context.bindings.newmessage = bookmarkString;

        // Tell the user all is well.
        context.res = {
            status: 200,
            body : "bookmark added!",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    context.done();
};

Desglosemos lo que hace este código:

Como esta función cambia los datos, esperamos que la solicitud HTTP sea una solicitud POST y que los datos del marcador formen parte del cuerpo de la solicitud.
El enlace de entrada de Azure Cosmos DB intenta recuperar un documento, o marcador, con el id que recibimos. Si encuentra una entrada, se establece el objeto bookmark. La condición if(bookmark) comprueba si se encontró una entrada.
Agregar contenido a la base de datos es tan sencillo como establecer el parámetro de enlace context.bindings.newbookmark en la nueva entrada de marcador, que se ha creado como una cadena JSON.
Publicar un mensaje en la cola es tan sencillo como establecer el parámetro context.bindings.newmessage.

Nota:

La única tarea que ha realizado ha sido crear un enlace de la cola. Nunca creó la cola de forma explícita. ¡Es testigo del poder de los enlaces! Como se indica en la siguiente notificación, la cola se crea automáticamente si no existe.

Screenshot showing message that the queue will be auto-created. .

Eso es todo. En la próxima sección veremos en acción lo que hemos realizado.

Para abrir el archivo run.ps1 en el editor de código, seleccione la función, HttpTrigger3 de la ruta de navegación en la parte superior del panel.
En el menú Función, en Desarrollador, seleccione Code + Test (Código y prueba). Se abrirá el panel Código y prueba de la función HttpTrigger3, que muestra el contenido predeterminado de run.ps1.

Reemplace el contenido del archivo por el código siguiente.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = 422
    $body = "Bookmark already exists."
}
else {
    $newBookmark = @{ id = $Request.Body.id; url = $Request.Body.url }

    Push-OutputBinding -Name newbookmark -Value $newBookmark

    Push-OutputBinding -Name newmessage -Value $newBookmark

    $status = [HttpStatusCode]::OK
    $body = "bookmark added!"
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = $status
    Body = $body
    ContentType = "application/json"
})

En la barra de comandos, seleccione Guardar. Se establece una conexión y se abre una sesión de archivo de registro.

Desglosemos lo que hace este código:

Como esta función cambia los datos, esperamos que la solicitud HTTP sea una solicitud POST y que los datos del marcador formen parte del cuerpo de la solicitud.
El enlace de entrada de Azure Cosmos DB intenta recuperar un documento, o marcador, con el id de la solicitud. Si encuentra una entrada, se establece el objeto bookmark. La condición if ($bookmark) comprueba si se encontró una entrada.
El proceso para agregar contenido a la base de datos es tan sencillo como llamar a Push-OutputBinding con el nombre del enlace de salida de Cosmos DB (newbookmark) y el valor del objeto $newBookmark.
Por su parte, publicar un mensaje en la cola es tan sencillo como llamar a Push-OutputBinding con el nombre del enlace de salida de la cola (newmessage) y el valor del objeto $newBookmark.

Nota:

Screenshot showing UI tool tip that the queue will be auto-created.

Eso es todo. En la próxima sección veremos en acción lo que hemos realizado.

Prueba

Ahora que tenemos varios enlaces de salida, las pruebas se vuelven un poco más complicadas. En las unidades anteriores, nos conformábamos con probar mediante el envío de una solicitud HTTP con una cadena de consulta; ahora, queremos realizar una solicitud HTTP Post. También es necesario comprobar si los mensajes entran a una cola.

En la barra de comandos del panel Código y prueba de la función HttpTrigger3, seleccione Probar/ejecutar. Aparece un nuevo panel, con la pestaña Entrada abierta, como se muestra en esta imagen:
En la lista desplegable Método HTTP, verifique que esté seleccionada la opción POST.
Reemplace el contenido del cuerpo de la solicitud por el objeto JSON siguiente:
```
{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}
```
Seleccione Run (Ejecutar).
El progreso de la programación se muestra en el panel Registros. Cuando haya finalizado, compruebe que en la pestaña Salida se muestra "Bookmark already exists" (El marcador ya existe) en el valor Contenido de respuesta HTTP.

Ha agregado el elemento de marcador en Ejercicio: Lectura de datos con enlaces de entrada. La respuesta confirma que JavaScript var bookmark = context.bindings.bookmark funciona correctamente y que el código de PowerShell realiza la misma conexión.
Vamos a publicar un segundo marcador en la base de datos. Seleccione la pestaña Entrada.
Reemplace el contenido del cuerpo de la solicitud por el objeto JSON siguiente:
```
{
    "id": "github",
    "url": "https://www.github.com"
}
```
Seleccione Run (Ejecutar).
Compruebe que en la pestaña Salida se muestra "marcador agregado" en Contenido de la respuesta HTTP, como en la captura de pantalla siguiente.

¡Enhorabuena! La función actúa tal y como se ha diseñado. Pero, ¿qué sucede con la operación de cola que agregamos al código? Ahora se comprobará si se ha escrito algo en una cola.

Comprobación de que se escribe un mensaje en la cola

Las colas de Azure Queue Storage se hospedan en una cuenta de almacenamiento. Configuró la cuenta de almacenamiento al crear el enlace de salida.

En la barra de búsqueda global de Azure Portal, escriba cuentas de almacenamiento y, en la lista de resultados, seleccione Cuentas de almacenamiento. Aparecerá el panel Cuenta de almacenamiento.
Seleccione la cuenta de almacenamiento que ha usado para configurar el enlace de salida newmessage.
En el menú Cuenta de almacenamiento, en Almacenamiento de datos, seleccione Colas para enumerar las colas que se alojan en esta cuenta de almacenamiento. Compruebe que se muestra la cola bookmarks-post-process, tal como se muestra en la captura de pantalla siguiente:
Seleccione bookmarks-post-process para enumerar los mensajes que se encuentran en la cola. Si todo ha ido según lo planeado, la cola incluye el mensaje que publicó al agregar un marcador a la base de datos. Debería tener este aspecto.

En este ejemplo, el mensaje ha recibido un identificador único y la columna Texto del mensaje muestra el marcador en formato JSON. No hay ningún mensaje para el marcador docs de Azure que ha intentado agregar porque ya existía en la base de datos.
Puede probar aún más la función si cambia el cuerpo de la solicitud en el panel de prueba con nuevos conjuntos de identificadores y direcciones URL, y ejecuta la función. Observe esta cola para ver cuando llegan más mensajes. También puede consultar la base de datos para comprobar que se han agregado entradas nuevas.

En este ejercicio se han ampliado los conocimientos sobre los enlaces a los enlaces de salida y la escritura de datos en la instancia de Azure Cosmos DB. Se ha agregado un enlace de salida para publicar mensajes en una cola de Azure. Este ejemplo demuestra la verdadera eficacia de los enlaces para ayudar a dar forma a los datos y moverlos desde los orígenes entrantes a diversos destinos. No hemos escrito nada de código de base de datos ni hemos tenido que administrar cadenas de conexión. En cambio, se han configurado los enlaces de manera declarativa y se ha permitido que la plataforma se encargara de proteger las conexiones y de escalar la función y las conexiones.

Continuar