Guida introduttiva: Libreria Azure Cosmos DB for NoSQL per .NET
SI APPLICA A: NoSQL
Introduzione alla libreria client di Azure Cosmos DB for NoSQL per .NET per eseguire query sui dati nei contenitori ed eseguire operazioni comuni su singoli elementi. Seguire questa procedura per distribuire una soluzione minima nell'ambiente usando Azure Developer CLI.
Documentazione di riferimento dell'API | Codice sorgente della libreria | Pacchetto (NuGet) | Azure Developer CLI
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 for NoSQL 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 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 --template cosmos-db-nosql-dotnet-quickstart
Nota
Questo avvio rapido usa il modello di archivio GitHub azure-samples/cosmos-db-nosql-dotnet-quickstart. Azure Developer CLI clonerà automaticamente questo progetto nel computer, se non è già presente.
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
Microsoft.Azure.Cosmos
usandodotnet add package
.dotnet add package Microsoft.Azure.Cosmos --version 3.*
Installare anche il pacchetto
Azure.Identity
se non lo è già.dotnet add package Azure.Identity --version 1.*
Aprire ed esaminare il file src/web/Cosmos.Samples.NoSQL.Quickstart.Web.csproj per verificare che le voci
Microsoft.Azure.Cosmos
eAzure.Identity
esistano entrambe.
Modello a oggetti
Nome | Descrizione |
---|---|
CosmosClient | Questa classe è la classe client primaria e viene usata per gestire i metadati o i database a livello di account. |
Database | Questa classe rappresenta un database all'interno dell'account. |
Container | Questa classe viene usata principalmente per eseguire operazioni di lettura, aggiornamento ed eliminazione sul contenitore o sugli elementi archiviati all'interno del contenitore. |
PartitionKey | Questa classe rappresenta una chiave di partizione logica. Questa classe è necessaria per molte operazioni e query comuni. |
Esempi di codice
- Autenticare il client
- Ottenere un database
- Ottenere un contenitore
- Creare un elemento
- Ottenere un elemento
- Eseguire query sugli elementi
Il codice di esempio nel modello usa un database denominato cosmicworks
e un contenitore denominato products
. Il contenitore products
contiene dettagli quali nome, categoria, quantità, identificatore univoco e flag di vendita per ogni prodotto. Il contenitore usa la proprietà /category
come chiave di partizione logica.
Autenticare il client
Le richieste dell'applicazione per la maggior parte dei servizi di Azure devono essere autorizzate. Usare il tipo DefaultAzureCredential
come metodo preferito per implementare una connessione senza password tra le applicazioni e Azure Cosmos DB for NoSQL. DefaultAzureCredential
supporta più metodi di autenticazione e determina il metodo da usare in fase di esecuzione.
Importante
È anche possibile autorizzare le richieste ai servizi di Azure usando direttamente password, stringhe di connessione o altre credenziali. Tuttavia, questo approccio deve essere usato con cautela. Gli sviluppatori devono essere diligenti per non esporre mai questi segreti in una posizione non sicura. Chiunque possa accedere alla password o alla chiave privata è in grado di eseguire l'autenticazione al servizio di database. DefaultAzureCredential
offre vantaggi di gestione e sicurezza migliorati rispetto alla chiave dell'account per consentire l'autenticazione senza password senza rischi di archiviazione delle chiavi.
Questo esempio crea una nuova istanza della classe CosmosClient
ed esegue l'autenticazione usando un'istanza di DefaultAzureCredential
.
DefaultAzureCredential credential = new();
CosmosClient client = new(
accountEndpoint: "<azure-cosmos-db-nosql-account-endpoint>",
tokenCredential: new DefaultAzureCredential()
);
Ottenere un database
Usare client.GetDatabase
per recuperare il database esistente denominato cosmicworks
.
Database database = client.GetDatabase("cosmicworks");
Ottenere un contenitore
Recuperare il contenitore products
esistente usando database.GetContainer
.
Container container = database.GetContainer("products");
Creare un elemento
Creare un tipo di record C# con tutti i membri da serializzare in JSON. In questo esempio il tipo ha un identificatore univoco e i campi per categoria, nome, quantità, prezzo e vendita.
public record Product(
string id,
string category,
string name,
int quantity,
decimal price,
bool clearance
);
Creare un elemento nel contenitore usando container.UpsertItem
. Questo metodo esegue l'upsert dell'elemento, in pratica sostituendolo, se esiste già.
Product item = new(
id: "68719518391",
category: "gear-surf-surfboards",
name: "Yamba Surfboard",
quantity: 12,
price: 850.00m,
clearance: false
);
ItemResponse<Product> response = await container.UpsertItemAsync<Product>(
item: item,
partitionKey: new PartitionKey("gear-surf-surfboards")
);
Leggere un elemento
Eseguire un'operazione di lettura dei punti usando sia l'identificatore univoco (id
) che i campi chiave di partizione. Usare container.ReadItem
per recuperare in modo efficiente l'elemento specifico.
ItemResponse<Product> response = await container.ReadItemAsync<Product>(
id: "68719518391",
partitionKey: new PartitionKey("gear-surf-surfboards")
);
Eseguire query sugli elementi
Eseguire una query su più elementi in un contenitore usando container.GetItemQueryIterator
. Trovare tutti gli elementi all'interno di una categoria specificata usando questa query con parametri:
SELECT * FROM products p WHERE p.category = @category
string query = "SELECT * FROM products p WHERE p.category = @category"
var query = new QueryDefinition(query)
.WithParameter("@category", "gear-surf-surfboards");
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
queryDefinition: query
);
Analizzare i risultati impaginati della query eseguendo un ciclo in ogni pagina di risultati usando feed.ReadNextAsync
. Usare feed.HasMoreResults
per determinare se all'inizio di ogni ciclo sono rimasti risultati.
List<Product> items = new();
while (feed.HasMoreResults)
{
FeedResponse<Product> response = await feed.ReadNextAsync();
foreach (Product item in response)
{
items.Add(item);
}
}
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
In GitHub Codespaces eliminare lo spazio di codice in esecuzione per ottimizzare l'archiviazione e i diritti di core.