Introdução ao Azure Cosmos DB for Table usando o .NET

Artigo
06/13/2024

APLICA-SE A: Tabela

Este artigo mostra como se conectar ao Azure Cosmos DB for Table usando o SDK do .NET. Uma vez conectado, você pode executar operações em tabelas e itens.

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Azure Cosmos DB para conta de tabela. Crie uma API para a conta Table.
.NET 6.0 ou posterior
Interface de Linha de Comando (CLI) do Azure ou Azure PowerShell

Configure o seu projeto

Criar o aplicativo de console .NET

Crie um novo aplicativo .NET usando o dotnet new comando com o modelo de console .

dotnet new console

Importe o pacote NuGet Azure.Data.Tables usando o dotnet add package comando.

dotnet add package Azure.Data.Tables

Crie o projeto com o dotnet build comando.

dotnet build

Conectar-se ao Azure Cosmos DB para Tabela

Para se conectar à API da Tabela do Azure Cosmos DB, crie uma instância da TableServiceClient classe. Esta classe é o ponto de partida para executar todas as operações em tabelas. Há duas maneiras principais de se conectar a uma API para conta Table usando a classe TableServiceClient :

Conectar-se com uma API para cadeia de conexão Table

Conectar-se com uma cadeia de conexão

O construtor mais comum para TableServiceClient tem um único parâmetro:

Parâmetro	Valor de exemplo	Description
`connectionString`	`COSMOS_CONNECTION_STRING` variável de ambiente	Cadeia de conexão com a API para a conta Table

Recuperar a cadeia de conexão da sua conta

CLI do Azure
PowerShell

Use o az cosmosdb list comando para recuperar o nome da primeira conta do Azure Cosmos DB em seu grupo de recursos e armazená-lo na variável de shell accountName .

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

Encontre a CADEIA DE CONEXÃO PRIMÁRIA na lista de cadeias de conexão da conta com o az-cosmosdb-keys-list comando.

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

Use o Get-AzCosmosDBAccount cmdlet para recuperar o nome da primeira conta do Azure Cosmos DB em seu grupo de recursos e armazená-lo na variável 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

Encontre a CADEIA DE CONEXÃO PRIMÁRIA na lista de cadeias de conexão da conta com o Get-AzCosmosDBAccountKey cmdlet.

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

Para usar o valor PRIMARY CONNECTION STRING dentro do seu código .NET, persista-o para uma nova variável de ambiente na máquina local que executa o aplicativo.

Windows
Linux / macOS

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

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

Criar TableServiceClient com cadeia de conexão

Crie uma nova instância da classe TableServiceClient com a COSMOS_CONNECTION_STRING variável de ambiente como o único parâmetro.

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

Compilar a aplicação

À medida que você cria seu aplicativo, seu código interage principalmente com quatro tipos de recursos:

A conta API for Table, que é o namespace de nível superior exclusivo para seus dados do Azure Cosmos DB.
Tabelas, que contêm um conjunto de itens individuais na sua conta.
Itens, que representam um item individual na tabela.

O diagrama seguinte mostra a relação entre estes recursos.

Diagrama da hierarquia do Azure Cosmos DB, incluindo contas, tabelas e itens.

Cada tipo de recurso é representado por uma ou mais classes ou interfaces .NET associadas. Aqui está uma lista dos tipos mais comuns:

Classe	Description
`TableServiceClient`	Essa classe de cliente fornece uma representação lógica do lado do cliente para o serviço Azure Cosmos DB. O objeto cliente é usado para configurar e executar solicitações no serviço.
`TableClient`	Esta classe de cliente é uma referência a uma tabela que pode, ou não, existir no serviço ainda. A tabela é validada no lado do servidor quando você tenta acessá-la ou executar uma operação contra ela.
`ITableEntity`	Esta interface é a interface base para quaisquer itens que são criados na tabela ou consultados a partir da tabela. Essa interface inclui todas as propriedades necessárias para itens na API para Tabela.
`TableEntity`	Esta classe é uma implementação genérica da `ITableEntity` interface como um dicionário de pares chave-valor.

Os guias a seguir mostram como usar cada uma dessas classes para criar seu aplicativo.

Guia	Description
Criar uma tabela	Criar tabelas
Criar um item	Criar itens
Ler um item	Ler itens

Consulte também

Próximos passos

Agora que você se conectou a uma conta da API para Tabela, use o próximo guia para criar e gerenciar tabelas.

Criar uma tabela no Azure Cosmos DB for Table usando .NET

Partilhar via