Inicio rápido: Biblioteca cliente de Azure Cosmos DB for NoSQL para .NET

SE APLICA A: NoSQL

• .NET
• Node.js
• Java
• Spring Data
• Python
• Spark v3
• Go

Comenzar con la biblioteca cliente de Azure Cosmos DB para .NET para crear bases de datos, contenedores y elementos dentro de la cuenta. Siga estos pasos para instalar el paquete y probar el código de ejemplo para realizar tareas básicas.

Nota:

Los fragmentos de código de ejemplo están disponibles en GitHub como un proyecto de .NET.

Documentación de referencia de la API | Código fuente de la biblioteca | Paquete (NuGet) | Ejemplos

Prerrequisitos

• Una cuenta de Azure con una suscripción activa.
  • ¿No tiene una suscripción de Azure? Puede probar Azure Cosmos DB gratis sin que tenga que proporcionar una tarjeta de crédito.
• .NET 6.0 o versión posterior
• Interfaz de la línea de comandos (CLI) de Azure o Azure PowerShell

Comprobación de requisitos previos

• En una ventana de terminal o de comandos, ejecute dotnet --version para comprobar que el SDK de .NET es de la versión 6.0 o posterior.
• Ejecute az --version (CLI de Azure) o Get-Module -ListAvailable AzureRM (Azure PowerShell) para comprobar que tiene instaladas las herramientas adecuadas de la línea de comandos de Azure.

Instalación

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

Creación de una cuenta de Azure Cosmos DB

Sugerencia

¿No tiene una suscripción de Azure? Puede probar Azure Cosmos DB gratis sin que tenga que proporcionar una tarjeta de crédito. Si crea una cuenta con la evaluación gratuita, puede ir directamente a la sección Creación de una nueva aplicación .NET.

En este inicio rápido se creará una única cuenta de Azure Cosmos DB mediante la API para NoSQL.

Portal

Sugerencia

Para este inicio rápido, se recomienda usar el nombre del grupo de recursos msdocs-cosmos-quickstart-rg.

1. Inicie sesión en Azure Portal.

2. En el menú de Azure Portal o en la página principal, seleccione Crear un recurso.

3. En la página Nuevos, busque y seleccione Azure Cosmos DB.

4. En la página Selección de la opción de API, seleccione la opción Crear en la sección NoSQL. Azure Cosmos DB tiene seis API: NoSQL, MongoDB, PostgreSQL, Apache Cassandra, Apache Gremlin y Table. Más información acerca de la API para NoSQL.

   

5. En la página Creación de una cuenta de Azure Cosmos DB, incluya la siguiente información:

   Configuración	Value	Descripción
   Subscription	Nombre de suscripción	Seleccione la suscripción de Azure que desea usar para esta cuenta de Azure Cosmos.
   Grupo de recursos	Definición de un nombre de grupo de recursos	Seleccione un grupo de recursos o seleccione Crear nuevo y escriba un nombre único para el grupo de recursos nuevo.
   Nombre de cuenta	Un nombre único	Escriba un nombre para identificar la cuenta de Azure Cosmos. El nombre se usará como parte de un nombre de dominio completo (FQDN) con el sufijo documents.azure.com, por lo que el nombre debe ser único a nivel global. El nombre solo puede contener letras minúsculas, números y el carácter de guion (-). Además, el nombre debe tener una longitud comprendida entre 3 y 44 caracteres.
   Location	Región más cercana a los usuarios	Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB. 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.
   Capacity mode (Modo de capacidad)	Rendimiento aprovisionado o sin servidor	Seleccione Provisioned throughput (Rendimiento aprovisionado) para crear una cuenta en modo de rendimiento aprovisionado. Seleccione Serverless (Sin servidor) para crear una cuenta en modo sin servidor.
   Aplicar el descuento del nivel Gratis de Azure Cosmos DB	Aplicar o No aplicar	Habilite el nivel gratis de Azure Cosmos DB. Con el nivel Gratis de Azure Cosmos DB, recibirá los primeros 1000 RU/s y 25 GB de almacenamiento gratis en una cuenta. Más información acerca del nivel Gratis.

   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. 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.

   

6. Seleccione Revisar + crear.

7. Revise la configuración que proporcione y, a continuación, seleccione Crear. La operación de creación de la cuenta tarda unos minutos. Antes de avanzar, espere a que la página del portal muestre Se completó la implementación.

8. Seleccione Ir al recurso para ir a la página de la cuenta de Azure Cosmos DB.

   

9. En la página de la cuenta de la API para NoSQL, seleccione la opción del menú de navegación Claves.

   

10. Registre los valores de los campos URI y CLAVE PRINCIPAL. Usará estos valores en un paso posterior.

    

CLI de Azure

1. Cree variables de shell para accountName, resourceGroupName y location.

   # Variable for resource group name
   resourceGroupName="msdocs-cosmos-quickstart-rg"
   location="westus"
   
   # Variable for account name with a randomly generated suffix
   let suffix=$RANDOM*$RANDOM
   accountName="msdocs-$suffix"
   

2. Si aún no lo ha hecho, inicie sesión en la CLI de Azure con el comando az login.

3. Use el comando az group create para crear un nuevo grupo de recursos en la suscripción.

   az group create \
       --name $resourceGroupName \
       --location $location
   

4. Use el comando az cosmosdb create para crear una nueva cuenta de la API para NoSQL con la configuración predeterminada.

   az cosmosdb create \
       --resource-group $resourceGroupName \
       --name $accountName \
       --locations regionName=$location \
       --enable-free-tier true
   

   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. 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. Para buscar otras cuentas habilitadas para el nivel gratuito, consulte Búsqueda de una cuenta de nivel gratuito de Azure Cosmos DB existente en una suscripción.

5. Obtenga el URI del punto de conexión de la API de NoSQL para la cuenta mediante el comando az cosmosdb show.

   az cosmosdb show \
       --resource-group $resourceGroupName \
       --name $accountName \
       --query "documentEndpoint"
   

6. Busque la CLAVE PRINCIPAL en la lista de claves de la cuenta con el comando az-cosmosdb-keys-list.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "keys" \
       --query "primaryMasterKey"
   

7. Registre los valores de URI y CLAVE PRINCIPAL. Necesitará estas credenciales más adelante.

PowerShell

1. Cree variables de shell para ACCOUNT_NAME, RESOURCE_GROUP_NAME y LOCATION.

   # Variable for resource group name
   $RESOURCE_GROUP_NAME = "msdocs-cosmos-quickstart-rg"
   $LOCATION = "West US"
   
   # Variable for account name with a randomly generated suffix
   $SUFFIX = Get-Random
   $ACCOUNT_NAME = "msdocs-$SUFFIX"
   

2. Si aún no lo ha hecho, inicie sesión en Azure PowerShell con el cmdlet Connect-AzAccount.

3. Use el cmdlet New-AzResourceGroup para crear un nuevo grupo de recursos en la suscripción.

   $parameters = @{
       Name = $RESOURCE_GROUP_NAME
       Location = $LOCATION
   }
   New-AzResourceGroup @parameters    
   

4. Use el cmdlet New-AzCosmosDBAccount para crear una nueva cuenta de la API para NoSQL con la configuración predeterminada.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Location = $LOCATION
       EnableFreeTier = true
   }
   New-AzCosmosDBAccount @parameters
   

   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. 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.

5. Obtenga el URI del punto de conexión de la API de NoSQL para la cuenta mediante el cmdlet Get-AzCosmosDBAccount.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
   }
   Get-AzCosmosDBAccount @parameters |
       Select-Object -Property "DocumentEndpoint"
   

6. Busque la CLAVE PRINCIPAL en la lista de claves de la cuenta con el cmdlet Get-AzCosmosDBAccountKey.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "Keys"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "PrimaryMasterKey"    
   

7. Registre los valores de URI y CLAVE PRINCIPAL. Necesitará estas credenciales más adelante.

Crear una nueva aplicación .NET

Cree una nueva aplicación de .NET en una carpeta vacía con su terminal preferido. Use el comando dotnet new que especifica la plantilla console.

dotnet new console

Instalar el paquete

Agregue el paquete NuGet microsoft.Azure.Cosmos al proyecto de .NET. Use el comando dotnet add package especificando el nombre del paquete de NuGet.

dotnet add package Microsoft.Azure.Cosmos

Compile el proyecto con el comando dotnet build.

dotnet build

Asegúrese de que la compilación se realizó correctamente sin errores. El resultado esperado de la compilación debe parecerse a lo siguiente:

  Determining projects to restore...
  All projects are up-to-date for restore.
  dslkajfjlksd -> C:\Users\sidandrews\Demos\dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll

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

Configuración de las variables de entorno

Para usar los valores de URI y CLAVE PRINCIPAL en el código, consérvelas en nuevas variables de entorno del equipo local que ejecuta la aplicación. Para establecer la variable de entorno, use el terminal preferido para ejecutar los siguientes comandos:

Windows

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Linux/macOS

export COSMOS_ENDPOINT="<cosmos-account-URI>"
export COSMOS_KEY="<cosmos-account-PRIMARY-KEY>"

Modelo de objetos

Antes de empezar a compilar la aplicación, consulte la jerarquía de recursos en Azure Cosmos DB. Azure Cosmos DB tiene un modelo de objetos específico que se usa para crear los recursos y acceder a ellos. Azure Cosmos DB crea recursos en una jerarquía que consta de cuentas, bases de datos, contenedores y elementos.

Diagrama jerárquico que muestra una cuenta de Azure Cosmos DB en la parte superior. La cuenta tiene dos nodos de base de datos secundarios. Uno de los nodos de la base de datos incluye dos nodos de contenedor secundarios. El otro nodo de la base de datos incluye un único nodo de contenedor secundario. Ese nodo de contenedor único tiene tres nodos de elementos secundarios.

Para más información sobre la jerarquía de diferentes recursos, consulte Utilización de bases de datos, contenedores y elementos en Azure Cosmos DB.

Usará las siguientes clases de .NET para interactuar con estos recursos:

• CosmosClient: esta clase proporciona una representación lógica del lado cliente para el servicio Azure Cosmos DB. El objeto de cliente se usa para configurar y ejecutar solicitudes en el servicio.
• Database: esta clase es una referencia a una base de datos que podría existir ya o no en el servicio. La base de datos se valida en el lado servidor al intentar acceder a ella o realizar alguna una operación en ella.
• Container: esta clase es una referencia a un contenedor que podría no existir aún en el servicio. El contenedor se valida en el lado servidor al intentar utilizarlo.
• QueryDefinition: esta clase representa una consulta SQL y cualquier parámetro de consulta.
• FeedIterator<>: esta clase representa un iterador que puede realizar un seguimiento de la página actual de resultados y obtener una nueva página de resultados.
• FeedResponse<>: esta clase representa una sola página de respuestas del iterador. Este tipo se puede iterar mediante un bucle foreach.

Ejemplos de código

• Autenticar el cliente
• Creación de una base de datos
• Creación de un contenedor
• Creación de un elemento
• Obtención de un elemento
• Elementos de consulta

El código de ejemplo descrito en este artículo crea una base de datos denominada adventureworks, con una contenedor denominado products. La tabla products se ha diseñado para incluir detalles de los productos, como el nombre, la categoría, la cantidad y un indicador de venta. Cada producto también contiene un identificador único.

Para este código de ejemplo, el contenedor usará la categoría como clave de partición lógica.

Autenticar el cliente

En el directorio del proyecto, abra el archivo Program.cs. En el editor, agregue una directiva using para Microsoft.Azure.Cosmos.

using Microsoft.Azure.Cosmos;

Defina una nueva instancia de la clase CosmosClient mediante el constructor y Environment.GetEnvironmentVariable para leer las dos variables de entorno que creó anteriormente.

// New instance of CosmosClient class
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);

Para más información sobre las distintas formas de crear una instancia de CosmosClient, consulte Comenzar con Azure Cosmos DB for NoSQL y .NET.

Crear una base de datos

Use el método CosmosClient.CreateDatabaseIfNotExistsAsync para crear una nueva base de datos si aún no existe. Este método devolverá una referencia a la base de datos existente o recién creada.

// Database reference with creation if it does not already exist
Database database = await client.CreateDatabaseIfNotExistsAsync(
    id: "cosmicworks"
);

Console.WriteLine($"New database:\t{database.Id}");

Para más información sobre cómo crear una base de datos, consulte Creación de una base de datos en Azure Cosmos DB for NoSQL mediante .NET.

Crear un contenedor

Database.CreateContainerIfNotExistsAsync creará un nuevo contenedor si aún no existe. Este método también devolverá una referencia al contenedor.

// Container reference with creation if it does not alredy exist
Container container = await database.CreateContainerIfNotExistsAsync(
    id: "products",
    partitionKeyPath: "/categoryId",
    throughput: 400
);

Console.WriteLine($"New container:\t{container.Id}");

Para más información sobre cómo crear un contenedor, consulte Creación de un contenedor en Azure Cosmos DB for NoSQL mediante .NET.

Crear un elemento

La manera más fácil de crear un nuevo elemento en un contenedor es compilar primero una clase o un tipo de registro de C# con todos los miembros que quiere serializar en JSON. En este ejemplo, el registro C# tiene un identificador único, un campo categoryId para la clave de partición y los campos adicionales categoryName, name, quantity y sales.

// C# record representing an item in the container
public record Product(
    string id,
    string categoryId,
    string categoryName,
    string name,
    int quantity,
    bool sale
);

Cree un elemento en el contenedor llamando a Container.CreateItemAsync.

// Create new object and upsert (create or replace) to container
Product newItem = new(
    id: "70b63682-b93a-4c77-aad2-65501347265f",
    categoryId: "61dba35b-4f02-45c5-b648-c6badc0cbd79",
    categoryName: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    sale: false
);

Product createdItem = await container.CreateItemAsync<Product>(
    item: newItem,
    partitionKey: new PartitionKey("61dba35b-4f02-45c5-b648-c6badc0cbd79")
);

Console.WriteLine($"Created item:\t{createdItem.id}\t[{createdItem.categoryName}]");

Para obtener más información sobre cómo crear, actualizar o reemplazar elementos, consulte Creación de un elemento en Azure Cosmos DB for NoSQL mediante .NET.

Obtención de un elemento

En Azure Cosmos DB, puede realizar una operación de lectura de punto mediante el identificador único (id) y los campos de clave de partición. En el SDK, llame a Container.ReadItemAsync<> pasando ambos valores para devolver una instancia deserializada del tipo C#.

// Point read item from container using the id and partitionKey
Product readItem = await container.ReadItemAsync<Product>(
    id: "70b63682-b93a-4c77-aad2-65501347265f",
    partitionKey: new PartitionKey("61dba35b-4f02-45c5-b648-c6badc0cbd79")
);

Para obtener más información sobre cómo leer elementos y analizar la respuesta, consulte Lectura de un elemento en Azure Cosmos DB for NoSQL mediante .NET.

Elementos de consulta

Después de insertar un elemento, puede ejecutar una consulta para obtener todos los elementos que coincidan con un filtro específico. En este ejemplo se ejecuta la consulta SQL: SELECT * FROM products p WHERE p.categoryId = "61dba35b-4f02-45c5-b648-c6badc0cbd79". En este ejemplo se usa el tipo QueryDefinition y una expresión de consulta parametrizada para el filtro de clave de partición. Una vez definida la consulta, llame a Container.GetItemQueryIterator<> para obtener un iterador de resultados que administrará las páginas de resultados. A continuación, use una combinación de los bucles while y foreach para recuperar páginas de resultados y, a continuación, iterar por los elementos individuales.

// Create query using a SQL string and parameters
var query = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.categoryId = @categoryId"
)
    .WithParameter("@categoryId", "61dba35b-4f02-45c5-b648-c6badc0cbd79");

using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);

while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

Ejecución del código

Esta aplicación crea un contenedor y una base de datos de API para NoSQL. A continuación, el ejemplo crea un elemento y luego lee el mismo elemento exactamente. Por último, el ejemplo emite una consulta que solo debe devolver ese único elemento. Con cada paso, el ejemplo genera metadatos en la consola sobre los pasos que ha realizado.

Para ejecutar la aplicación, use un terminal para ir al directorio de la aplicación y ejecutarla.

dotnet run

La salida de la aplicación debe ser similar a este ejemplo:

New database:   adventureworks
New container:  products
Created item:   68719518391     [gear-surf-surfboards]

Limpieza de recursos

Cuando ya no necesite la cuenta de la API para NoSQL, puede eliminar el grupo de recursos correspondiente.

Portal

1. Vaya al grupo de recursos que creó anteriormente en Azure Portal.

   Sugerencia

   En este inicio rápido, se recomienda el nombre msdocs-cosmos-quickstart-rg.

2. Seleccione Eliminar grupo de recursos.

   

3. En el cuadro de diálogo ¿Seguro que desea eliminar?, escriba el nombre del grupo de recursos y seleccione Eliminar.

   

CLI de Azure

Use el comando az group delete para eliminar el grupo de recursos.

az group delete --name $resourceGroupName

PowerShell

Use el cmdlet Remove-AzResourceGroup para eliminar el grupo de recursos.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Pasos siguientes

En este inicio rápido, ha aprendido a crear una cuenta de Azure Cosmos DB for NoSQL, a crear una base de datos y a crear un contenedor mediante el SDK de .NET. Ahora puede profundizar más en un tutorial en el que se administran los recursos y los datos de Azure Cosmos DB for NoSQL mediante una aplicación de consola de .NET.

Tutorial: Desarrollo de una aplicación de consola de .NET con Azure Cosmos DB for NoSQL