Almacenamiento de datos no estructurados mediante Azure Functions y Cosmos DBStore unstructured data using Azure Functions and Azure Cosmos DB

Azure Cosmos DB es una excelente manera de almacenar datos no estructurados y JSON.Azure Cosmos DB is a great way to store unstructured and JSON data. En combinación con Azure Functions, Cosmos DB facilita y agiliza el almacenamiento de datos con mucho menos código que el necesario para almacenar datos en una base de datos relacional.Combined with Azure Functions, Cosmos DB makes storing data quick and easy with much less code than required for storing data in a relational database.

Nota

En este momento, el desencadenador de Azure Cosmos DB y los enlaces de entrada y de salida solo funcionan con cuentas de SQL API y Graph API.At this time, the Azure Cosmos DB trigger, input bindings, and output bindings work with SQL API and Graph API accounts only.

En Azure Functions, los enlaces de entrada y salida proporcionan una manera declarativa de conectarse a los datos de servicio externos desde su función.In Azure Functions, input and output bindings provide a declarative way to connect to external service data from your function. En este artículo, aprenda a actualizar una función existente para agregar un enlace de salida que almacene datos no estructurados en un documento de Azure Cosmos DB.In this article, learn how to update an existing function to add an output binding that stores unstructured data in an Azure Cosmos DB document.

PrerrequisitosPrerequisites

Para completar este tutorial:To complete this tutorial:

Este tema usa como punto de inicio los recursos creados en Creación de su primera función desde Azure Portal.This topic uses as its starting point the resources created in Create your first function from the Azure portal. Si aún no lo hecho, lleve a cabo estos pasos ahora para crear la aplicación de función.If you haven't already done so, please complete these steps now to create your function app.

Creación de una cuenta de Azure Cosmos DBCreate an Azure Cosmos DB account

Debe tener una cuenta de Azure Cosmos DB que use la API de SQL para poder crear el enlace de salida.You must have an Azure Cosmos DB account that uses the SQL API before you create the output binding.

  1. En el menú de Azure Portal o en la página principal, seleccione Crear un recurso.From the Azure portal menu or the Home page, select Create a resource.

  2. En la página Nuevos, busque y seleccione Azure Cosmos DB.On the New page, search for and select Azure Cosmos DB.

  3. En la página Azure Cosmos DB, seleccione Crear.On the Azure Cosmos DB page, select Create.

  4. En la página Creación de una cuenta de Azure Cosmos DB , especifique la configuración básica de la nueva cuenta de Azure Cosmos.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    ConfiguraciónSetting ValueValue DescripciónDescription
    SubscriptionSubscription Nombre de suscripciónSubscription name Seleccione la suscripción de Azure que desea usar para esta cuenta de Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Grupo de recursosResource Group Definición de un nombre de grupo de recursosResource group name Seleccione un grupo de recursos o seleccione Crear nuevo y escriba un nombre único para el grupo de recursos nuevo.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Nombre de cuentaAccount Name Un nombre únicoA unique name Escriba un nombre para identificar la cuenta de Azure Cosmos.Enter a name to identify your Azure Cosmos account. Dado que documents.azure.com se anexa al nombre que se proporciona para crear el identificador URI, debe usar un nombre único.Because documents.azure.com is appended to the name that you provide to create your URI, use a unique name.

    El nombre solo puede contener letras minúsculas, números y el carácter de guion (-).The name can only contain lowercase letters, numbers, and the hyphen (-) character. Debe tener una longitud de entre 3 y 44 caracteres.It must be between 3-44 characters in length.
    APIAPI El tipo de cuenta que se va a crearThe type of account to create Seleccione Core(SQL) para crear una base de datos de documentos y consultarla mediante la sintaxis SQL.Select Core (SQL) to create a document database and query by using SQL syntax.

    La API determina el tipo de cuenta que se va a crear.The API determines the type of account to create. Azure Cosmos DB proporciona cinco API: Core (SQL) y MongoDB para datos de documento, Gremlin para datos de gráfico, Azure Table y Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. Actualmente, debe crear una cuenta independiente para cada API.Currently, you must create a separate account for each API.
    Capacity mode (Modo de capacidad)Capacity mode Rendimiento aprovisionado o sin servidorProvisioned throughput or Serverless Seleccione Provisioned throughput (Rendimiento aprovisionado) para crear una cuenta en modo de rendimiento aprovisionado.Select Provisioned throughput to create an account in provisioned throughput mode. Seleccione Serverless (Sin servidor) para crear una cuenta en modo sin servidor.Select Serverless to create an account in serverless mode.
    Aplicación de descuento por nivel GratisApply Free Tier Discount Aplicar o no aplicarApply or Do not apply Con el nivel Gratis de Azure Cosmos DB, obtendrá los primeros 400 RU/s y 5 GB de almacenamiento gratis en una cuenta.With Azure Cosmos DB free tier, you will get the first 400 RU/s and 5 GB of storage for free in an account. Más información acerca del nivel Gratis.Learn more about free tier.
    LocationLocation Región más cercana a los usuariosThe region closest to your users Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Use la ubicación más cercana a los usuarios para que puedan acceder de la forma más rápida posible a los datos.Use the location that is closest to your users to give them the fastest access to the data.
    Tipo de cuentaAccount Type Producción o no producciónProduction or Non-Production Seleccione Producción si la cuenta se va a usar para una carga de trabajo de producción.Select Production if the account will be used for a production workload. Seleccione No producción si la cuenta se va a usar para entornos que no son de producción, como desarrollo, pruebas, control de calidad o almacenamiento provisional.Select Non-Production if the account will be used for non-production, e.g. development, testing, QA, or staging. Se trata de una configuración de etiquetas de recursos de Azure que ajusta la experiencia del portal, pero no afecta a la cuenta de Azure Cosmos DB subyacente.This is an Azure resource tag setting that tunes the Portal experience but does not affect the underlying Azure Cosmos DB account. Este valor se puede cambiar en cualquier momento.You can change this value anytime.

    Nota

    Puede tener una cuenta de Azure Cosmos DB de nivel Gratis por cada suscripción de Azure y debe optar por tenerla al crear la cuenta.You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. Si no ve la opción para aplicar el descuento por nivel Gratis, significará que en otra cuenta de la suscripción ya se ha habilitado el nivel Gratis.If you do not see the option to apply the free tier discount, this means another account in the subscription has already been enabled with free tier.

    Nota

    Las siguientes opciones no están disponibles si selecciona Serverless (Sin servidor) en Capacity mode (Modo de capacidad):The following options are not available if you select Serverless as the Capacity mode:

    • Aplicación de descuento por nivel GratisApply Free Tier Discount
    • Redundancia geográficaGeo-redundancy
    • Escrituras en varias regionesMulti-region Writes

    Página de la nueva cuenta de Azure Cosmos DB

  5. Seleccione Revisar + crear.Select Review + create. Puede omitir las secciones Red y Etiquetas.You can skip the Network and Tags sections.

  6. Revise la configuración de la cuenta y seleccione Crear.Review the account settings, and then select Create. La operación de creación de la cuenta tarda unos minutos.It takes a few minutes to create the account. Espere hasta que la página del portal muestre Se completó la implementación .Wait for the portal page to display Your deployment is complete.

    Panel de notificaciones de Azure Portal

  7. Seleccione Ir al recurso para ir a la página de la cuenta de Azure Cosmos DB.Select Go to resource to go to the Azure Cosmos DB account page.

    Página de la cuenta de Azure Cosmos DB

Adición de un enlace de salidaAdd an output binding

  1. En Azure Portal, vaya a la aplicación de funciones que se ha creado anteriormente y selecciónela.In the Azure portal, navigate to and select the function app you created previously.

  2. Seleccione Funciones y, después, seleccione la función HttpTrigger.Select Functions, and then select the HttpTrigger function.

    Seleccione su función Http en Azure Portal.

  3. Seleccione Integración y + Agregar salida.Select Integration and + Add output.

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

  4. Use la configuración de Crear salida, como se especifica en la tabla:Use the Create Output settings as specified in the table:

    Configuración del enlace de salida de Azure Cosmos DB .

    ConfiguraciónSetting Valor sugeridoSuggested value DescripciónDescription
    Tipo de enlaceBinding Type Azure Cosmos DBAzure Cosmos DB Nombre del tipo de enlace que se selecciona para crear el enlace de salida a Azure Cosmos DB.Name of the binding type to select to create the output binding to Azure Cosmos DB.
    Nombre del parámetro de documentoDocument parameter name taskDocumenttaskDocument Nombre que hace referencia al objeto de Cosmos DB en el código.Name that refers to the Cosmos DB object in code.
    Nombre de la base de datosDatabase name taskDatabasetaskDatabase Nombre de la base de datos para guardar documentos.Name of database to save documents.
    Nombre de colecciónCollection name taskCollectiontaskCollection Nombre de la colección de la base de datos.Name of the database collection.
    Si es true, crea la base de datos y la colección de Cosmos DBIf true, creates the Cosmos DB database and collection Yes La colección no existe, por lo que se crea.The collection doesn't already exist, so create it.
    Conexión de la cuenta de Cosmos DBCosmos DB account connection Nueva configuraciónNew setting Seleccione Nuevo, luego, Cuenta de Azure Cosmos DB y la cuenta de la base de datos que creó anteriormente y, después, seleccione Aceptar.Select New, then choose Azure Cosmos DB Account and the Database account you created earlier, and then select OK. Con esto se crea una configuración de la aplicación para la conexión de la cuenta.Creates an application setting for your account connection. Esta configuración la usa el enlace para establecer la conexión a la base de datos.This setting is used by the binding to connection to the database.
  5. Seleccione Aceptar para crear el enlace.Select OK to create the binding.

Actualización del código de la funciónUpdate the function code

Reemplace el código existente de la función por el código siguiente, en el lenguaje de su elección:Replace the existing function code with the following code, in your chosen language:

Reemplace la función de C# existente por el código siguiente:Replace the existing C# function with the following code:

#r "Newtonsoft.Json"

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;

public static IActionResult Run(HttpRequest req, out object taskDocument, ILogger log)
{
    string name = req.Query["name"];
    string task = req.Query["task"];
    string duedate = req.Query["duedate"];

    // We need both name and task parameters.
    if (!string.IsNullOrEmpty(name) && !string.IsNullOrEmpty(task))
    {
        taskDocument = new
        {
            name,
            duedate,
            task
        };

        return (ActionResult)new OkResult();
    }
    else
    {
        taskDocument = null;
        return (ActionResult)new BadRequestResult();
    }
}

Este ejemplo de código lee las cadenas de consulta de la solicitud HTTP y las asigna a los campos del objeto taskDocument.This code sample reads the HTTP Request query strings and assigns them to fields in the taskDocument object. El enlace taskDocument envía los datos del objeto desde este parámetro de enlace para almacenarlos en la base de datos de documentos enlazada.The taskDocument binding sends the object data from this binding parameter to be stored in the bound document database. La base de datos se crea la primera vez que se ejecuta la función.The database is created the first time the function runs.

Prueba de la función y la base de datosTest the function and database

  1. Seleccione Probar/Ejecutar.Select Test/Run. En Consulta, seleccione + Agregar parámetro y agregue los siguientes parámetros a la cadena de consulta:Under Query, select + Add parameter and add the following parameters to the query string:

    • name
    • task
    • duedate

    Probar la función.

  2. Seleccione Ejecutar y compruebe que se devuelve un estado 200.Select Run and verify that a 200 status is returned.

    Captura de pantalla del estado 200 del código de respuesta HTTP resaltado después de seleccionar Ejecutar.

  3. En Azure Portal, busque y seleccione Azure Cosmos DB.In the Azure portal, search for and select Azure Cosmos DB.

    Búsqueda del servicio Cosmos DB .

  4. Elija la cuenta de Azure Cosmos DB y luego seleccione Explorador de datos.Choose your Azure Cosmos DB account, then select Data Explorer.

  5. Expanda los nodos de TaskCollection, seleccione el nuevo documento y confirme que el documento contiene los valores de la cadena de consulta, junto con metadatos adicionales.Expand the TaskCollection nodes, select the new document, and confirm that the document contains your query string values, along with some additional metadata.

    Verificar los valores de cadena del documento.

Ha agregado correctamente un enlace al desencadenador HTTP que almacena datos no estructurados en Azure Cosmos DB.You've successfully added a binding to your HTTP trigger to store unstructured data in an Azure Cosmos DB.

Limpieza de recursosClean up resources

En los pasos anteriores, creó recursos de Azure en un grupo de recursos.In the preceding steps, you created Azure resources in a resource group. Si no cree que vaya a necesitar estos recursos en el futuro, puede eliminarlos mediante la eliminación del grupo de recursos.If you don't expect to need these resources in the future, you can delete them by deleting the resource group.

En el menú de Azure Portal o la página Inicio, seleccione Grupos de recursos.From the Azure portal menu or Home page, select Resource groups. En la página Grupos de recursos, seleccione myResourceGroup.Then, on the Resource groups page, select myResourceGroup.

En la página myResourceGroup, asegúrese de que los recursos enumerados sean los que desea eliminar.On the myResourceGroup page, make sure that the listed resources are the ones you want to delete.

Seleccione Eliminar grupo de recursos, escriba myResourceGroup en el cuadro de texto para confirmar y, después, seleccione Eliminar.Select Delete resource group, type myResourceGroup in the text box to confirm, and then select Delete.

Pasos siguientesNext steps

Para más información sobre el enlace a una base de datos de la base de datos de Cosmos, consulte Enlaces de Cosmos DB en Azure Functions.For more information about binding to a Cosmos DB database, see Azure Functions Cosmos DB bindings.