Conexión de Azure Functions a Azure Cosmos DB mediante Visual Studio Code

Azure Functions le permite conectar servicios de Azure y otros recursos a funciones sin tener que escribir su propio código de integración. Estos enlaces, que representan la entrada y la salida, se declaran dentro de la definición de función. Los datos de los enlaces se proporcionan a la función como parámetros. Un desencadenador es un tipo especial de enlace de entrada. Si bien una función tiene un único desencadenador, puede tener varios enlaces de entrada y salida. Para más información, consulte Conceptos básicos sobre los enlaces y desencadenadores de Azure Functions.

En este artículo se muestra cómo usar Visual Studio Code para conectar Microsoft Azure Cosmos DB a la función que creó en el artículo de inicio rápido anterior. El enlace de salida que se agrega a esta función escribe datos de la solicitud HTTP en un documento JSON almacenado en un contenedor de Azure Cosmos DB.

Configurar su entorno

Antes de empezar, asegúrese de instalar la extensión Azure Databases para Visual Studio Code.

Creación de una cuenta de Azure Cosmos DB

1. En Visual Studio Code, haga clic con el botón derecho en la suscripción de Azure en la que creó la aplicación de funciones en el artículo anterior y seleccione Crear servidor... .

   

2. Escriba la siguiente información cuando se le indique:

   • Seleccionar un servidor de bases de datos de Azure: elija Core (SQL) para crear una base de datos de documentos en la que se puedan realizar consultas mediante una sintaxis de SQL. Más información sobre la SQL API de Azure Cosmos DB.

   • Nombre de cuenta: escriba un nombre único para identificar la cuenta de Azure Cosmos DB. El nombre de la cuenta solo puede utilizar letras minúsculas, números y guiones (-), y debe tener entre 3 y 31 caracteres de longitud.

   • Seleccionar un modelo de capacidad: seleccione servidor para crear una cuenta en modo sin servidor. Seleccione Provisioned throughput (Rendimiento aprovisionado) para crear una cuenta en modo de rendimiento aprovisionado. Se recomienda elegir Sin servidor si va a empezar a trabajar con Azure Cosmos DB.

   • Seleccionar un grupo de recursos para los nuevos recursos: elija el grupo de recursos en el que creó la aplicación de funciones en el artículo anterior.

   • Seleccionar una ubicación para los nuevos recursos: seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB. Use la ubicación que esté más cercana a usted o a los usuarios para obtener el acceso más rápido a los datos.

Creación de un contenedor y una base de datos de Azure Cosmos DB

1. Una vez creada la nueva cuenta de Azure Cosmos DB, haga clic con el botón derecho en su nombre y seleccione Crear base de datos... .

   

2. Cuando se le solicite, escriba my-database como Nombre de la base de datos.

3. Una vez creada la base de datos, haga clic con el botón derecho en su nombre y seleccione Crear colección... .

   

4. Escriba la siguiente información cuando se le indique:

   • Escriba un identificador para la colección: my-container

   • Escriba la clave de partición de la colección: id

Actualización de la configuración de la aplicación de funciones

En el artículo del inicio rápido anterior, creó una aplicación de funciones en Azure. En este artículo, se actualiza una instancia de Function App para escribir documentos JSON en el contenedor de Azure Cosmos DB que ha creado anteriormente. Para conectarse a una cuenta de Azure Cosmos DB, debe agregar su cadena de conexión a la configuración de la aplicación. Después, descargue la nueva configuración en el archivo local.settings.json para que pueda conectarse a su cuenta de Azure Cosmos DB cuando realice la ejecución en un entorno local.

1. En Visual Studio Code, haga clic con el botón derecho en la cuenta de Azure Cosmos DB y seleccione Copiar cadena de conexión.

   

2. Presione F1 para abrir la paleta de comandos y busque y ejecute el comando Azure Functions: Add New Setting....

3. Elija la aplicación de funciones que creó en el artículo anterior. Escriba la siguiente información cuando se le indique:

   • Escriba el nombre de la nueva configuración de la aplicación: escriba CosmosDbConnectionString.

   • Escriba el valor de "CosmosDbConnectionString" : pegue la cadena de conexión de la cuenta de Azure Cosmos DB que copió anteriormente.

4. Vuelva a presionar F1 para abrir la paleta de comandos y busque y ejecute el comando Azure Functions: Download Remote Settings....

5. Elija la aplicación de funciones que creó en el artículo anterior. Seleccione Sí a todo para sobrescribir la configuración local existente.

Registro de extensiones de enlace

Dado que va a utilizar un enlace de salida de Azure Cosmos DB, para poder ejecutar el proyecto debe tener instalada la extensión de enlaces correspondiente.

dotnet add package Microsoft.Azure.WebJobs.Extensions.CosmosDB

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[1.*, 2.0.0)"
  } 
}

Ya puede agregar el enlace de salida de Azure Cosmos DB a su proyecto.

Adición de un enlace de salida

En Functions, para cada tipo de enlace es necesario definir los elementos direction, type y un valor único de name en el archivo function.json. La manera de definir estos atributos depende del lenguaje de la aplicación de funciones.

[CosmosDB(
    databaseName: "my-database",
    collectionName: "my-container",
    ConnectionStringSetting = "CosmosDbConnectionString")]IAsyncCollector<dynamic> documentsOut,

[FunctionName("HttpExample")]
public static async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,
    [CosmosDB(
        databaseName: "my-database",
        collectionName: "my-container",
        ConnectionStringSetting = "CosmosDbConnectionString")]IAsyncCollector<dynamic> documentsOut,
    ILogger log)

{
    "type": "cosmosDB",
    "direction": "out",
    "name": "outputDocument",
    "databaseName": "my-database",
    "collectionName": "my-container",
    "createIfNotExists": "false",
    "connectionStringSetting": "CosmosDbConnectionString"
}

Adición de código que utilice el enlace de salida

if (!string.IsNullOrEmpty(name))
{
    // Add a JSON document to the output container.
    await documentsOut.AddAsync(new
    {
        // create a random ID
        id = System.Guid.NewGuid().ToString(),
        name = name
    });
}

[FunctionName("HttpExample")]
public static async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,
    [CosmosDB(
        databaseName: "my-database",
        collectionName: "my-container",
        ConnectionStringSetting = "CosmosDbConnectionString")]IAsyncCollector<dynamic> documentsOut,
    ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    string name = req.Query["name"];

    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);
    name = name ?? data?.name;

    if (!string.IsNullOrEmpty(name))
    {
        // Add a JSON document to the output container.
        await documentsOut.AddAsync(new
        {
            // create a random ID
            id = System.Guid.NewGuid().ToString(),
            name = name
        });
    }

    string responseMessage = string.IsNullOrEmpty(name)
        ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
        : $"Hello, {name}. This HTTP triggered function executed successfully.";

    return new OkObjectResult(responseMessage);
}

if (name) {
    context.bindings.outputDocument = JSON.stringify({
        // create a random ID
        id: new Date().toISOString() + Math.random().toString().substr(2,8),
        name: name
    });
}

module.exports = async function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    const name = (req.query.name || (req.body && req.body.name));
    const responseMessage = name
        ? "Hello, " + name + ". This HTTP triggered function executed successfully."
        : "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response.";

    if (name) {
        context.bindings.outputDocument = JSON.stringify({
            // create a random ID
            id: new Date().toISOString() + Math.random().toString().substr(2,8),
            name: name
        });
    }

    context.res = {
        // status: 200, /* Defaults to 200 */
        body: responseMessage
    };
}

Ejecución local de la función

1. Como en el artículo anterior, presione F5 para iniciar el proyecto de aplicación de función y Core Tools.

2. Mientras se ejecuta Core Tools, vaya al área de Azure: Área Functions. En Functions, expanda Proyecto local > Functions. Haga clic con el botón derecho (Ctrl + clic en Mac) en la función HttpExample y elija Execute Function Now... (Ejecutar la función ahora...).

   

3. En Enter request body (Especificar el cuerpo de la solicitud) verá el valor del cuerpo del mensaje de solicitud de { "name": "Azure" }. Presione Entrar para enviar este mensaje de solicitud a la función.

4. Una vez que se haya devuelto una respuesta, presione Ctrl + C para detener Core Tools.

Comprobación de que se ha creado un documento JSON

1. En Azure Portal, vuelva a su cuenta de Azure Cosmos DB y seleccione Explorador de datos.

2. Expanda la base de datos y el contenedor, y seleccione Elementos para enumerar los documentos creados en el contenedor.

3. Compruebe que el enlace de salida ha creado un documento JSON.

   

Reimplementación y comprobación de la aplicación actualizada

1. En Visual Studio Code, presione F1 para abrir la paleta de comandos. En la paleta de comandos, busque y seleccione Azure Functions: Deploy to function app....

2. Elija la aplicación de funciones que creó en el primer artículo. Dado que va a volver a implementar el proyecto en la misma aplicación, seleccione Implementar para descartar la advertencia sobre la sobrescritura de archivos.

3. Una vez finalizada la implementación, puede volver a usar la característica Execute Function Now... (Ejecutar la función ahora...) para desencadenar la función en Azure.

4. Vuelva a comprobar los documentos creados en el contenedor de Azure Cosmos DB para tener la certeza de que el enlace de salida vuelve a generar un nuevo documento JSON.

Limpieza de recursos

En Azure, los recursos son aplicaciones de funciones, funciones o cuentas de almacenamiento, entre otros. Se agrupan en grupos de recursos y se puede eliminar todo el contenido de un grupo si este se elimina.

Ha creado recursos para completar estas guías de inicio rápido. Se le pueden facturar por estos recursos, dependiendo del estado de la cuentade los y precios de los servicios. Si ya no necesita los recursos, aquí se indica cómo eliminarlos:

1. En Visual Studio Code, presione F1 para abrir la paleta de comandos. En la paleta de comandos, busque y seleccione Azure Functions: Open in portal.

2. Elija una aplicación de funciones y presione Entrar. La página de la aplicación de funciones se abre en Azure Portal.

3. En la pestaña Información general, seleccione el vínculo con nombre junto a Grupo de recursos.

   

4. En la página Grupo de recursos, revise la lista de recursos incluidos y compruebe que son los que desea eliminar.

5. Seleccione Eliminar grupo de recursos y siga las instrucciones.

   El proceso de eliminación tardará un par de minutos. Cuando termine, aparece una notificación durante unos segundos. También puede seleccionar el icono de campana en la parte superior de la página para ver la notificación.

Pasos siguientes

Ha actualizado la función desencadenada por HTTP para escribir documentos JSON en un contenedor de Azure Cosmos DB. Ahora, puede obtener más información sobre el desarrollo de Functions mediante Visual Studio Code:

• Desarrollo de Azure Functions mediante Visual Studio Code

• Enlaces y desencadenadores de Azure Functions.