Inicio rápido: Compilación de una aplicación de consola mediante el SDK para .NET V4 (versión preliminar) para administrar los recursos de la cuenta de SQL API de Azure Cosmos DB

Artículo
09/10/2021
14 minutos para leer

SE APLICA A: SQL API

Introducción a la biblioteca cliente de API de SQL de Azure Cosmos DB para .NET. Siga los pasos de este artículo para instalar el paquete .NET V4 (Azure.Cosmos) y compilar una aplicación. Luego, pruebe el código de ejemplo para las operaciones básicas de creación, lectura, actualización y eliminación (CRUD) en los datos almacenados en Azure Cosmos DB.

Importante

El SDK para .NET V4 de Azure Cosmos DB está actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin un Acuerdo de Nivel de Servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas.

Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

Azure Cosmos DB es una base de datos NoSQL rápida de Microsoft con API abiertas para cualquier escala. Puede usar Azure Cosmos DB para crear y consultar rápidamente las bases de datos de gráficos, documentos, claves y valores. Use la biblioteca cliente de API de SQL de Azure Cosmos DB para .NET para:

Crear una base de datos y un contenedor de Azure Cosmos.
Agregar datos de ejemplo al contenedor.
Consultar los datos.
Se elimina la base de datos.

Código fuente de la biblioteca | Paquete (NuGet)

Prerrequisitos

Suscripción de Azure. cree una de forma gratuita. También puede probar Azure Cosmos DB sin ninguna suscripción a Azure, de forma gratuita y sin compromiso alguno.
SDK de .NET Core 3. Puede comprobar qué versión está disponible en su entorno mediante la ejecución de dotnet --version.

Configurar

En esta sección se le guía por el proceso de creación de una cuenta de Azure Cosmos y de configuración de un proyecto que usa una biblioteca cliente de SQL API de Azure Cosmos DB para .NET para administrar recursos.

El código de ejemplo descrito en este artículo crea la base de datos FamilyDatabase y los miembros de la familia en esa base de datos. Cada miembro de la familia es un elemento y tiene propiedades como Id, FamilyName, FirstName, LastName, Parents, Children y Address. La propiedad LastName se usa como clave de partición para el contenedor.

Crear una cuenta de Azure Cosmos

Si usa la opción Try Azure Cosmos DB for free (Prueba gratuita de Azure Cosmos DB) para crear una cuenta de Azure Cosmos, debe crear una cuenta de Azure Cosmos DB del tipo SQL API. Ya se ha creado una cuenta de prueba de Azure Cosmos. No tiene que crear la cuenta explícitamente, por lo que puede omitir esta sección y pasar a la siguiente.

Si tiene su propia suscripción de Azure o creó una suscripción gratuita, debe crear una cuenta de Azure Cosmos explícitamente. El código siguiente creará una cuenta de Azure Cosmos con coherencia de sesión. La cuenta se replica en South Central US y North Central US.

Puede usar Azure Cloud Shell para crear la cuenta de Azure Cosmos. Azure Cloud Shell es un shell interactivo, autenticado y al que se puede acceder desde un explorador para administrar recursos de Azure. Permite elegir la experiencia de shell que mejor se adapte a la forma de trabajar de cada uno: Bash o PowerShell.

Para este inicio rápido, use Bash. Azure Cloud Shell también requiere una cuenta de almacenamiento. Puede crearla cuando se le solicite.

Seleccione el botón Pruébelo que encontrará junto al siguiente código, elija el modo Bash, seleccione Crear una cuenta de almacenamiento e inicie sesión en Cloud Shell.

Copie y pegue el código siguiente en Azure Cloud Shell y ejecútelo. El nombre de la cuenta de Azure Cosmos debe ser único globalmente, por lo que debe asegurarse de actualizar el valor de mysqlapicosmosdb antes de ejecutar el comando.


# Set variables for the new SQL API account, database, and container
resourceGroupName='myResourceGroup'
location='southcentralus'

# The Azure Cosmos account name must be globally unique, so be sure to update the `mysqlapicosmosdb` value before you run the command
accountName='mysqlapicosmosdb'

# Create a resource group
az group create \
    --name $resourceGroupName \
    --location $location

# Create a SQL API Cosmos DB account with session consistency and multi-region writes enabled
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --kind GlobalDocumentDB \
    --locations regionName="South Central US" failoverPriority=0 --locations regionName="North Central US" failoverPriority=1 \
    --default-consistency-level "Session" \
    --enable-multiple-write-locations true

La cuenta de Azure Cosmos tarda un tiempo en crearse. Una vez que la operación se haya realizado correctamente, puede ver la salida de confirmación. Inicie sesión en Azure Portal y compruebe que existe la cuenta de Azure Cosmos con el nombre especificado. Puede cerrar la ventana de Azure Cloud Shell una vez creado el recurso.

Creación de una aplicación .NET

Cree una aplicación .NET en el entorno de desarrollo integrado o editor que prefiera. Abra el símbolo del sistema de Windows o una ventana de terminal en el equipo local. En las secciones siguientes todos los comandos se ejecutarán desde el símbolo del sistema o desde el terminal.

Ejecute el comando dotnet new siguiente para crear una aplicación llamada todo. El parámetro --langVersion establece la propiedad LangVersion en el archivo de proyecto creado.

dotnet new console --langVersion:8 -n todo

Use los siguientes comandos para cambiar de directorio a la carpeta de la aplicación recién creada y compilar la aplicación:

cd todo
dotnet build

El resultado esperado de la compilación debe parecerse a lo siguiente:

  Restore completed in 100.37 ms for C:\Users\user1\Downloads\CosmosDB_Samples\todo\todo.csproj.
  todo -> C:\Users\user1\Downloads\CosmosDB_Samples\todo\bin\Debug\netcoreapp3.0\todo.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:34.17

Instalar el paquete de Azure Cosmos DB

Aún en el directorio de la aplicación, instale el paquete de la biblioteca cliente de Azure Cosmos DB para .NET Core mediante el comando dotnet add package:

dotnet add package Azure.Cosmos --version 4.0.0-preview3

Copiar las credenciales de la cuenta de Azure Cosmos desde Azure Portal

La aplicación de ejemplo debe autenticarse para la cuenta de Azure Cosmos. Para realizar la autenticación, pase las credenciales de la cuenta de Azure Cosmos a la aplicación. Para obtener las credenciales de cuenta de Azure Cosmos, siga estos pasos:

Inicie sesión en Azure Portal.
Vaya a la cuenta de Azure Cosmos.
Abra el panel Claves y copie los valores de URI y CLAVE PRINCIPAL de la cuenta. En el procedimiento siguiente, agregará los valores de URI y de la lave a una variable de entorno.

Modelo de objetos

Antes de seguir compilando la aplicación, vamos a examinar la jerarquía de recursos de Azure Cosmos DB y el modelo de objetos que se usa para crear estos recursos y acceder a ellos. Azure Cosmos DB crea recursos en el orden siguiente:

Cuenta de Azure Cosmos
Bases de datos
Contenedores
Elementos

Para más información sobre la jerarquía de entidades, consulte el artículo Modelo de recursos de Azure Cosmos DB. Usará las siguientes clases de .NET para interactuar con estos recursos:

CosmosClient. Esta clase proporciona una representación lógica del cliente para el servicio Azure Cosmos DB. El objeto de cliente se usa para configurar y ejecutar solicitudes en el servicio.
CreateDatabaseIfNotExistsAsync. Este método crea (si no existe) un recurso de base de datos o lo obtiene (en caso de que ya exista) como operación asincrónica.
CreateContainerIfNotExistsAsync. Este método crea (si no existe) un contenedor o lo obtiene (en caso de que ya exista) como operación asincrónica. Puede comprobar el código de estado de la respuesta para determinar si el contenedor se creó recientemente (201) o si se devolvió un contenedor existente (200).
CreateItemAsync. Este método crea un elemento en el contenedor.
UpsertItemAsync. Este método crea un elemento en el contenedor, si aún no existe, o lo reemplaza si ya existe.
GetItemQueryIterator. Este método crea una consulta para los elementos de un contenedor en una base de datos de Azure Cosmos mediante una instrucción SQL con valores con parámetros.
DeleteAsync. Este método elimina la base de datos especificada de una cuenta de Azure Cosmos.

Configuración de ejemplos de código

En el código de ejemplo que se describe en este artículo, se crea una base de datos de familia en Azure Cosmos DB. La base de datos de la familia contiene detalles de la familia como el nombre, la dirección, la ubicación, los padres, los hijos y las mascotas.

Antes de rellenar los datos de su cuenta de Azure Cosmos, defina las propiedades de un elemento de familia. Cree una nueva clase denominada Family.cs en el nivel raíz de la aplicación de ejemplo y agréguele el código siguiente:

using System.Text.Json;
using System.Text.Json.Serialization;

namespace todo
{
    public class Family
    {
        [JsonPropertyName("id")]
        public string Id { get; set; }
        public string LastName { get; set; }
        public Parent[] Parents { get; set; }
        public Child[] Children { get; set; }
        public Address Address { get; set; }
        public bool IsRegistered { get; set; }
        public override string ToString()
        {
            return JsonSerializer.Serialize(this);
        }
    }

    public class Parent
    {
        public string FamilyName { get; set; }
        public string FirstName { get; set; }
    }

    public class Child
    {
        public string FamilyName { get; set; }
        public string FirstName { get; set; }
        public string Gender { get; set; }
        public int Grade { get; set; }
        public Pet[] Pets { get; set; }
    }

    public class Pet
    {
        public string GivenName { get; set; }
    }

    public class Address
    {
        public string State { get; set; }
        public string County { get; set; }
        public string City { get; set; }
    }
}

Incorporación de las directivas de uso y definición del objeto cliente

En el directorio del proyecto, abra el archivo Program.cs en el editor y agregue las siguientes directivas using en la parte superior de la aplicación:

using System;
using System.Collections.Generic;
using System.Net;
using System.Threading.Tasks;
using Azure.Cosmos;

En la clase Program, agregue las variables globales siguientes. Dichas variables incluirán el punto de conexión y las claves de autorización, el nombre de la base de datos y el contenedor que creará. Asegúrese de reemplazar los valores de punto de conexión y clave de autorización en función de su entorno.

private const string EndpointUrl = "https://<your-account>.documents.azure.com:443/";
private const string AuthorizationKey = "<your-account-key>";
private const string DatabaseId = "FamilyDatabase";
private const string ContainerId = "FamilyContainer";

Finalmente, reemplace el método Main:

static async Task Main(string[] args)
{
    
    CosmosClient cosmosClient = new CosmosClient(EndpointUrl, AuthorizationKey);
    await Program.CreateDatabaseAsync(cosmosClient);
    await Program.CreateContainerAsync(cosmosClient);
    await Program.AddItemsToContainerAsync(cosmosClient);
    await Program.QueryItemsAsync(cosmosClient);
    await Program.ReplaceFamilyItemAsync(cosmosClient);
    await Program.DeleteFamilyItemAsync(cosmosClient);
    await Program.DeleteDatabaseAndCleanupAsync(cosmosClient);
}

Crear una base de datos

Defina el método CreateDatabaseAsync dentro de la clase program.cs. Este método crea la base de datos FamilyDatabase, en caso de que no exista.

/// <summary>
/// Create the database if it does not exist
/// </summary>
private static async Task CreateDatabaseAsync(CosmosClient cosmosClient)
{
    // Create a new database
    CosmosDatabase database = await cosmosClient.CreateDatabaseIfNotExistsAsync(Program.DatabaseId);
    Console.WriteLine("Created Database: {0}\n", database.Id);
}

Crear un contenedor

Defina el método CreateContainerAsync dentro de la clase Program. Este método crea el contenedor FamilyContainer, en caso de que no exista.

/// <summary>
/// Create the container if it does not exist. 
/// Specify "/LastName" as the partition key since we're storing family information, to ensure good distribution of requests and storage.
/// </summary>
/// <returns></returns>
private static async Task CreateContainerAsync(CosmosClient cosmosClient)
{
    // Create a new container
    CosmosContainer container = await cosmosClient.GetDatabase(Program.DatabaseId).CreateContainerIfNotExistsAsync(Program.ContainerId, "/LastName");
    Console.WriteLine("Created Container: {0}\n", container.Id);
}

Crear un elemento

Para crear un elemento de familia, agregue el método AddItemsToContainerAsync con el código siguiente. Puede usar los métodos CreateItemAsync o UpsertItemAsync para crear un elemento.

/// <summary>
/// Add Family items to the container
/// </summary>
private static async Task AddItemsToContainerAsync(CosmosClient cosmosClient)
{
    // Create a family object for the Andersen family
    Family andersenFamily = new Family
    {
        Id = "Andersen.1",
        LastName = "Andersen",
        Parents = new Parent[]
        {
            new Parent { FirstName = "Thomas" },
            new Parent { FirstName = "Mary Kay" }
        },
        Children = new Child[]
        {
            new Child
            {
                FirstName = "Henriette Thaulow",
                Gender = "female",
                Grade = 5,
                Pets = new Pet[]
                {
                    new Pet { GivenName = "Fluffy" }
                }
            }
        },
        Address = new Address { State = "WA", County = "King", City = "Seattle" },
        IsRegistered = false
    };

    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);
    try
    {
        // Read the item to see if it exists.  
        ItemResponse<Family> andersenFamilyResponse = await container.ReadItemAsync<Family>(andersenFamily.Id, new PartitionKey(andersenFamily.LastName));
        Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamilyResponse.Value.Id);
    }
    catch(CosmosException ex) when (ex.Status == (int)HttpStatusCode.NotFound)
    {
        // Create an item in the container representing the Andersen family. Note we provide the value of the partition key for this item, which is "Andersen"
        ItemResponse<Family> andersenFamilyResponse = await container.CreateItemAsync<Family>(andersenFamily, new PartitionKey(andersenFamily.LastName));

        // Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse.
        Console.WriteLine("Created item in database with id: {0}\n", andersenFamilyResponse.Value.Id);
    }

    // Create a family object for the Wakefield family
    Family wakefieldFamily = new Family
    {
        Id = "Wakefield.7",
        LastName = "Wakefield",
        Parents = new Parent[]
        {
            new Parent { FamilyName = "Wakefield", FirstName = "Robin" },
            new Parent { FamilyName = "Miller", FirstName = "Ben" }
        },
        Children = new Child[]
        {
            new Child
            {
                FamilyName = "Merriam",
                FirstName = "Jesse",
                Gender = "female",
                Grade = 8,
                Pets = new Pet[]
                {
                    new Pet { GivenName = "Goofy" },
                    new Pet { GivenName = "Shadow" }
                }
            },
            new Child
            {
                FamilyName = "Miller",
                FirstName = "Lisa",
                Gender = "female",
                Grade = 1
            }
        },
        Address = new Address { State = "NY", County = "Manhattan", City = "NY" },
        IsRegistered = true
    };

    // Create an item in the container representing the Wakefield family. Note we provide the value of the partition key for this item, which is "Wakefield"
    ItemResponse<Family> wakefieldFamilyResponse = await container.UpsertItemAsync<Family>(wakefieldFamily, new PartitionKey(wakefieldFamily.LastName));

    // Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse. We can also access the RequestCharge property to see the amount of RUs consumed on this request.
    Console.WriteLine("Created item in database with id: {0}\n", wakefieldFamilyResponse.Value.Id);
}

Consultar elementos

Después de insertar un elemento, puede ejecutar una consulta para obtener los detalles de la familia Andersen. El código siguiente muestra cómo ejecutar la consulta directamente con la consulta SQL. La consulta SQL para obtener los detalles de la familia Andersen es SELECT * FROM c WHERE c.LastName = 'Andersen'. Defina el método QueryItemsAsync en la clase Program y agréguele el código siguiente:

/// <summary>
/// Run a query (using Azure Cosmos DB SQL syntax) against the container
/// </summary>
private static async Task QueryItemsAsync(CosmosClient cosmosClient)
{
    var sqlQueryText = "SELECT * FROM c WHERE c.LastName = 'Andersen'";

    Console.WriteLine("Running query: {0}\n", sqlQueryText);

    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);

    QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText);

    List<Family> families = new List<Family>();

    await foreach (Family family in container.GetItemQueryIterator<Family>(queryDefinition))
    {
        families.Add(family);
        Console.WriteLine("\tRead {0}\n", family);
    }
}

Reemplazo de un elemento

Lea un elemento de familia y, después, actualícelo mediante la adición del método ReplaceFamilyItemAsync con el siguiente código:

/// <summary>
/// Replace an item in the container
/// </summary>
private static async Task ReplaceFamilyItemAsync(CosmosClient cosmosClient)
{
    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);

    ItemResponse<Family> wakefieldFamilyResponse = await container.ReadItemAsync<Family>("Wakefield.7", new PartitionKey("Wakefield"));
    Family itemBody = wakefieldFamilyResponse;
    
    // update registration status from false to true
    itemBody.IsRegistered = true;
    // update grade of child
    itemBody.Children[0].Grade = 6;

    // replace the item with the updated content
    wakefieldFamilyResponse = await container.ReplaceItemAsync<Family>(itemBody, itemBody.Id, new PartitionKey(itemBody.LastName));
    Console.WriteLine("Updated Family [{0},{1}].\n \tBody is now: {2}\n", itemBody.LastName, itemBody.Id, wakefieldFamilyResponse.Value);
}

Eliminación de un elemento

Para eliminar un elemento de la familia, agregue el método DeleteFamilyItemAsync con el código siguiente:

/// <summary>
/// Delete an item in the container
/// </summary>
private static async Task DeleteFamilyItemAsync(CosmosClient cosmosClient)
{
    CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);

    string partitionKeyValue = "Wakefield";
    string familyId = "Wakefield.7";

    // Delete an item. Note we must provide the partition key value and id of the item to delete
    ItemResponse<Family> wakefieldFamilyResponse = await container.DeleteItemAsync<Family>(familyId,new PartitionKey(partitionKeyValue));
    Console.WriteLine("Deleted Family [{0},{1}]\n", partitionKeyValue, familyId);
}

Eliminación de la base de datos

Para eliminar la base de datos, agregue el método DeleteDatabaseAndCleanupAsync con el código siguiente:

/// <summary>
/// Delete the database and dispose of the Cosmos Client instance
/// </summary>
private static async Task DeleteDatabaseAndCleanupAsync(CosmosClient cosmosClient)
{
    CosmosDatabase database = cosmosClient.GetDatabase(Program.DatabaseId);
    DatabaseResponse databaseResourceResponse = await database.DeleteAsync();

    Console.WriteLine("Deleted Database: {0}\n", Program.DatabaseId);
}

Después de agregar todos los métodos necesarios, guarde el archivo Program.cs.

Ejecución del código

Ejecute la aplicación para crear los recursos de Azure Cosmos DB:

dotnet run

Al ejecutar la aplicación, se genera el siguiente resultado:

Created Database: FamilyDatabase

Created Container: FamilyContainer

Created item in database with id: Andersen.1

Running query: SELECT * FROM c WHERE c.LastName = 'Andersen'

        Read {"id":"Andersen.1","LastName":"Andersen","Parents":[{"FamilyName":null,"FirstName":"Thomas"},{"FamilyName":null   "FirstName":"Mary Kay"}],"Children":[{"FamilyName":null,"FirstName":"Henriette Thaulow","Gender":"female","Grade":5,"Pets": [{"GivenName":"Fluffy"}]}],"Address":{"State":"WA","County":"King","City":"Seattle"},"IsRegistered":false}

Updated Family [Wakefield,Wakefield.7].
        Body is now: {"id":"Wakefield.7","LastName":"Wakefield","Parents":[{"FamilyName":"Wakefield","FirstName":"Robin"}   {"FamilyName":"Miller","FirstName":"Ben"}],"Children":[{"FamilyName":"Merriam","FirstName":"Jesse","Gender":"female","Grade":6   "Pets":[{"GivenName":"Goofy"},{"GivenName":"Shadow"}]},{"FamilyName":"Miller","FirstName":"Lisa","Gender":"female","Grade":1   "Pets":null}],"Address":{"State":"NY","County":"Manhattan","City":"NY"},"IsRegistered":true}

Deleted Family [Wakefield,Wakefield.7]

Deleted Database: FamilyDatabase

End of demo, press any key to exit.

Para validar la creación de los datos, inicie sesión en Azure Portal y vea los elementos necesarios en su cuenta de Azure Cosmos.

Limpieza de recursos

Cuando ya no necesite la cuenta de Azure Cosmos y el grupo de recursos correspondiente, puede usar el CLI de Azure o Azure PowerShell para quitarlos. El siguiente comando muestra cómo eliminar el grupo de recursos con el CLI de Azure:

az group delete -g "myResourceGroup"

Pasos siguientes

En este inicio rápido, ha aprendido a crear una cuenta de Azure Cosmos, una base de datos y un contenedor mediante una aplicación de .NET Core. Ahora puede importar más datos en su cuenta de Azure Cosmos. Para ello, debe seguir las instrucciones del siguiente artículo:

¿Intenta planear la capacidad para una migración a Azure Cosmos DB? Para ello, puede usar información sobre el clúster de base de datos existente.

Si todo lo que sabe es el número de núcleos virtuales y servidores del clúster de base de datos existente, lea sobre cómo calcular las unidades de solicitud mediante núcleos o CPU virtuales.
Si conoce las velocidades de solicitud típicas de la carga de trabajo de base de datos actual, lea sobre el cálculo de las unidades de solicitud mediante la herramienta de planeamiento de capacidad de Azure Cosmos DB.

Importación de datos a Azure Cosmos DB