Introducción a Azure Cosmos DB for NoSQL con .NET
SE APLICA A: 
NoSQL
En este artículo se muestra cómo conectarse a Azure Cosmos DB for NoSQL mediante el SDK de .NET. Una vez conectado, puede realizar operaciones en bases de datos, contenedores y elementos.
Package (NuGet) | Muestras | Referencia API | código fuente de biblioteca | Hacer comentarios
Requisitos previos
- Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
- Cuenta de Azure Cosmos DB for NoSQL. Creación de una API para una cuenta de NoSQL.
- .NET 6.0 o versión posterior
- Interfaz de la línea de comandos (CLI) de Azure o Azure PowerShell
Configurar su proyecto
Cree una nueva aplicación .NET mediante el comando dotnet new con la plantilla console.
dotnet new console
Importe el paquete de NuGet Microsoft.Azure.Cosmos mediante el comando dotnet add package.
dotnet add package Microsoft.Azure.Cosmos
Compile el proyecto con el comando dotnet build.
dotnet build
Conexión de Azure Cosmos DB for NoSQL
Para conectarse a la API de NoSQL de Azure Cosmos DB, cree una instancia de la clase CosmosClient. Esta clase es el punto inicial para realizar todas las operaciones en bases de datos.
Para conectarse a la API para la cuenta NoSQL mediante Microsoft Entra, use una entidad de seguridad. El tipo exacto de entidad de seguridad dependerá de dónde hospede el código de la aplicación. La tabla siguiente sirve como guía de referencia rápida.
| Dónde se ejecuta la aplicación | Entidad de seguridad |
|---|---|
| Máquina local (desarrollo y pruebas) | Identidad de usuario o entidad de servicio |
| Azure | Identidad administrada |
| Servidores o clientes fuera de Azure | Entidad de servicio |
Importación de Azure.Identity
El paquete NuGet Azure.Identity contiene la funcionalidad de autenticación principal que se comparte entre todas las bibliotecas del SDK de Azure.
Importe el paquete NuGet Azure.Identity mediante el comando dotnet add package.
dotnet add package Azure.Identity
Recompile el proyecto con el comando dotnet build.
dotnet build
En el editor de código, agregue mediante directivas para los espacios de nombres Azure.Core y Azure.Identity.
using Azure.Core;
using Azure.Identity;
Creación de CosmosClient con la implementación de credenciales predeterminada
Si está probando en una máquina local o la aplicación se va a ejecutar en servicios de Azure con compatibilidad directa con identidades administradas, obtenga un token de OAuth mediante la creación de una instancia de DefaultAzureCredential.
En este ejemplo, guardamos la instancia en una variable de tipo TokenCredential, ya que es un tipo más genérico que se puede reutilizar en los SDK.
// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();
Cree una nueva instancia de la clase CosmosClient con la variable de entorno COSMOS_ENDPOINT y el objeto TokenCredential como parámetros.
// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
tokenCredential: credential
);
Compilación de la aplicación
A medida que compile la aplicación, el código interactuará principalmente con cuatro tipos de recursos:
La cuenta de la API de NoSQL, que es el espacio de nombres único de nivel superior para los datos de Azure Cosmos DB.
Bases de datos, que organizan los contenedores de la cuenta.
Contenedores, que contienen un conjunto de elementos individuales en la base de datos.
Elementos, que representan un documento JSON en el contenedor.
En el siguiente diagrama se muestra la relación entre estos recursos.
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.
Cada tipo de recurso se representa mediante una o varias clases .NET asociadas. A continuación, se muestra una lista de las clases más comunes:
| Clase | Descripción |
|---|---|
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. |
Database |
Esta clase es una referencia a una base de datos que podría existir 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 servidor al intentar utilizarlo. |
En las siguientes guías se muestra cómo usar cada una de estas clases para compilar la aplicación.
| Guía | Descripción |
|---|---|
| Creación de una base de datos | Creación de bases de datos |
| Creación de un contenedor | Creación de contenedores |
| Lectura de un elemento | Lectura puntual de un elemento específico |
| Elementos de consulta | Consulta de varios elementos |
Consulte también
- Paquete (NuGet)
- Muestras
- Referencia de las API
- Código fuente de la biblioteca
- Envíenos sus comentarios