Introduzione ad Azure Cosmos DB for NoSQL con Python

  • Articolo

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

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. Esistono tre modi per connettersi a un account API for NoSQL usando la classe CosmosClient:

Connettersi con un endpoint e una chiave

Il costruttore per CosmosClient ha due parametri obbligatori:

Parametro Valore di esempio Descrizione
url La variabile di ambiente COSMOS_ENDPOINT Endpoint API for NoSQL da usare per tutte le richieste.
credential La variabile di ambiente COSMOS_KEY Chiave dell'account o token della risorsa da usare per l'autenticazione.

Recuperare l'endpoint e la chiave dell'account

  1. Creare una variabile della shell per resourceGroupName.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-python-howto-rg"

  2. Usare il comando az cosmosdb list per recuperare il nome del primo account Azure Cosmos DB nel gruppo di risorse e archiviarlo nella variabile della shell accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  3. Ottenere l'URI dell'endpoint API for NoSQL per l'account usando il comando az cosmosdb show.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

  4. Trovare il valore della CHIAVE PRIMARIA nell'elenco di chiavi per l'account con il comando az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  5. Registrare i valori di URI e CHIAVE PRIMARIA. Queste credenziali saranno necessarie più avanti.

Per usare i valori di URI e CHIAVE PRIMARIA all'interno del codice Python, salvarli in modo permanente in nuove variabili di ambiente nel computer locale che esegue l'applicazione.

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Creare CosmosClient con l'endpoint e la chiave dell'account

Creare una nuova istanza della classe CosmosClient con le variabili di ambiente COSMOS_ENDPOINT e COSMOS_KEY come parametri.

ENDPOINT = os.environ["COSMOS_ENDPOINT"]
KEY = os.environ["COSMOS_KEY"]

client = CosmosClient(url=ENDPOINT, credential=KEY)

Connettersi con una stringa di connessione

La classe CosmosClient include un metodo from_connection_string che è possibile usare per connettersi con un parametro obbligatorio:

Parametro Valore di esempio Descrizione
conn_str La variabile di ambiente COSMOS_CONNECTION_STRING Stringa di connessione all'account API for NoSQL.
credential La variabile di ambiente COSMOS_KEY Chiave dell'account o token della risorsa alternativo facoltativo da usare anziché quello nella stringa di connessione.

Recuperare la stringa di connessione dell'account

  1. Usare il comando az cosmosdb list per recuperare il nome del primo account Azure Cosmos DB nel gruppo di risorse e archiviarlo nella variabile della shell accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  2. Eseguire il comando az-cosmosdb-keys-list per trovare il valore di STRINGA DI CONNESSIONE PRIMARIA dall'elenco delle stringhe di connessione per l'account.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

Per usare il valore di STRINGA DI CONNESSIONE PRIMARIA all'interno del codice Python, salvarlo in modo permanente in una nuova variabile di ambiente nel computer locale che esegue l'applicazione.

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Creare CosmosClient con la stringa di connessione

Creare una nuova istanza della classe CosmosClient con la variabile di ambiente COSMOS_CONNECTION_STRING come unico parametro.

CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]

client = CosmosClient.from_connection_string(conn_str=CONN_STR)

Connettersi usando Microsoft Identity Platform

Per connettersi all'account API for NoSQL usando Microsoft Identity Platform e Microsoft Entra ID, usare un'entità di sicurezza. Il tipo esatto di entità di sicurezza dipenderà dalla posizione in cui è ospitato il codice dell'applicazione. La tabella seguente è una guida di riferimento rapido.

Posizione di esecuzione dell'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 a cui connettersi come illustrato nella sezione precedente per Connettersi con un endpoint e una chiave e impostarlo come variabile di ambiente COSMOS_ENDPOINT.

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

Creare CosmosClient con implementazione delle credenziali personalizzate

Se si prevede di distribuire l'applicazione all'esterno di Azure, è possibile ottenere un token OAuth usando altre classi nella libreria client Azure.Identity per Python. Anche queste altre classi derivano dalla classe TokenCredential.

Per questo esempio viene creata un'istanza di ClientSecretCredential usando gli identificatori di client e tenant, insieme a un segreto client.

In app.py:

  • Ottenere le informazioni sulle credenziali dalle variabili di ambiente per un'entità servizio. È possibile ottenere l'ID client, l'ID tenant e il segreto client quando si registra un'applicazione in Microsoft Entra ID. Per altre informazioni sulla registrazione di applicazioni Microsoft Entra, vedere Registrare un'applicazione con Microsoft Identity Platform.

  • Importare ClientSecretCredential e creare un'istanza con le variabili di ambiente TENANT_ID, CLIENT_ID e CLIENT_SECRET come parametri.

  • Creare una nuova istanza della classe CosmosClient con ENDPOINT e credential come parametri.

from azure.identity import ClientSecretCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]
TENANT_ID = os.environ["TENANT_ID"]
CLIENT_ID = os.environ["CLIENT_ID"]
CLIENT_SECRET = os.environ["CLIENT_SECRET"]

credential = ClientSecretCredential(
    tenant_id=TENANT_ID, client_id=CLIENT_ID, client_secret=CLIENT_SECRET
)

client = CosmosClient(ENDPOINT, credential)

Compilare l'applicazione

Durante la compilazione dell'applicazione, il codice interagirà essenzialmente con due tipi di risorse:

  • L'account dell'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 includono un set di singoli elementi dell'account.

  • Elementi, che rappresentano un documento JSON nel contenitore.

Il diagramma seguente mostra la relazione tra queste risorse.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

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

Vedi anche

Passaggi successivi

Dopo aver eseguito la connessione a un account API for NoSQL, passare alla guida successiva per creare e gestire i database.

Creare un database in Azure Cosmos DB for NoSQL con Python