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

SE APLICA A: NoSQL

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

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.

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.

    Captura de pantalla de la página de selección de opciones de API para Azure Cosmos DB.

  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.

    Captura de pantalla de una nueva página de cuenta para la API para NoSQL.

  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.

    Captura de pantalla de la página de implementación de un recurso de API para NoSQL.

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

    Captura de pantalla de una página de la cuenta de la API para NoSQL. La opción Claves está resaltada en el menú de navegación.

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

    Captura de pantalla de la página Claves con varias credenciales para una cuenta de la API para NoSQL.

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:

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env: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 de la jerarquía de Azure Cosmos DB que incluye 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

El código de ejemplo descrito en este artículo crea una base de datos denominada cosmicworks, 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

Deben autorizarse las solicitudes de aplicación a la mayor parte de servicios de Azure. El uso de la clase DefaultAzureCredential que proporciona la biblioteca cliente de Azure Identity es el enfoque recomendado para implementar conexiones sin contraseña a los servicios de Azure en el código.

También puede autorizar directamente las solicitudes a los servicios de Azure mediante contraseñas, cadenas de conexión u otras credenciales. Sin embargo, este enfoque debe usarse con precaución. Los desarrolladores deben ser meticulosos y no exponer nunca estos secretos en una ubicación que no sea segura. Cualquier persona que obtenga acceso a la contraseña o a la clave secreta puede autenticarse. DefaultAzureCredential ofrece ventajas de seguridad y administración mejoradas con respecto la clave de cuenta para permitir la autenticación sin contraseña. Ambas opciones se muestran en el ejemplo siguiente.

DefaultAzureCredential es una clase proporcionada por la biblioteca cliente de Azure Identity para .NET. Para más información sobre DefaultAzureCredential, consulte la información general sobre DefaultAzureCredential. DefaultAzureCredential admite varios métodos de autenticación y determina el que se debe usar en tiempo de ejecución. Este enfoque permite que la aplicación use diferentes métodos de autenticación en distintos entornos (local frente a producción) sin implementar código específico del entorno.

Por ejemplo, la aplicación puede autenticarse con las credenciales de inicio de sesión de Visual Studio cuando se trabaja en un desarrollo localmente y, después, usar una identidad administrada tras haberse implementado en Azure. No se necesitan cambios de código para esta transición.

Al desarrollar localmente con autenticación sin contraseña, asegúrese de que a la cuenta de usuario que se conecta a Cosmos DB se le asigna un rol con los permisos correctos para realizar operaciones de datos. Actualmente, Azure Cosmos DB for NoSQL no incluye roles integrados para las operaciones de datos, pero puede crear el suyo propio mediante la CLI de Azure o PowerShell.

Los roles constan de una colección de permisos o acciones que un usuario puede realizar, como lectura, escritura y eliminación. Puede obtener más información sobre cómo configurar el control de acceso basado en roles (RBAC) en la documentación de configuración de seguridad de Cosmos.

Creación del rol personalizado

Cree los roles con el comando az role definition create. Pase el nombre de la cuenta y el grupo de recursos de Cosmos DB, seguido de un cuerpo de JSON que defina el rol personalizado. En el ejemplo siguiente se crea un rol denominado PasswordlessReadWrite con permisos para leer y escribir elementos en contenedores de Cosmos DB. El rol también tiene como ámbito el nivel de cuenta mediante /.

az cosmosdb sql role definition create 
    --account-name passwordlessnosql
    --resource-group  passwordlesstesting 
    --body '{
    "RoleName": "PasswordlessReadWrite",
    "Type": "CustomRole",
    "AssignableScopes": ["/"],
    "Permissions": [{
        "DataActions": [
            "Microsoft.DocumentDB/databaseAccounts/readMetadata",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"
        ]
    }]
}'

Cuando se complete el comando, copie el valor de identificador del campo name y péguelo en algún lugar para su uso posterior.

A continuación, asigne el rol que creó a la cuenta de usuario o a la entidad de servicio que se conectará a Cosmos DB. Durante el desarrollo local, generalmente será su propia cuenta que haya iniciado sesión en Visual Studio o en la CLI de Azure.

Recupere los detalles de su cuenta mediante el comando az ad user.

az ad user --id "<your-email-address>"

Copie el valor de la propiedad id fuera de los resultados y péguelo en algún lugar para su uso posterior.

Por último, asigne el rol personalizado que creó a la cuenta de usuario mediante el comando az cosmosdb sql role assignment create y los identificadores que copió anteriormente.

az cosmosdb sql role assignment create 
    --account-name msdocs-cosmos-nosql
    --resource-group msdocs
    --scope "/" 
    --principal-id <your-user-id>
    --role-definition-id <your-custom-role-id> 

Autenticación con DefaultAzureCredential

Asegúrese de que esté autenticado con la misma cuenta de Azure AD a la que asignó el rol. Puede autenticarse a través de la CLI de Azure, Visual Studio o Azure PowerShell.

Inicie sesión en Azure a través de la CLI de Azure mediante el siguiente comando:

az login

Puede autenticarse en Cosmos DB for NoSQL mediante DefaultAzureCredential agregando el paquete NuGet Azure.Identity a la aplicación. DefaultAzureCredential detectará y usará automáticamente la cuenta con la que ha iniciado sesión en el paso anterior.

dotnet add package Azure.Identity

Desde el directorio del proyecto, abra el archivo Program.cs. En el editor, agregue mediante directivas para los espacios de nombres Microsoft.Azure.Cosmos y Azure.Identity.

using Microsoft.Azure.Cosmos;
using Azure.Identity;

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

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

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.

Creación y consulta de una base de datos

A continuación, creará una base de datos y un contenedor para almacenar productos y realizará consultas para insertar y leer esos elementos.

Las bibliotecas cliente Microsoft.Azure.Cosmos permiten realizar operaciones de datos mediante Azure RBAC. Sin embargo, para autenticar las operaciones de administración, como crear y eliminar bases de datos, debe usar RBAC a través de una de las siguientes opciones:

En este ejemplo se usa el enfoque de la CLI de Azure. Use los comandos az cosmosdb sql database create y az cosmosdb sql container create para crear un contenedor y una base de datos Cosmos DB for NoSQL.

# Create a SQL API database
az cosmosdb sql database create 
    --account-name msdocs-cosmos-nosql
    --resource-group msdocs
    --name cosmicworks

# Create a SQL API container
az cosmosdb sql container create
    --account-name msdocs-cosmos-nosql 
    --resource-group msdocs
    --database-name cosmicworks
    --name products

Una vez creados los recursos, use clases de las bibliotecas cliente Microsoft.Azure.Cosmos para conectarse a la base de datos y consultarla.

Obtención de la base de datos

Use el método CosmosClient.GetDatabase devolverá una referencia a la base de datos especificada.

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

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

Obtención del contenedor

Database.GetContainer devolverá una referencia al contenedor especificado.

// Container reference with creation if it does not alredy exist
Container container = database.GetContainer(id: "products");

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

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.

  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.

    Captura de pantalla de la opción Eliminar grupo de recursos de la barra de navegación de un grupo de recursos.

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

    Captura de pantalla de la página de confirmación de la eliminación de un grupo de recursos.

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.