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. Se ha configurado un enlace de entrada para leer datos de la colección de marcadores. Pero, podemos hacer más. Expandamos el escenario e incluyamos la escritura. Tenga en cuenta el siguiente diagrama de flujo:

Diagrama de flujo de decisión que ilustra el proceso de agregar un marcador en el back-end de Azure Cosmos DB y devolver una respuesta.

En este escenario, recibimos solicitudes para agregar marcadores a nuestra colección. Las solicitudes pasan la clave deseada o el 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 nuestro back-end.

Si no se encuentra la clave que se ha pasado a nosotros, agregamos el nuevo marcador a nuestra base de datos. Podríamos detenernos allí, pero vamos a hacer un poco más.

¿Observe otro paso en el diagrama de flujo? Hasta ahora, no hicimos mucho con los datos que recibimos en términos de procesamiento. Movemos lo que recibimos en una base de datos. Sin embargo, en una solución real, probablemente procesaríamos los datos de alguna manera. Podemos realizar todo el procesamiento en la misma función. Sin embargo, en este ejercicio se muestra un patrón que descarga más procesamiento en otro componente o parte de la lógica de negocios.

¿Cuál podría ser un buen ejemplo de descarga de trabajo en nuestro escenario de marcadores? Bueno, ¿qué ocurre si se envía el nuevo marcador a un servicio de generación de código QR? Ese servicio generaría un código QR para la dirección URL, almacenaría la imagen en Blob Storage y agregaría la dirección de la imagen QR a la entrada de nuestra colección de marcadores. Llamar a un servicio para generar una imagen QR consume mucho tiempo. Por lo tanto, en lugar de esperar el resultado, entregamos la tarea a una función y se deja que complete esta tarea de forma asincrónica.

Al igual que Azure Functions admite enlaces de entrada para varios orígenes de integración, también tiene un conjunto de plantillas para enlaces de salida para facilitar la escritura de datos en orígenes de datos. Los enlaces de salida también se configuran en el archivo function.json. Como puede ver en este ejercicio, podemos configurar nuestra función para que funcione con varios orígenes de datos y servicios.

Importante

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

Creación de una función desencadenada por 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 HTTP y, a continuación, seleccione Siguiente. Acepte los valores predeterminados en la ficha Detalles de la plantilla y 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 Desencadenador y 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.

Ajuste	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 estamos recuperando un elemento a la vez en función del identificador. Por lo tanto, el filtrado con la configuración documento es mejor que usar una consulta SQL en esta instancia. Podríamos crear una consulta SQL para devolver una entrada (`SELECT * from b where b.ID = /id`). Esa consulta realmente devolvería un elemento, pero lo devolvería en una colección de elementos. Nuestro código tendría que manipular una colección innecesariamente. Use el enfoque de consulta SQL cuando desee obtener varios documentos.

Al igual que el enlace de entrada que creamos en el ejercicio anterior, queremos buscar un marcador con un identificador específico. Por lo tanto, asociamos el identificador de documento que la función recibe en la cadena de consulta al enlace, que se conoce como expresión de enlace. El desencadenador de función es 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 Agregar para guardar la configuración del enlace de entrada.

Ya tenemos un enlace de entrada de Azure Cosmos DB. Vamos a agregar un enlace de salida para que podamos escribir nuevas entradas en nuestra 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.

Ajuste	Valor	Descripción
Nombre del parámetro de documento	`newbookmark`	Nombre que se usa para identificar este enlace en el 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 Marcadores 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 Agregar para guardar esta configuración de enlace de salida.

Ahora tenemos un enlace para leer de nuestra colección y un enlace 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 esté definida la cola. En este diagrama se muestra en líneas generales cómo se usa una cola en el escenario.

Ilustración en la que se muestra una cola de almacenamiento con una inserción de funciones y otra función que muestra mensajes emergentes.

En este ejemplo, verá que una función denominada add-bookmark agrega mensajes a una cola y otro denominado gen-qr-code extrae 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:

Ajuste	Valor anterior	Valor nuevo	Descripción
Nombre del parámetro de mensaje	outputQueueItem	nuevo mensaje	La propiedad de enlace que usamos 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 Agregar 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 nuestra función.

Para abrir el archivo index.js en el editor de código, seleccione la función HttpTrigger3.
En el menú, seleccione 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 código del fragmento de código siguiente. A continuación, 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();
};

Vamos a desglosar lo que hace este código:

Dado que esta función cambia los datos, esperamos que la solicitud HTTP sea post y los datos de 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 ha creado la cola explícitamente. ¡Está presenciando el poder de los enlaces! Como se indica en la siguiente notificación, la cola se crea automáticamente si no existe.

Recorte de pantalla que muestra el mensaje de que la cola se creará automáticamente. .

Seleccione function.json de la lista desplegable de su ruta de acceso de <functionapp> \ HttpTrigger3 \ y realice los siguientes cambios:
1. Cambie todas las instancias de "collectionName" a "containerName".
2. Cambie todas las instancias de "connectionStringSetting" a "connection".
3. Elimine las referencias a "methods": [].

El archivo function.json final debe ser similar a este código.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "name": "bookmark",
      "direction": "in",
      "type": "cosmosDB",
      "partitionKey": "{id}",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "id": "{id}"
    },
    {
      "name": "newbookmark",
      "direction": "out",
      "type": "cosmosDB",
      "partitionKey": "/id",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB"
    },
    {
      "name": "newmessage",
      "direction": "out",
      "type": "queue",
      "queueName": "bookmarks-post-process",
      "connection": "your-storage-account_STORAGE"
    }
  ]
}

En la barra de comandos, seleccione Guardar.

Eso es todo. En la próxima sección verá en acción lo que ha hecho.

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, seleccione 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"
})

Seleccione Guardar en la barra de comandos. Se establece una conexión y se abre una sesión de archivo de registro.

Vamos a desglosar lo que hace este código:

Dado que esta función cambia los datos, esperamos que la solicitud HTTP sea post y los datos de marcador formen parte del cuerpo de la solicitud.
Nuestro enlace de entrada de Azure Cosmos DB intenta recuperar un documento o marcador mediante 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.
Publicar un mensaje en nuestra cola es tan sencillo como llamar a Push-OutputBinding con el nombre del enlace de salida de cola (newmessage) y el valor del objeto $newBookmark.

Nota

Recorte de pantalla que muestra la información sobre herramientas de la interfaz de usuario que la cola se creará automáticamente.

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 unidades anteriores, éramos el contenido para probar mediante el envío de una solicitud HTTP con una cadena de consulta, pero queremos realizar una publicación HTTP esta vez. También es necesario comprobar si los mensajes se están convirtiendo en 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"
}
```
Haga clic en Ejecutar.
El progreso de la programación se muestra en el panel Registros. Cuando haya finalizado, compruebe que la pestaña Salida muestra El marcador ya existe. en la configuración de contenido de la 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"
}
```
Haga clic en Ejecutar.
Compruebe que la pestaña Salida muestra ¡marcador agregado! en el contenido de la respuesta HTTP, como se muestra en la captura de pantalla siguiente.

Enhorabuena, la función funciona como está diseñada. ¿Pero qué ocurre con la operación de cola que hemos agregado 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. A continuación, 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 el recorte 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 cambiando el cuerpo de la solicitud en el panel de prueba con nuevos conjuntos id/url y ejecutando la función. Vea esta cola para ver que llegan más mensajes. También puede consultar la base de datos para comprobar que se han agregado entradas nuevas.

En este ejercicio, ampliamos el conocimiento de los enlaces para generar enlaces y escribir datos en Azure Cosmos DB. Se ha agregado un enlace de salida para publicar mensajes en una cola de Azure. En este ejemplo se muestra la verdadera eficacia de los enlaces para ayudarle a dar forma y mover datos de orígenes entrantes a varios destinos. No teníamos que escribir ningún código de base de datos ni administrar cadenas de conexión nosotros mismos. En su lugar, configuramos enlaces mediante declaración y permitimos que la plataforma se ocupe de proteger las conexiones, escalar nuestra función y escalar nuestras conexiones.