Introduzione ad Azure Cosmos DB for Table tramite .NET

Articolo
03/25/2024

SI APPLICA A: Tabella

Questo articolo illustra come connettersi ad Azure Cosmos DB for Table usando .NET SDK. Una volta stabilita la connessione, è possibile eseguire operazioni su tabelle ed elementi.

Prerequisiti

Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
Account di Azure Cosmos DB for Table. Creare un'API per l'account Table.
.NET 6.0 o versioni successive
Interfaccia della riga di comando di Azure o Azure PowerShell

Impostare il progetto

Creare l'applicazione console .NET

Creare una nuova applicazione .NET usando il comando dotnet new con il modello di console.

dotnet new console

Importare il pacchetto NuGet Azure.Data.Tables usando il comando dotnet add package.

dotnet add package Azure.Data.Tables

Creare il progetto con il comando dotnet build.

dotnet build

Connettersi ad Azure Cosmos DB for Table

Per connettersi all'API for Table di Azure Cosmos DB, creare un'istanza della classe TableServiceClient. Questa classe è il punto di partenza per eseguire qualsiasi operazione sulle tabelle. Esistono essenzialmente due modi per connettersi a un account dell'API per Table usando la classe TableServiceClient:

Connettersi con una stringa di connessione dell'API per Table

Connettersi con una stringa di connessione

Il costruttore più comune per TableServiceClient ha un singolo parametro:

Parametro	Valore di esempio	Descrizione
`connectionString`	La variabile di ambiente `COSMOS_CONNECTION_STRING`	Stringa di connessione all'account dell'API per Table

Recuperare la stringa di connessione dell'account

Interfaccia della riga di comando di Azure
PowerShell

Usare il comando az cosmosdb list per recuperare il nome del primo account Azure Cosmos DB nel gruppo di risorse e archiviarlo nella variabile della shell accountName.

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

Eseguire il cmdlet az-cosmosdb-keys-list per trovare il valore di PRIMARY CONNECTION STRING dall'elenco delle stringhe di connessione per l'account.

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

Usare il cmdlet Get-AzCosmosDBAccount per recuperare il nome del primo account Azure Cosmos DB nel gruppo di risorse e archiviarlo nella variabile della 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

Eseguire il cmdlet Get-AzCosmosDBAccountKey per trovare il valore di PRIMARY CONNECTION STRING dall'elenco delle stringhe di connessione per l'account.

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

Per usare il valore di PRIMARY CONNECTION STRING all'interno del codice .NET, salvarlo in modo permanente in una nuova variabile di ambiente nel computer locale che esegue l'applicazione.

Windows
Linux/macOS

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

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

Creare TableServiceClient con la stringa di connessione

Creare una nuova istanza della classe TableServiceClient con la variabile di ambiente COSMOS_CONNECTION_STRING come unico parametro.

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

Compilare l'applicazione

Durante la compilazione dell'applicazione, il codice interagirà essenzialmente con due tipi di risorse:

L'account dell'API per Table, ovvero lo spazio dei nomi di primo livello univoco per i dati di Azure Cosmos DB.
Tabelle, che contengono un set di singoli elementi dell'account.
Elementi, che rappresentano un singolo elemento della tabella.

Il diagramma seguente mostra la relazione tra queste risorse.

Diagramma della gerarchia di Azure Cosmos DB, inclusi account, tabelle ed elementi.

Ogni tipo di risorsa è rappresentato da una o più classi o interfacce .NET associate. Ecco un elenco dei tipi più comuni:

Classe	Descrizione
`TableServiceClient`	Questa classe client fornisce una rappresentazione logica lato client per il servizio Azure Cosmos DB. L'oggetto client viene usato per configurare ed eseguire richieste nel servizio.
`TableClient`	Questa classe client è un riferimento a una tabella che può esistere o meno nel servizio. La tabella viene convalidata sul lato server quando si tenta di accedervi o di eseguire un'operazione su di essa.
`ITableEntity`	Questa interfaccia è l'interfaccia di base per tutti gli elementi creati nella tabella o sottoposti a query dalla tabella. Questa interfaccia include tutte le proprietà necessarie per gli elementi nell'API per Table.
`TableEntity`	Questa classe è un'implementazione generica dell'interfaccia `ITableEntity` come dizionario di coppie chiave-valore.

Nelle guide seguenti viene illustrato come usare ognuna di queste classi per compilare l'applicazione.

Guida	Descrizione
Crea una tabella	Creare tabelle
Creare un elemento	Creare elementi
Leggere un elemento	Leggere gli elementi

Vedi anche

Passaggi successivi

Dopo aver eseguito la connessione a un account dell'API per Table, passare alla guida successiva per creare e gestire tabelle.

Creare una tabella in Azure Cosmos DB for Table tramite .NET

Condividi tramite