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.

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 della gerarchia di Azure Cosmos DB, che include account, database, contenitori ed elementi.

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

Creare un database in Azure Cosmos DB for NoSQL con Python