Ejercicio: Lectura de datos con enlaces de entrada

20 minutos

Imagine que quiere crear un servicio de búsqueda de marcadores. Inicialmente, el servicio es de solo lectura. Si los usuarios quieren buscar una entrada, envían una solicitud con el identificador de la entrada y la función devuelve la dirección URL. En el diagrama de flujo siguiente se describe el flujo lógico.

Cuando un usuario envía una solicitud con texto, la función para buscar un marcador intenta detectar una entrada en la base de datos que contenga un marcador con el texto como clave o identificador. El sistema devuelve un resultado que indica si se ha encontrado la entrada.

Cuando la función de Azure recibe una solicitud con un identificador de marcador, primero comprueba si la solicitud es válida. De lo contrario, se genera una respuesta de error. Si la solicitud es válida, la función comprueba si el identificador de marcador existe en la base de datos de Azure Cosmos DB. Si no existe, se genera una respuesta de error. Si se encuentra el identificador del marcador, se genera una respuesta correcta.

Debe almacenar los datos en algún lugar. En el diagrama de flujo anterior, el almacén de datos es una instancia de Azure Cosmos DB. Pero ¿cómo se puede conectar a esa base de datos desde una función y leer los datos? En el mundo de las funciones, configura un enlace de entrada para ese trabajo. Es fácil configurar un enlace de entrada a través de Azure Portal. Como verá en breve, no es necesario escribir código ni abrir una conexión de almacenamiento. El sistema en tiempo de ejecución de Azure Functions y los enlaces se encargan automáticamente de esas tareas.

Creación de una cuenta de Azure Cosmos DB

Nota:

Este ejercicio no está pensado para ser un tutorial sobre Azure Cosmos DB. Si le interesa obtener más información, hay una ruta de aprendizaje completa sobre Azure Cosmos DB al final de este módulo.

Creación de una cuenta de base de datos

Una cuenta de base de datos es un contenedor para administrar una o varias bases de datos. Para crear una base de datos, debemos crear una cuenta de base de datos.

En el menú de recursos de Azure Portal, o bien en la página Inicio, seleccione Crear un recurso. Aparecerá el panel Crear un recurso.
En el menú Crear un recurso, seleccione Bases de datos y, después, busque y seleccione Azure Cosmos DB. Aparece el panel ¿Qué API resulta más adecuada para la carga de trabajo?
En la opción Azure Cosmos DB for NoSQL, seleccione Crear para poder crear un desencadenador de Cosmos DB y enlaces de entrada y salida. Aparece el panel Creación de una cuenta de Azure Cosmos DB: Azure Cosmos DB for NoSQL.

En la pestaña Aspectos básicos, escriba los valores siguientes para cada opción.

Configuración	valor	Descripción
Detalles del proyecto
Suscripción	Suscripción de Concierge	Suscripción de Azure que funciona con los recursos del espacio aislado.
Grupo de recursos	En la lista desplegable, seleccione [nombre del grupo de recursos de espacio aislado].	Grupo de recursos para el espacio aislado.
Detalles de instancia
Nombre de cuenta	`globally unique name`	Escriba un nombre único, pero identificable, para la cuenta de Azure Cosmos DB. Se anexará `documents.azure.com` al nombre que proporcione. `3 - 50 lowercase characters, numbers, or hyphens (-)`.
Location	`region`	Seleccione la región más cercana.

Acepte los valores predeterminados para el resto de la configuración y seleccione Revisar y crear para validar la entrada. Aparece una notificación Validación correcta.
Seleccione Crear para aprovisionar e implementar una cuenta de base de datos.
La implementación puede tardar un tiempo. Debe esperar el mensaje Implementación correcta del Centro de notificaciones antes de continuar.
Haga clic en Ir al recurso para ir a la cuenta de base de datos del portal. Aparece el panel Inicio rápido de la cuenta de Azure Cosmos DB.

A continuación, se agregará un contenedor y después una base de datos a la cuenta de Azure Cosmos DB.

Agregar un contenedor

En una instancia de Azure Cosmos DB, se usa un contenedor para almacenar varias entidades generadas por el usuario, también denominadas elementos. Se creará un contenedor denominado Bookmarks.

Se usará la herramienta Explorador de datos para crear una base de datos y un contenedor.

En el menú de la cuenta de Azure Cosmos DB, seleccione Explorador de datos. Aparece el panel Explorador de datos para su cuenta de Azure Cosmos DB.
Seleccione el cuadro Nuevo contenedor. Aparece el panel Nuevo contenedor. Es posible que tenga que desplazarse para verlo.

Escriba los valores siguientes para cada opción.

Configuración	valor	Descripción
Id. de base de datos	Seleccione Crear nuevo y escriba func-io-learn-db para el identificador de la Base de datos	Los nombres de bases de datos pueden tener una longitud de entre 1 y 255 caracteres, y no pueden contener /, \, #, ? ni un espacio final. Aquí puede escribir lo que quiera, pero en este módulo se usa func-io-learn-db.
Máximo de RU de base de datos	4000	Acepte el rendimiento predeterminado de 4000 unidades de solicitud por segundo (RU/s). Para reducir la latencia, puede escalar verticalmente el rendimiento más adelante.
Id. de contenedor	Marcadores	Los identificadores de contenedor presentan los mismos requisitos de caracteres que los nombres de bases de datos. En este módulo se usan marcadores.
Clave de partición	/id	La clave de partición especifica cómo se distribuyen los documentos de colecciones de Azure Cosmos DB entre las particiones de datos lógicos. Aquí usamos el campo Clave de partición, ya que en este módulo no nos interesa conocer el rendimiento de la base de datos. Para obtener más información sobre estrategias de clave de partición de Azure Cosmos DB, explore los módulos correspondientes en Microsoft Learn.

Acepte los valores predeterminados para el resto de configuraciones.

Desplácese a la parte inferior del panel y seleccione Aceptar. Espere unos minutos para que se puedan crear la base de datos y el contenedor.

Cuando se haya completado, el Explorador de datos muestra func-io-learn-db, en DATOS bajo NOSQL API.
Seleccione func-io-learn-db para expandirla. Tenga en cuenta que la base de datos func-io-learn-db contiene varios miembros secundarios, incluidos Scale y Bookmarks.
Expanda el contenedor Bookmarks y verá que se ha rellenado previamente con varios miembros secundarios.

En la siguiente tarea, agregará algunos datos, también conocidos como elementos, al contenedor Bookmarks.

Adición de datos de prueba

Le gustaría agregar algunos datos al contenedor Bookmarks. Use el Explorador de datos para almacenar una dirección URL y un identificador para cada elemento.

Expanda la base de datos func-io-learn-db, y el contenedor Bookmarks y, después, seleccione Elementos. Se muestra la pestaña Elementos.
En la barra de comandos, seleccione Nuevo elemento.
Reemplace el código predeterminado del nuevo elemento por el código JSON siguiente.
```
{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}
```

En la barra de comandos, seleccione Guardar.

Observe que aparecen más propiedades que las dos líneas que agregamos. Todas comienzan con un subrayado (_rid, _self, _etag, _attachments, _ts). El sistema genera estas propiedades, descritas en la tabla siguiente, para ayudar a administrar los elementos que se agregan al contenedor.

Propiedad	Descripción
`_rid`	El identificador de recurso es un identificador único que también es jerárquico por la pila de recursos del modelo de recursos. Se usa de forma interna para la selección de ubicación y la navegación del recurso de elemento.
`_self`	Identificador URI direccionable único del recurso.
`_etag`	Se requiere para el control de simultaneidad optimista.
`_attachments`	Ruta de acceso direccionable para el recurso de datos adjuntos.
`_ts`	La marca de tiempo de la última actualización de este recurso.

Vamos a agregar algunos elementos más al contenedor Bookmarks. En la barra de comandos, seleccione Nuevo elemento. Crearemos cuatro elementos más con el siguiente contenido. Para agregar los elementos, seleccione Nuevo elemento y luego Guardar después de copiar y pegar cada nuevo elemento. Observe cómo se agrega cada elemento a la lista de elementos.
```
{
    "id": "portal",
    "url": "https://portal.azure.com"
}
```
```
{
    "id": "learn",
    "url": "https://learn.microsoft.com/training"
}
```
```
{
    "id": "marketplace",
    "url": "https://azuremarketplace.microsoft.com/marketplace/apps"
}
```
```
{
    "id": "blog",
    "url": "https://azure.microsoft.com/blog"
}
```
Cuando haya terminado de escribir los datos del marcador, el contenedor debe tener un aspecto parecido al de la imagen siguiente.

El contenedor Bookmarks tiene cinco elementos. En este escenario, si una solicitud llega con "id=docs", esta busca ese identificador en el contenedor de marcadores y devuelve la dirección URL https://learn.microsoft.com/azure. Se crearás una función de Azure que busque valores en el contenedor Bookmarks.

Creación de la función

Vaya a la aplicación de funciones que creó en la unidad anterior. En el menú de recursos, seleccione Inicio y, en la sección Recursos recientes, debería ver la aplicación de funciones (Tipo es igual a Aplicación de funciones). Seleccione la aplicación de funciones. Aparece el panel Aplicación de funciones.
En la pestaña Funciones en la página Información general, debe tener una función, HttpTrigger1.
Vamos a crear otra función. Seleccione Crear en la pestaña Funciones. Aparece el panel Crear función, en el que se enumeran las plantillas de los desencadenadores admitidos.
En la sección Seleccionar una plantilla, haga clic en Desencadenador de HTTP.
Acepte todas las configuraciones predeterminadas y seleccione Crear para crear la función.

Se abre el panel Información general de la función HttpTrigger2.

Comprobación de la función

Puede comprobar lo que ha hecho hasta ahora si prueba la nueva función.

En la barra de comandos, seleccione Obtener la dirección URL de la función. Aparece el cuadro de diálogo Obtener la dirección URL de la función.
Seleccione default (function key) (valor predeterminado [clave de función]) en la lista desplegable, después el icono Copiar al Portapapeles y, por último, Aceptar.
Pegue la dirección URL de la función que copió en la barra de direcciones de una nueva pestaña del explorador. Anexe el valor de la cadena de consulta &name=<your name> al final de la dirección URL, reemplace <your name> por su nombre y presione ENTRAR. La función de Azure debe devolver una respuesta personalizada en el explorador.

Ahora que el esqueleto de la función ya funciona, la atención se centrará en la lectura de datos desde la instancia de Azure Cosmos DB o, en este escenario, desde el contenedor Bookmarks.

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

Para leer datos de la base de datos, deberá definir un enlace de entrada. Como ve aquí, puede configurar un enlace que puede comunicarse con la base de datos en tan solo unos pasos.

En Azure Portal, en el menú de la función HttpTrigger2 de la izquierda, seleccione Integración. Aparece el panel Integración de la función.

Ha usado una plantilla que creó una solicitud de desencadenador de HTTP y un enlace de salida HTTP. Vamos a agregar un enlace de entrada de Azure Cosmos DB.
En el cuadro Entradas, seleccione Agregar entrada. Aparece el panel Crear entrada.
En la lista desplegable Tipo de enlace, seleccione Azure Cosmos DB.
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. Aparece el cuadro de diálogo Nueva conexión de Cosmos DB.

Si aparece un mensaje que le pide instalar la extensión Microsoft.Azure.WebJobs.Extensions.CosmosDB, seleccione Instalar y espere a que finalice.
De forma predeterminada, Azure reconoce la cuenta de Azure Cosmos DB que creó anteriormente. Seleccione Aceptar para configurar una conexión a la base de datos. Se configura una nueva conexión a la cuenta de la base de datos y se muestra en el campo Conexión de cuenta de Cosmos DB.

Queremos buscar un marcador con un identificador específico, de modo que vincularemos el identificador que se recibe en la cadena de consulta al enlace.

Ahora se completará el panel Crear entrada. Escriba los valores siguientes para cada opción. Para obtener más información sobre el propósito de cada valor, seleccione el icono de información del campo en cuestión.

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 estableció.
Nombre de la colección	`Bookmarks`	La colección desde la que se leen los datos. Este valor se definió.
Id. de documento	`id`	Agregue el identificador de documento que definió al crear el contenedor Bookmarks de Azure Cosmos DB.
Clave de partición	`/id`	Agregue la clave de partición que definió al crear la colección Bookmarks de Azure Cosmos DB. La clave introducida aquí (especificada en formato de enlace de entrada `<key>`) debe coincidir con la de la colección.
Consulta SQL (opcional)	Déjelo en blanco	Solo se recupera un documento cada vez en función del identificador. Así pues, en este caso el filtrado con el valor Id. de 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 documento, pero lo devolvería en una colección de documentos. Su código tendría que manipular una colección sin necesidad. Use el enfoque de consulta SQL cuando quiera obtener varios documentos.

Para aclarar por qué se usan estos valores: el objetivo es buscar un marcador con un identificador específico, por lo que se ha vinculado el identificador de documento que la función recibe en la cadena de consulta al enlace de entrada. Esta sintaxis se conoce 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. Como los identificadores son únicos en nuestra colección, el enlace devuelve 0 documentos (no encontrados) o 1 (encontrado).

Para guardar esta configuración de enlace de entrada, seleccione Aceptar.

Actualización de la implementación de funciones

Ahora que el enlace está definido, puede usarlo en la función. Debe realizar dos cambios para implementar el enlace que acaba de crear:

Modifique el código de implementación específico del lenguaje de la función. Debe determinar si se ha encontrado un documento en la base de datos que coincide con el identificador que se pasa a la función.
Modifique el código de implementación JSON de la función para aceptar un parámetro que se pasa en la cadena de consulta.

Modificación del código de implementación JavaScript de la función

En el menú Función de la función HttpTrigger2, seleccione Código y prueba. Se abrirá el panel Código y prueba de la función HttpTrigger2.

Reemplace todo el código del archivo index.js por el siguiente código.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark

    if(bookmark){
        context.res = {
        body: { "url": bookmark.url },
        headers: {
            'Content-Type': 'application/json'
        }
        };
    }
    else {
        context.res = {
            status: 404,
            body : "No bookmarks found",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }

    context.done();
};

En la barra de comandos, seleccione Guardar. Seleccione Registros del sistema de archivos en la lista desplegable del centro superior del panel de registros (que muestra Registros de App Insights de forma predeterminada). Aparece el panel Registros, en el que se muestra Connected!.

Examinemos lo que hace este código.

Una solicitud HTTP entrante desencadena la función y se pasa un parámetro de consulta id al enlace de entrada de Azure Cosmos DB.
Si la base de datos encuentra un documento que coincida con este identificador, el parámetro bookmark se establece en el documento ubicado.

En este ejemplo, el código crea una respuesta que contiene el valor de dirección URL que se encuentra en el documento correspondiente de la base de datos.
Si no se encuentra ningún documento que coincida con esta clave, la solicitud responderá con una carga útil y un código de estado que comunique las malas noticias al usuario.

Modificación del código de implementación JSON de la función

En la lista desplegable, seleccione function.json en la ruta <functionapp> \ HttpTrigger2 \.

Modifique los valores de id y partitionKey para que acepten un parámetro de {id}. El código de function.json debe ser similar al ejemplo siguiente, donde your-database se reemplaza por el nombre de la base de datos de Cosmos DB.

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

En la barra de comandos, seleccione Guardar.

Modificación del código de implementación de PowerShell de la función

En el menú Función de la función HttpTrigger2, seleccione Código y prueba. Se abrirá el panel Código y prueba de la función HttpTrigger2, que muestra el archivo run.ps1.

Reemplace todo el código del archivo run.ps1 por el siguiente código.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = [HttpStatusCode]::OK
    $body = @{ url = $bookmark.url }
}
else {
    $status = [HttpStatusCode]::NotFound
    $body = "No bookmarks found"
}

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

En la barra de comandos, seleccione Guardar. Seleccione Registros del sistema de archivos en la lista desplegable del centro superior del panel de registros (que muestra Registros de App Insights de forma predeterminada). Aparece el panel Registros, en el que se muestra Connected!.

Examinemos lo que hace este código.

Una solicitud HTTP entrante desencadena la función y se pasa un parámetro de consulta id al enlace de entrada de Azure Cosmos DB.
Si la base de datos encuentra un documento que coincida con este identificador, el parámetro bookmark se establece en el documento ubicado.

En este ejemplo, el código crea una respuesta que contiene el valor de dirección URL que se encuentra en el documento correspondiente de la base de datos.
Si no se encuentra ningún documento que coincida con esta clave, la solicitud responderá con una carga útil y un código de estado que comunique las malas noticias al usuario.

Modificación del código de implementación JSON de la función

En la lista desplegable, seleccione function.json en la ruta <functionapp> \ HttpTrigger2 \.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "cosmosDB",
      "name": "bookmark",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "direction": "in",
      "id": "{id}",
      "partitionKey": "{id}"
    }
  ]
}

En la barra de comandos, seleccione Guardar.

Prueba

Ya debería estar en el panel Código y prueba de la función HttpTrigger2.
En la barra de comandos, seleccione Obtener la dirección URL de la función. Aparece el cuadro de diálogo Obtener la dirección URL de la función.
En la lista desplegable Clave, seleccione valor predeterminado en Clave de función, y después el icono Copiar al Portapapeles situado al final de la dirección URL.
Pegue la clave de función que copió en la barra de direcciones de una nueva pestaña del explorador y agregue el valor &id=docs de la cadena de consulta al final de la dirección URL. La dirección URL resultante debería ser similar al ejemplo siguiente:

https://example.azurewebsites.net/api/HttpTrigger2?code=AbCdEfGhIjKlMnOpQrStUvWxYz==&id=docs
Presione ENTRAR para ejecutar la solicitud. La respuesta devuelta por la función debería ser parecida al siguiente ejemplo.
```
{
  "url": "https://learn.microsoft.com/azure"
}
```
Reemplace &id=docs por &id=missing, presione ENTRAR y observe la respuesta. Se han definido cinco marcadores y se ha creado una respuesta de error significativa si el marcador solicitado no existe.

En esta unidad, creó su primer enlace manualmente para leerlo desde una base de datos Azure Cosmos DB. La cantidad de código que escribió para buscar la base de datos y leer los datos era mínima gracias a los enlaces. Ha dedicado la mayor parte de su trabajo a configurar el enlace mediante declaraciones, y la plataforma se ocupó del resto.

En la siguiente unidad, agregará más datos a la colección de marcadores a través de un enlace de salida de Azure Cosmos DB.

Continuar

Ejercicio: Lectura de datos con enlaces de entrada

Creación de una cuenta de Azure Cosmos DB

Creación de una cuenta de base de datos

Agregar un contenedor

Adición de datos de prueba

Creación de la función

Comprobación de la función

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

Actualización de la implementación de funciones

Modificación del código de implementación JavaScript de la función

Modificación del código de implementación JSON de la función

Modificación del código de implementación de PowerShell de la función

Modificación del código de implementación JSON de la función

Prueba

Comentarios