Introduzione ad Azure Cosmos DB for NoSQL con Python
SI APPLICA A: 
NoSQL
Questo articolo illustra come connettersi ad Azure Cosmos DB for NoSQL usando Python SDK. Una volta stabilita la connessione, è possibile eseguire operazioni su database, contenitori ed elementi.
Pacchetto (PyPi) | Esempi | Informazioni di riferimento sulle API | Codice sorgente della raccolta | Commenti e suggerimenti
Prerequisiti
- Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
- Account Azure Cosmos DB for NoSQL. Creare un account API for NoSQL.
- Python 3.7 o versione successiva
- Interfaccia della riga di comando di Azure o Azure PowerShell
Impostare il progetto
Creare un ambiente in cui è possibile eseguire il codice Python.
Con un ambiente virtuale, è possibile installare pacchetti Python in un ambiente isolato senza alcun impatto sul resto del sistema.
Installare Azure Cosmos DB for NoSQL Python SDK nell'ambiente virtuale.
pip install azure-cosmos
Creare un'applicazione Python
Nell'ambiente in uso creare un nuovo file app.py e aggiungervi il codice seguente:
import json
import os
import sys
import uuid
from azure.core.exceptions import AzureError
from azure.cosmos import CosmosClient, PartitionKey
Il codice precedente importa i moduli che verranno usati nel corso dell'articolo.
Connettersi ad Azure Cosmos DB for NoSQL
Per connettersi all'API for NoSQL di Azure Cosmos DB, creare un'istanza della classe CosmosClient. Questa classe è il punto di partenza per eseguire qualsiasi operazione sui database.
Per connettersi all'account API per NoSQL usando Microsoft Entra, usare un'entità di sicurezza. Il tipo esatto di entità di sicurezza dipenderà da dove viene ospitato il codice dell'applicazione. La tabella seguente funge da guida di riferimento rapido.
| Dove viene eseguita l'applicazione | Entità di sicurezza principale |
|---|---|
| Computer locale (sviluppo e test) | Identità utente o entità servizio |
| Azure | Identità gestita |
| Server o client esterni ad Azure | Entità servizio |
Importare Azure.Identity
Il pacchetto azure-identity contiene funzionalità di autenticazione di base condivise tra tutte le librerie di Azure SDK.
Importare il pacchetto azure-identity nell'ambiente.
pip install azure-identity
Creare CosmosClient con implementazione delle credenziali predefinite
Se si esegue il test in un computer locale o l'applicazione verrà eseguita nei servizi di Azure con supporto diretto per le identità gestite, ottenere un token OAuth creando un'istanza di DefaultAzureCredential.
In app.py:
Ottenere l'endpoint per connettersi all'account e impostarlo come variabile
COSMOS_ENDPOINTdi ambiente .Importare DefaultAzureCredential e crearne un'istanza.
Creare una nuova istanza della classe CosmosClient con ENDPOINT e credential come parametri.
from azure.identity import DefaultAzureCredential
ENDPOINT = os.environ["COSMOS_ENDPOINT"]
credential = DefaultAzureCredential()
client = CosmosClient(ENDPOINT, credential)
Importante
Per informazioni dettagliate su come aggiungere il ruolo corretto per il corretto funzionamento di DefaultAzureCredential, vedere Configurare il controllo degli accessi in base al ruolo con Microsoft Entra ID per l'account Azure Cosmos DB. In particolare, vedere la sezione sulla creazione di ruoli e l'assegnazione di tali ruoli a un ID entità di sicurezza.
Compilare l'applicazione
Durante la compilazione dell'applicazione, il codice interagirà principalmente con quattro tipi di risorse:
Account API for NoSQL, ovvero lo spazio dei nomi di primo livello univoco per i dati di Azure Cosmos DB.
Database, che organizzano i contenitori nell'account.
Contenitori, che contengono una serie di singoli elementi nel database.
Elementi, che rappresentano un documento JSON nel contenitore.
Il diagramma seguente mostra la relazione tra queste risorse.
Diagramma gerarchico che mostra al vertice un account di Azure Cosmos DB. L'account presenta due nodi database figlio. Uno dei nodi del database include due nodi contenitore figlio. L'altro nodo del database include un singolo nodo contenitore figlio. Tale nodo contenitore singolo ha tre nodi elemento figlio.
Ogni tipo di risorsa è rappresentato da una o più classi Python associate. Di seguito è riportato un elenco delle classi più comuni per la programmazione sincrona. Sono disponibili classi simili per la programmazione asincrona nello spazio dei nomi azure.cosmos.aio.
| Classe | Descrizione |
|---|---|
CosmosClient |
Questa classe fornisce una rappresentazione logica lato client per il servizio Azure Cosmos DB. L'oggetto client viene usato per configurare ed eseguire richieste nel servizio. |
DatabaseProxy |
Interfaccia a un database che può, o meno, essere già esistente nel servizio. Non è possibile creare direttamente un'istanza di questa classe. È invece consigliabile usare il metodo get_database_client di CosmosClient. |
ContainerProxy |
Interfaccia per interagire con un contenitore Cosmos DB specifico. Non è possibile creare direttamente un'istanza di questa classe. Usare invece il metodo get_container_client di DatabaseProxy per ottenere un contenitore esistente o il metodo create_container per creare un nuovo contenitore. |
Nelle guide seguenti viene illustrato come usare ognuna di queste classi per compilare l'applicazione.
| Guida | Descrizione |
|---|---|
| Creare un database | Creare database |
| Creare un contenitore | Crea contenitori |
| Esempi di elementi | Lettura di punti un elemento specifico |