Avvio rapido: Azure Cosmos DB for Table per .NET
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. Si apprenderà come creare tabelle, righe ed eseguire attività di base all'interno della risorsa di Azure Cosmos DB usando 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 Azure Developer CLI (azd) per creare un account Azure Cosmos DB per Table e implementare 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 entitlement di archiviazione e ore di core senza costi. Per altre informazioni, vedere l'articolo sullo spazio di archiviazione e le ore di core inclusi per gli account GitHub.
Aprire un terminale nella directory radice del progetto.
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
Usare
azd init
per inizializzare il progetto.azd init
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 questo avvio rapido è consigliabile usare
msdocs-cosmos-db
.Distribuire l'account Azure Cosmos DB usando
azd up
. I modelli Bicep distribuiscono anche un'applicazione Web di esempio.azd up
Durante il processo di provisioning, selezionare la sottoscrizione e la posizione desiderata. Attendere il completamento del processo di provisioning. Per il processo sono necessari circa 5 minuti.
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.
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
.
Aprire un terminale e passare alla cartella
/src/web
:cd ./src/web
Se non è già installato, installare il pacchetto
Azure.Data.Tables
usandodotnet add package
.dotnet add package Azure.Data.Tables
Installare anche il pacchetto
Azure.Identity
se non è già stato fatto.dotnet add package Azure.Identity
Aprire ed esaminare il file src/web/Cosmos.Samples.Table.Quickstart.Web.csproj per verificare che le voci
Microsoft.Azure.Cosmos
eAzure.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, usare l'API seguente per le classi Table:
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 TableServiceClient
classe usando il costruttore e Environment.GetEnvironmentVariable
leggere le credenziali.
// 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
. Creare una nuova tabella se non esiste già usando il TableClient.CreateIfNotExistsAsync
metodo in TableClient
. Questo metodo restituisce 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 TableClient.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. L'esempio, infine, crea un secondo elemento ed esegue quindi una query che deve restituire più elementi. Con ogni passaggio, l'esempio restituisce i metadati nella console sui passaggi eseguiti.
Per eseguire l'app, usare un terminale per passare alla directory dell'applicazione ed 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.
Usare il comando az group delete
per eliminare il gruppo di risorse.
az group delete --name $resourceGroupName
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.