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
- 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 --versionpara comprobar que el SDK de .NET es de la versión 6.0 o posterior. - Ejecute
az --version(CLI de Azure) oGet-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.
Inicie sesión en Azure Portal.
En el menú de Azure Portal o en la página principal, seleccione Crear un recurso.
En la página Nuevos, busque y seleccione Azure Cosmos DB.
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.
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.
Seleccione Revisar + crear.
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.
Seleccione Ir al recurso para ir a la página de la cuenta de Azure Cosmos DB.
En la página de la cuenta de la API para NoSQL, seleccione la opción del menú de navegación Claves.
Registre los valores de los campos URI y CLAVE PRINCIPAL. Usará estos valores en un paso posterior.
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 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 bucleforeach.
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 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.
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.Seleccione Eliminar grupo de recursos.
En el cuadro de diálogo ¿Seguro que desea eliminar?, escriba el nombre del grupo de recursos y seleccione Eliminar.
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.