Introducción a Azure Cosmos DB for Table con .NET

SE APLICA A: Table

En este artículo se muestra cómo conectarse a Azure Cosmos DB for Table mediante el SDK de .NET. Una vez conectado, puede realizar operaciones en tablas y elementos.

Package (NuGet) | Muestras | Referencia API | código fuente de biblioteca | Hacer comentarios |

Prerrequisitos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
• Cuenta de Azure Cosmos DB for Table. Creación de una API para una cuenta de Table.
• .NET 6.0 o versión posterior
• Interfaz de la línea de comandos (CLI) de Azure o Azure PowerShell

Configurar su proyecto

Creación de la aplicación de consola .NET

Cree una nueva aplicación .NET mediante el comando dotnet new con la plantilla console.

dotnet new console

Importe el paquete NuGet Azure.Data.Tables mediante el comando dotnet add package.

dotnet add package Azure.Data.Tables

Compile el proyecto con el comando dotnet build.

dotnet build

Conexión a Azure Cosmos DB for Table

Para conectarse a la API de Table de Azure Cosmos DB, cree una instancia de la clase TableServiceClient. Esta clase es el punto inicial para realizar todas las operaciones en tablas. Hay dos maneras principales de conectarse a una cuenta de la API de Table mediante la clase TableServiceClient:

• Conexión con una cadena de conexión de la API de Table

Conexión con una cadena de conexión

El constructor más común para TableServiceClient tiene un único parámetro:

Parámetro	Valor de ejemplo	Descripción
connectionString	La variable de entorno COSMOS_CONNECTION_STRING	Cadena de conexión a la cuenta de la API de Table

Recuperación de la cadena de conexión de la cuenta

CLI de Azure

1. Use el comando az cosmosdb list para recuperar el nombre de la primera cuenta de Azure Cosmos DB del grupo de recursos y almacenarlo en la variable de shell accountName.

   # Retrieve most recently created account name
   accountName=$(
       az cosmosdb list \
           --resource-group $resourceGroupName \
           --query "[0].name" \
           --output tsv
   )
   

2. Busque la CADENA DE CONEXIÓN PRINCIPAL en la lista de cadenas de conexión para la cuenta con el comando az-cosmosdb-keys-list.

   az cosmosdb keys list \
       --resource-group $resourceGroupName \
       --name $accountName \
       --type "connection-strings" \
       --query "connectionStrings[?description == \`Primary Table Connection String\`] | [0].connectionString"
   

PowerShell

1. Use el cmdlet Get-AzCosmosDBAccount para recuperar el nombre de la primera cuenta de Azure Cosmos DB del grupo de recursos y almacenarlo en la variable de shell ACCOUNT_NAME.

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

2. Busque la CADENA DE CONEXIÓN PRINCIPAL en la lista de cadenas de conexión para la cuenta con el cmdlet Get-AzCosmosDBAccountKey.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary Table Connection String" -First 1    
   

Para usar el valor de CADENA DE CONEXIÓN PRINCIPAL en el código .NET, consérvelo en una nueva variable de entorno del equipo local que ejecuta la aplicación.

Windows

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Linux/macOS

export COSMOS_CONNECTION_STRING="<cosmos-account-PRIMARY-CONNECTION-STRING>"

Creación de TableServiceClient con una cadena de conexión

Cree una nueva instancia de la clase TableServiceClient con la variable de entorno COSMOS_CONNECTION_STRING como el único parámetro.

// New instance of TableServiceClient class using a connection string
TableServiceClient client = new(
    connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);

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 Table, que es el espacio de nombres único de nivel superior para los datos de Azure Cosmos DB.

• Tablas, que contienen un conjunto de elementos individuales en la cuenta.

• Elementos, que representan un elemento individual de la tabla.

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 tablas secundarios. Uno de los nodos de tablas incluye dos elementos secundarios.

Cada tipo de recurso se representa mediante una o varias clases .NET o interfaces asociadas. A continuación, se muestra una lista de los tipos más comunes:

Clase	Descripción
TableServiceClient	Esta clase de cliente 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.
TableClient	Esta clase de cliente es una referencia a una tabla que podría existir ya o no en el servicio. La tabla se valida en el lado servidor al intentar acceder a ella o realizar alguna una operación en ella.
ITableEntity	Esta interfaz es la interfaz base de los elementos creados en la tabla o consultados desde la tabla. Esta interfaz incluye todas las propiedades necesarias para los elementos de la API de Table.
TableEntity	Esta clase es una implementación genérica de la interfaz ITableEntity como diccionario de pares clave-valor.

En las siguientes guías se muestra cómo usar cada una de estas clases para compilar la aplicación.

Guía	Descripción
de una tabla	Crear tablas.
Creación de un elemento	Creación de elementos
Lectura de un elemento	Lectura de elementos

Consulte también

• Paquete (NuGet)
• Muestras
• Referencia de las API
• Código fuente de la biblioteca
• Envíenos sus comentarios

Pasos siguientes

Ahora que se ha conectado a una cuenta de la API para Table, use la siguiente guía para crear y administrar tablas.

Creación de una tabla en Azure Cosmos DB for Table mediante .NET