Ejercicio: Lectura de datos con enlaces de entrada

20 minutos

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

Cuando un usuario envía una solicitud con texto, la función de marcador de búsqueda intenta buscar una entrada en la base de datos que contiene 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 conecta a una base de datos desde una función y lee datos? En el mundo de las funciones, configuras un enlace de entrada para una función. La configuración de un enlace de entrada a través de Azure Portal es sencilla. Como ve en breve, no tiene que escribir código ni abrir una conexión de almacenamiento. El entorno de ejecución y los enlaces de Azure Functions se encargan 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 está interesado en obtener más información, consulte la 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 en la página Inicio , seleccione Crear un recurso. Aparece el panel Crear un recurso .
En el menú Crear un recurso , seleccione Bases de datos y, a continuación, busque y seleccione Azure Cosmos DB. Aparece el panel ¿Qué API se adapta mejor a la carga de trabajo?
En la opción Azure Cosmos DB para NoSQL , seleccione Crear para poder crear un desencadenador de Cosmos DB y enlaces de entrada y salida. Aparece el panel Crear cuenta de Azure Cosmos DB: Azure Cosmos DB para NoSQL .

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

Ajuste	Valor	Descripción
Detalles del proyecto
Tipo de carga de trabajo	Desarrollo y pruebas	Garantiza un rendimiento y una eficiencia de costos óptimos.
Suscripción	Suscripción de Concierge	La 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 la instancia
Nombre de cuenta	`globally unique name`	Escriba un nombre único pero identificable para la cuenta de Azure Cosmos DB; `documents.azure.com` se anexa al nombre que proporcione. `3 - 50 lowercase characters, numbers, or hyphens (-)`.
Ubicación	`region`	Seleccione la región más cercana.

Acepte los valores predeterminados de la configuración restante 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 algún tiempo. Espere a que la implementación se haya realizado correctamente en el centro de notificaciones antes de continuar.
Seleccione Ir al recurso para ir a la cuenta de base de datos en el portal. Aparece el panel Inicio rápido de la cuenta de Azure Cosmos DB.

A continuación, agregamos un contenedor y, a continuación, agregamos 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. Creamos un contenedor denominado Bookmarks.

Vamos a 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 de la cuenta de 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 configuración.

Ajuste	Valor	Descripción
Id. de base de datos	Seleccione Crear nuevo y escriba func-io-learn-db para el identificador de 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. Puede escribir lo que quiera, pero en este módulo se usa func-io-learn-db .
Número máximo de RU/s de base de datos	Manual de instrucciones	Ajuste a Manual y acepte el valor predeterminado de 400 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 tienen los mismos requisitos de caracteres que los nombres de base 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 las colecciones de Azure Cosmos DB entre particiones de datos lógicas. Aquí usamos la configuración clave de partición , ya que no nos preocupa el rendimiento de la base de datos en este módulo. 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 todas las demás configuraciones.

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

Cuando haya finalizado, el Explorador de datos muestra func-io-learn-db en DATA en NOSQL API.
Seleccione func-io-learn-db para expandirlo. Tenga en cuenta que la base de datos func-io-learn-db contiene miembros secundarios, incluidos Marcadores.
Expanda el contenedor Marcadores. Observe que varios miembros secundarios ya lo rellenan previamente.

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

Adición de datos de prueba

Quieres agregar datos al contenedor Marcadores. 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 Marcadores y, a continuación, seleccione Elementos. Aparece 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. Todos comienzan con un subrayado (_rid, _self, _etag, _attachments, _ts). Estas propiedades, descritas en la tabla siguiente, se generan por el sistema para ayudar a administrar los elementos que agregue 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. La Id. se usa de forma interna para localizar el recurso de elemento y navegar por él.
`_self`	Identificador URI direccionable único del recurso.
`_etag`	Necesario 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 Marcadores . En la barra de comandos, seleccione Nuevo elemento. Cree cuatro elementos más con el siguiente contenido. Agregue los elementos seleccionando Nuevo elemento y, después, seleccione 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 termine 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. Vamos a crear 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. En la sección Recursos recientes, debería ver su aplicación de función (Tipo es igual a Function App). Seleccione la aplicación de funciones y aparecerá el panel Aplicación de funciones.
En la pestaña Funciones de 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 , enumerando plantillas para desencadenadores admitidos.
En la sección Seleccionar una plantilla , seleccione Desencadenador HTTP y, a continuación, seleccione Siguiente.
Acepte todas las opciones predeterminadas y seleccione Crear para crear la función.

Aparece el panel Información general de la función HttpTrigger2 .

Comprobación de la función

Puede comprobar el progreso hasta ahora probando la nueva función.

En la barra de comandos, seleccione Obtener dirección URL de función. Aparece el cuadro de diálogo Obtener dirección URL de la función .
En el valor predeterminado (clave de función), seleccione el icono Copiar en el Portapapeles y seleccione Cerrar.
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 &name=<your name> de la cadena de consulta al final de la dirección URL, reemplace por <your name> el nombre y presione Entrar. La función de Azure debe devolver una respuesta personalizada en el explorador.

Ahora que tenemos nuestra función básica funcionando, vamos a enfocarnos en leer datos de tu Azure Cosmos DB o, en nuestro caso, desde tu contenedor de Marcadores.

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

Para leer datos de la base de datos, debe definir un enlace de entrada. Como puede ver aquí, puede configurar un enlace que pueda comunicarse con la base de datos en unos pocos pasos.

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

Ha usado una plantilla que creó una solicitud de desencadenador HTTP con un enlace de salida HTTP. Vamos a agregar un enlace de entrada de Azure Cosmos DB.
En el cuadro Desencadenador y entradas , seleccione Agregar entrada. Aparece el panel Crear entrada .
En la lista desplegable Tipo de vínculo, seleccione Azure Cosmos DB.
En la sección Detalles de Azure Cosmos DB , en la configuración de conexión de la 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 que instale 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, por lo que vamos a vincular el identificador que recibimos en la cadena de consulta al enlace.

Vamos a completar la configuración en el panel Crear entrada . Escriba los valores siguientes para cada configuración. Para obtener más información sobre el propósito de cada configuración, seleccione el icono de información de ese campo.

Ajuste	Valor	Descripción
Nombre del parámetro del 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 establecemos.
Nombre de la colección	`Bookmarks`	La colección de la que se leen los datos. Esta configuración se definió.
Id. de documento	`id`	Agregue el identificador de documento que definimos al crear el contenedor Marcadores 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)	Dejar en blanco	Solo se recupera un documento cada vez en función del identificador. Por lo tanto, el filtrado con la configuración id. de documento es mejor que usar una consulta SQL en esta instancia. Se podría elaborar una consulta SQL para devolver una entrada (`SELECT * from b where b.ID = id`). Esa consulta realmente devolvería 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 desee obtener varios documentos.

Para aclarar por qué usamos esta configuración, queremos buscar un marcador con un identificador específico, por lo que vinculamos el ID de documento que nuestra función recibe en la cadena de consulta con el enlace de entrada. Esta sintaxis se conoce como expresión de enlace. Una solicitud HTTP desencadena la función que usa una cadena de consulta para especificar el identificador que se va a buscar. Dado que los identificadores son únicos en nuestra colección, el enlace devuelve 0 (no encontrado) o 1 (encontrado) documentos.

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

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

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 encontró 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 que acepte un parámetro que se pasa en la cadena de consulta.

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

En el menú Función de la función HttpTrigger2 , seleccione Código y prueba. Aparece el panel Código y prueba para la función HttpTrigger2 .

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

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 los registros de App Insights de forma predeterminada). Aparece el panel Registros, en el que se muestra que tiene Connected!

Vamos a examinar 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 \.

Reemplace todo el código del archivo function.json por el código siguiente. Asegúrese y reemplace your-database por el nombre de nuestra cuenta de Azure 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",
      "partitionKey": "{id}",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "id": "{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. Aparece el panel Código y prueba para la función HttpTrigger2 , que muestra el run.ps1 archivo.

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 los registros de App Insights de forma predeterminada). Aparece el panel Registros, en el que se muestra que tiene Connected!

Vamos a examinar 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 defunction.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": "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.

Pruébelo

Ya debería estar en el panel Código y prueba de la función HttpTrigger2 .
En la barra de comandos, seleccione Obtener dirección URL de la función. Aparece el cuadro de diálogo Obtener dirección URL de la función .
En la tecla de función predeterminada, seleccione el icono Copiar al portapapeles.
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 debe 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 debe ser similar al ejemplo siguiente.
```
{
  "url": "https://learn.microsoft.com/azure"
}
```
Reemplace por &id=docs&id=missing, presione Entrar y observe la respuesta. Definimos cinco marcadores y creamos 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 en nuestra base de datos y leer datos era mínima debido a las vinculaciones. Ha realizado la mayor parte de su trabajo configurando el enlace mediante declaración y la plataforma se encarga del resto.

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

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 la función

Modificación del código de implementación de 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

Pruébelo

Comentarios