Condividi tramite

Guida introduttiva: Azure Cosmos DB per la libreria tabelle per .NET

  • Articolo

SI APPLICA A: Tabella

Questo avvio rapido illustra come iniziare a usare Azure Cosmos DB for Table da un'applicazione .NET. Azure Cosmos DB for Table è un archivio dati senza schema che consente alle applicazioni di archiviare dati di tabella strutturati nel cloud. Informazioni su come creare tabelle, righe ed eseguire attività di base all'interno della risorsa di Azure Cosmos DB usando Azure SDK per .NET

Documentazione di riferimento dell'API | Codice sorgente della libreria | Pacchetto (NuGet) | Azure Developer CLI

Prerequisiti

Inizializzare il progetto

Usare 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.

  1. Aprire un terminale in una directory vuota.

  2. Se non si è già autenticati, eseguire l'autenticazione all'interfaccia della riga di comando per sviluppatori di Azure 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 --template cosmos-db-table-dotnet-quickstart

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

  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, la località desiderata e il gruppo di risorse di destinazione. Attendere il completamento del processo di provisioning. Per il processo sono necessari circa 5 minuti.

  7. Al termine del provisioning delle risorse di Azure, nell'output viene incluso un 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.

    Screenshot dell'applicazione Web in esecuzione.

Installare la libreria client

La libreria client è disponibile tramite NuGet, come pacchetto Azure.Data.Tables.

  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. Aprire ed esaminare il file src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj per verificare che la Azure.Data.Tables voce esista.

Modello a oggetti

Nome Descrizione
TableServiceClient Questa classe è la classe client primaria e viene usata per gestire i metadati o i database a livello di account.
TableClient Questa classe rappresenta il client per una tabella all'interno dell'account.

Esempi di codice

Il codice di esempio nel modello usa una tabella denominata cosmicworks-products. La cosmicworks-products tabella contiene dettagli quali nome, categoria, quantità, prezzo, identificatore univoco e flag di vendita per ogni prodotto. Il contenitore usa un identificatore univoco* come chiave di riga e categoria come chiave di partizione.

Autenticare il client

In questo esempio viene creata una nuova istanza della TableServiceClient classe .

TableServiceClient serviceClient = new(
    endpoint: new Uri("<azure-cosmos-db-table-account-endpoint>"),
    credential
);

Ottenere una tabella

In questo esempio viene creata un'istanza della TableClient classe usando il GetTableClient metodo della TableServiceClient classe .

TableClient client = serviceClient.GetTableClient(
    tableName: "<azure-cosmos-db-table-name>"
);

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.

public record Product : ITableEntity
{
    public string RowKey { get; set; } = $"{Guid.NewGuid()}";

    public string PartitionKey { get; set; } = String.Empty;

    public string Name { get; set; } = String.Empty;

    public int Quantity { get; set; } = 0;

    public decimal Price { get; set; } = 0.0m;

    public bool Clearance { get; set; } = false;

    public ETag ETag { get; set; } = ETag.All;

    public DateTimeOffset? Timestamp { get; set; }
};

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

Product entity = new()
{
    RowKey = "68719518391",
    PartitionKey = "gear-surf-surfboards",
    Name = "Surfboard",
    Quantity = 10,
    Price = 300.00m,
    Clearance = true
};

Response response = await client.UpsertEntityAsync<Product>(
    entity: entity,
    mode: TableUpdateMode.Replace
);

Ottenere un elemento

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

Response<Product> response = await client.GetEntityAsync<Product>(
    rowKey: "68719518391",
    partitionKey: "gear-surf-surfboards"
);

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.

string category = "gear-surf-surfboards";

AsyncPageable<Product> results = client.QueryAsync<Product>(
    product => product.PartitionKey == category
);

Analizzare i risultati impaginati della query eseguendo un ciclo in ogni pagina di risultati usando un ciclo asincrono.

List<Product> entities = new();
await foreach (Product product in results)
{
    entities.Add(product);
}

Pulire le risorse

Quando l'applicazione o le risorse di esempio non sono più necessarie, rimuovere la distribuzione corrispondente e tutte le risorse.

azd down

Contenuto correlato