Avvio rapido: Azure Cosmos DB for Table per .NET

SI APPLICA A: Tabella

• .NET
• Java
• Node.js
• Python

Questo avvio rapido illustra come iniziare a usare Azure Cosmos DB for Table da un'applicazione .NET. Azure Cosmos DB per tabella è un archivio dati senza schema che consente alle applicazioni di archiviare dati strutturati della tabella nel cloud. Verrà spiegato come creare tabelle, righe ed eseguire attività di base all'interno della risorsa di Azure Cosmos DB utilizzando il Pacchetto Azure.Data.Tables (NuGet).

Nota

I frammenti di codice di esempio sono disponibili su GitHub come progetto .NET.

Documentazione di riferimento dell'API per Table | Pacchetto Azure.Data.Tables (NuGet)

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
• Account GitHub

• Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
• Azure Developer CLI
• Docker Desktop

Configurazione

Distribuire il contenitore di sviluppo di questo progetto nell'ambiente. Usare quindi l'interfaccia della riga di comando per sviluppatori di Azure (azd) per creare un account Azure Cosmos DB per tabelle e distribuire un'applicazione di esempio in contenitori. L'applicazione di esempio usa la libreria client per gestire, creare, leggere ed eseguire query sui dati di esempio.

Importante

Gli account GitHub includono un diritto di archiviazione e ore di core senza costi. Per altre informazioni, vedere le ore di archiviazione e i core inclusi per gli account GitHub.

1. Aprire un terminale nella directory radice del progetto.

2. Eseguire l'autenticazione in Azure Developer CLI usando azd auth login. Seguire i passaggi specificati dallo strumento per eseguire l'autenticazione all'interfaccia della riga di comando usando le credenziali di Azure preferite.

   azd auth login
   

3. Usare azd init per inizializzare il progetto.

   azd init
   

4. Durante l'inizializzazione, configurare un nome di ambiente univoco.

   Suggerimento

   Il nome dell'ambiente verrà usato anche come nome del gruppo di risorse di destinazione. Per questa guida di avvio rapido, usare msdocs-cosmos-db.

5. Distribuire l'account Azure Cosmos DB usando azd up. I modelli Bicep distribuiscono anche un'applicazione Web di esempio.

   azd up
   

6. Durante il processo di provisioning, selezionare la sottoscrizione e il percorso desiderato. Attendere il completamento del processo di provisioning. Per il processo sono necessari circa 5 minuti.

7. Una volta completato il provisioning delle risorse di Azure, nell'output viene incluso l'URL dell'applicazione Web in esecuzione.

   Deploying services (azd deploy)
   
     (✓) Done: Deploying service web
   - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
   
   SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
   

8. Usare l'URL nella console per passare all'applicazione Web nel browser. Osservare l'output dell'app in esecuzione.

   

Installare la libreria client

La libreria client è disponibile tramite NuGet, come pacchetto Microsoft.Azure.Cosmos.

1. Aprire un terminale e passare alla cartella /src/web:

   cd ./src/web
   

2. Se non è già installato, installare il pacchetto Azure.Data.Tables usando dotnet add package.

   dotnet add package Azure.Data.Tables
   

3. Installare anche il pacchetto Azure.Identity se non è già stato fatto.

   dotnet add package Azure.Identity
   

4. Aprire ed esaminare il file src/web/Cosmos.Samples.Table.Quickstart.Web.csproj per verificare che le Microsoft.Azure.Cosmos voci e Azure.Identity esistano entrambe.

Esempi di codice

• Autenticare il client
• Crea una tabella
• Creare un elemento
• Ottenere un elemento
• Eseguire query sugli elementi

Il codice di esempio descritto in questo articolo crea una tabella denominata adventureworks. Ogni riga della tabella contiene i dettagli di un prodotto come nome, categoria, quantità e indicatore di vendita. Ogni prodotto contiene inoltre un identificatore univoco.

Per interagire con queste risorse, si useranno le classi API Table seguenti:

• TableServiceClient - Questa classe fornisce metodi per eseguire operazioni a livello di servizio con Azure Cosmos DB for Table.
• TableClient - Questa classe consente di interagire con le tabelle ospitate nell'API per Table di Azure Cosmos DB.
• TableEntity - Questa classe è un riferimento a una riga di una tabella che consente di gestire le proprietà e i dati delle colonne.

Autenticare il client

Dalla directory del progetto aprire il file Program.cs. Nell'editor aggiungere una direttiva using per Azure.Data.Tables.

using Azure.Data.Tables;

Definire una nuova istanza della classe TableServiceClient utilizzando il costruttore e Environment.GetEnvironmentVariable per leggere la stringa di connessione impostata in precedenza.

// New instance of the TableClient class
TableServiceClient tableServiceClient = new TableServiceClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));

Crea una tabella

Recuperare un'istanza di TableClient usando la classe TableServiceClient. Utilizzare il metodo TableClient.CreateIfNotExistsAsync sul TableClient per creare una nuova tabella, se non esiste già. Questo metodo restituirà un riferimento alla tabella esistente o appena creata.

// New instance of TableClient class referencing the server-side table
TableClient tableClient = tableServiceClient.GetTableClient(
    tableName: "adventureworks"
);

await tableClient.CreateIfNotExistsAsync();

Creare un elemento

Il modo più semplice per creare un nuovo elemento in una tabella è quello di creare una classe che implementi l'interfaccia ITableEntity. È quindi possibile aggiungere proprietà personalizzate alla classe per popolare le colonne di dati in quella riga della tabella.

// C# record type for items in the table
public record Product : ITableEntity
{
    public string RowKey { get; set; } = default!;

    public string PartitionKey { get; set; } = default!;

    public string Name { get; init; } = default!;

    public int Quantity { get; init; }

    public bool Sale { get; init; }

    public ETag ETag { get; set; } = default!;

    public DateTimeOffset? Timestamp { get; set; } = default!;
}

Creare un elemento nella raccolta tramite la classe Product chiamando TableClient.AddEntityAsync<T>.

// Create new item using composite key constructor
var prod1 = new Product()
{
    RowKey = "68719518388",
    PartitionKey = "gear-surf-surfboards",
    Name = "Ocean Surfboard",
    Quantity = 8,
    Sale = true
};

// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(prod1);

Ottenere un elemento

È possibile recuperare un elemento specifico da una tabella usando il metodo TableEntity.GetEntityAsync<T>. Specificare partitionKey e rowKey come parametri per identificare la riga corretta su cui eseguire una rapida lettura diretta di tale elemento.

// Read a single item from container
var product = await tableClient.GetEntityAsync<Product>(
    rowKey: "68719518388",
    partitionKey: "gear-surf-surfboards"
);
Console.WriteLine("Single product:");
Console.WriteLine(product.Value.Name);

Eseguire query sugli elementi

Dopo aver inserito un elemento, è inoltre possibile eseguire una query per ottenere tutti gli elementi che corrispondono a un filtro specifico usando il metodo TableClient.Query<T>. Questo esempio filtra i prodotti per categoria utilizzando la sintassi Linq, che è un vantaggio di utilizzare modelli ITableEntity tipizzati come la classe Product.

Nota

È inoltre possibile eseguire query sugli elementi utilizzando la sintassi OData. È possibile vedere un esempio di questo approccio nell'esercitazione Esecuzione di query sui dati.

// Read multiple items from container
var prod2 = new Product()
{
    RowKey = "68719518390",
    PartitionKey = "gear-surf-surfboards",
    Name = "Sand Surfboard",
    Quantity = 5,
    Sale = false
};

await tableClient.AddEntityAsync<Product>(prod2);

var products = tableClient.Query<Product>(x => x.PartitionKey == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var item in products)
{
    Console.WriteLine(item.Name);
}

Eseguire il codice

Questa app crea una tabella API Table di Azure Cosmos DB. L'esempio crea quindi un elemento e successivamente rilegge esattamente lo stesso elemento. Infine, l'esempio crea un secondo elemento e quindi esegue una query che deve restituire più elementi. Ad ogni passaggio, l'esempio restituisce metadati alla console sui passaggi eseguiti.

Per eseguire l'app, utilizzare un terminale per accedere alla directory dell'applicazione e quindi eseguire l'applicazione.

dotnet run

L'output dell'app sarà simile a questo esempio:

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

Pulire le risorse

Quando l'account Azure Cosmos DB for Table non è più necessario, è possibile eliminare il gruppo di risorse corrispondente.

Interfaccia della riga di comando di Azure

Usare il comando az group delete per eliminare il gruppo di risorse.

az group delete --name $resourceGroupName

PowerShell

Usare il cmdlet Remove-AzResourceGroup per eliminare il gruppo di risorse.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Portale

1. Accedere al gruppo di risorse creato in precedenza nel portale di Azure.

   Suggerimento

   In questa guida introduttiva è stato consigliato il nome msdocs-cosmos-quickstart-rg.

2. Selezionare Elimina gruppo di risorse.

   

3. Nella finestra di dialogo Sei sicuro di voler eliminare immettere il nome del gruppo di risorse e quindi selezionare Elimina.

   

Passaggi successivi

In questa guida introduttiva si è appreso come creare un account Azure Cosmos DB for Table, creare una tabella e gestire le voci usando l'SDK .NET. È ora possibile approfondire l'SDK per apprendere come eseguire query e attività di gestione dei dati più avanzate nelle risorse di Azure Cosmos DB for Table.

Attività iniziali con Azure Cosmos DB for Table e .NET