Aan de slag met Azure Cosmos DB for NoSQL met behulp van Python

VAN TOEPASSING OP: NoSQL

In dit artikel leest u hoe u verbinding maakt met Azure Cosmos DB for NoSQL met behulp van de Python SDK. Zodra u verbinding hebt gemaakt, kunt u bewerkingen uitvoeren op databases, containers en items.

Pakket (PyPi) | Samples | API reference | Library source code | Give Feedback

Vereisten

• Een Azure-account met een actief abonnement. Gratis een account maken
• Azure Cosmos DB for NoSQL-account. Maak een API voor een NoSQL-account.
• Python 3.7 of hoger
• Azure-opdrachtregelinterface (CLI) of Azure PowerShell

Uw project instellen

Maak een omgeving waarin u Python-code kunt uitvoeren.

Virtuele omgeving

Met een virtuele omgeving kunt u Python-pakketten installeren in een geïsoleerde omgeving zonder dat dit van invloed is op de rest van uw systeem.

Installeer de Azure Cosmos DB for NoSQL Python SDK in de virtuele omgeving.

pip install azure-cosmos

Dev-container

Een dev-container is een vooraf geconfigureerde omgeving die u kunt gebruiken om Python-code uit te voeren.

Als u een dev-container wilt uitvoeren, kunt u het volgende gebruiken:

• Visual Studio Code: Kloon deze opslagplaats naar uw lokale computer en open de map met behulp van de extensie Dev-containers.

• GitHub Codespaces: Open deze opslagplaats in de browser met een GitHub-coderuimte.

Installeer de Azure Cosmos DB for NoSQL Python SDK in de dev-container.

pip install azure-cosmos

De Python-toepassing maken

Maak in uw omgeving een nieuw app.py-bestand en voeg de volgende code eraan toe:

import json
import os
import sys
import uuid

from azure.core.exceptions import AzureError
from azure.cosmos import CosmosClient, PartitionKey

Met de voorgaande code importeert u modules die u in de rest van het artikel gaat gebruiken.

Verbinding maken met Azure Cosmos DB for NoSQL

Als u verbinding wilt maken met de API voor NoSQL van Azure Cosmos DB, maakt u een exemplaar van de CosmosClient-klasse . Deze klasse is het startpunt om alle bewerkingen uit te voeren op databases. Er zijn drie manieren om verbinding te maken met een API voor NoSQL-account met behulp van de CosmosClient-klasse :

• Verbinding maken met een API voor NoSQL-eindpunt en een lees-/schrijfsleutel
• Verbinding maken met een API voor NoSQL-verbindingsreeks
• Verbinding maken met Microsoft Entra-id

Verbinding maken met een eindpunt en sleutel

De constructor voor CosmosClient heeft twee vereiste parameters:

Parameter	Voorbeeldwaarde	Beschrijving
url	COSMOS_ENDPOINT Omgevingsvariabele	API voor NoSQL-eindpunt voor alle aanvragen.
credential	COSMOS_KEY Omgevingsvariabele	Accountsleutel of resourcetoken dat moet worden gebruikt bij het verifiëren.

Uw accounteindpunt en -sleutel ophalen

Azure-CLI

1. Maak een shellvariabele voor resourceGroupName.

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

2. Gebruik de az cosmosdb list opdracht om de naam van het eerste Azure Cosmos DB-account in uw resourcegroep op te halen en op te slaan in de accountName-shellvariabele .

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

3. Haal de API voor NoSQL-eindpunt-URI voor het account op met behulp van de az cosmosdb show opdracht.

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

4. Zoek de PRIMAIRE SLEUTEL in de lijst met sleutels voor het account met de az-cosmosdb-keys-list opdracht.

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

5. Noteer de waarden voor de URI en PRIMAIRE SLEUTEL . U gebruikt deze referenties later.

Powershell

1. Maak een shellvariabele voor RESOURCE_GROUP_NAME.

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

2. Gebruik de Get-AzCosmosDBAccount cmdlet om de naam van het eerste Azure Cosmos DB-account in uw resourcegroep op te halen en op te slaan in de variabele ACCOUNT_NAME shell.

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

3. Haal de API voor NoSQL-eindpunt-URI voor het account op met behulp van de Get-AzCosmosDBAccount cmdlet.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
   }
   Get-AzCosmosDBAccount @parameters |
       Select-Object -Property "DocumentEndpoint"
   

4. Zoek de PRIMAIRE SLEUTEL in de lijst met sleutels voor het account met de Get-AzCosmosDBAccountKey cmdlet.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "Keys"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "PrimaryMasterKey"
   

5. Noteer de waarden voor de URI en PRIMAIRE SLEUTEL . U gebruikt deze referenties later.

Portal

Tip

Voor deze handleiding raden we u aan de naam msdocs-cosmos-python-howto-rgvan de resourcegroep te gebruiken.

1. Meld u aan bij het Azure-portaal.

2. Navigeer naar de bestaande azure Cosmos DB for NoSQL-accountpagina.

3. Selecteer op de azure Cosmos DB for NoSQL-accountpagina de optie Navigatiemenu Sleutels .

   

4. Noteer de waarden uit de velden URI en PRIMAIRE SLEUTEL . U gebruikt deze waarden in een latere stap.

   

Als u de URI - en PRIMAIRE SLEUTEL-waarden in uw Python-code wilt gebruiken, moet u deze behouden tot nieuwe omgevingsvariabelen op de lokale computer waarop de toepassing wordt uitgevoerd.

Windows

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

Linux/macOS

export COSMOS_ENDPOINT="<cosmos-account-URI>"
export COSMOS_KEY="<cosmos-account-PRIMARY-KEY>"

CosmosClient maken met accounteindpunt en -sleutel

Maak een nieuw exemplaar van de CosmosClient-klasse met de COSMOS_ENDPOINT en COSMOS_KEY omgevingsvariabelen als parameters.

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

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

Verbinding maken met een verbindingsreeks

De CosmosClient-klasse heeft een from_connection_string methode die u kunt gebruiken om verbinding te maken met één vereiste parameter:

Parameter	Voorbeeldwaarde	Beschrijving
conn_str	COSMOS_CONNECTION_STRING Omgevingsvariabele	De verbindingsreeks naar het API voor NoSQL-account.
credential	COSMOS_KEY Omgevingsvariabele	Een optionele alternatieve accountsleutel of resourcetoken die moet worden gebruikt in plaats van het account in de verbindingsreeks.

Uw account ophalen verbindingsreeks

Azure-CLI

1. Gebruik de az cosmosdb list opdracht om de naam van het eerste Azure Cosmos DB-account in uw resourcegroep op te halen en op te slaan in de accountName-shellvariabele .

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

2. Zoek de PRIMAIRE VERBINDINGSREEKS in de lijst met verbindingsreeks s voor het account met de az-cosmosdb-keys-list opdracht.

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

Powershell

1. Gebruik de Get-AzCosmosDBAccount cmdlet om de naam van het eerste Azure Cosmos DB-account in uw resourcegroep op te halen en op te slaan in de variabele ACCOUNT_NAME shell.

   # Retrieve most recently created account name
   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
   }
   $ACCOUNT_NAME = (
       Get-AzCosmosDBAccount @parameters |
           Select-Object -Property Name -First 1
   ).Name
   

2. Zoek de PRIMAIRE VERBINDINGSREEKS in de lijst met verbindingsreeks s voor het account met de Get-AzCosmosDBAccountKey cmdlet.

   $parameters = @{
       ResourceGroupName = $RESOURCE_GROUP_NAME
       Name = $ACCOUNT_NAME
       Type = "ConnectionStrings"
   }    
   Get-AzCosmosDBAccountKey @parameters |
       Select-Object -Property "Primary SQL Connection String" -First 1    
   

Portal

Tip

Voor deze handleiding raden we u aan de naam msdocs-cosmos-python-howto-rgvan de resourcegroep te gebruiken.

1. Meld u aan bij het Azure-portaal.

2. Navigeer naar de bestaande azure Cosmos DB for NoSQL-accountpagina.

3. Selecteer op de azure Cosmos DB for NoSQL-accountpagina de optie Navigatiemenu Sleutels .

4. Noteer de waarde uit het veld PRIMARY CONNECTION STRING .

Als u de waarde PRIMARY CONNECTION STRING in uw Python-code wilt gebruiken, moet u deze behouden tot een nieuwe omgevingsvariabele op de lokale computer waarop de toepassing wordt uitgevoerd.

Windows

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

Linux/macOS

export COSMOS_CONNECTION_STRING="<cosmos-account-PRIMARY-CONNECTION-STRING>"

CosmosClient maken met verbindingsreeks

Maak een nieuw exemplaar van de CosmosClient-klasse met de COSMOS_CONNECTION_STRING omgevingsvariabele als enige parameter.

CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]

client = CosmosClient.from_connection_string(conn_str=CONN_STR)

Verbinding maken met behulp van het Microsoft Identity Platform

Gebruik een beveiligingsprincipaal om verbinding te maken met uw API voor NoSQL-account met behulp van het Microsoft Identity Platform en de Microsoft Entra-id. Het exacte type principal is afhankelijk van waar u uw toepassingscode host. De onderstaande tabel fungeert als een snelzoekgids.

Waar de toepassing wordt uitgevoerd	Beveiligingsprincipal
Lokale machine (ontwikkelen en testen)	Gebruikersidentiteit of service-principal
Azure	Beheerde identiteit
Servers of clients buiten Azure	Service-principal

Azure.Identity importeren

Het pakket azure-identity bevat kernverificatiefunctionaliteit die wordt gedeeld tussen alle Azure SDK-bibliotheken.

Importeer het azure-identity-pakket in uw omgeving.

pip install azure-identity

CosmosClient maken met standaardreferentie-implementatie

Als u test op een lokale computer of uw toepassing wordt uitgevoerd op Azure-services met directe ondersteuning voor beheerde identiteiten, moet u een OAuth-token verkrijgen door een DefaultAzureCredential exemplaar te maken.

In uw app.py:

• Haal het eindpunt op om verbinding mee te maken zoals wordt weergegeven in de sectie hierboven voor Verbinding maken met een eindpunt en sleutel en stel dit in als de omgevingsvariabele COSMOS_ENDPOINT.

• Importeer de DefaultAzureCredential en maak er een exemplaar van.

• Maak een nieuw exemplaar van de CosmosClient-klasse met het EINDPUNT en de referentie als parameters.

from azure.identity import DefaultAzureCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]

credential = DefaultAzureCredential()

client = CosmosClient(ENDPOINT, credential)

Belangrijk

Zie Op rollen gebaseerd toegangsbeheer configureren met Microsoft Entra ID voor uw Azure Cosmos DB-account voor meer informatie over het toevoegen van de juiste rol om dit mogelijk te makenDefaultAzureCredential. Zie met name de sectie over het maken van rollen en het toewijzen ervan aan een principal-id.

CosmosClient maken met een aangepaste referentie-implementatie

Als u van plan bent om de toepassing uit Azure te implementeren, kunt u een OAuth-token verkrijgen met behulp van andere klassen in de Azure.Identity-clientbibliotheek voor Python. Deze andere klassen zijn ook afgeleid van de TokenCredential klasse.

In dit voorbeeld maken we een ClientSecretCredential exemplaar met behulp van client- en tenant-id's, samen met een clientgeheim.

In uw app.py:

• Haal de referentiegegevens op uit omgevingsvariabelen voor een service-principal. U kunt de client-id, tenant-id en clientgeheim verkrijgen wanneer u een toepassing registreert in Microsoft Entra-id. Zie Een toepassing registreren bij het Microsoft Identity Platform voor meer informatie over het registreren van Microsoft Entra-toepassingen.

• Importeer de ClientSecretCredential en maak een exemplaar met de TENANT_ID, CLIENT_IDen CLIENT_SECRET omgevingsvariabelen als parameters.

• Maak een nieuw exemplaar van de CosmosClient-klasse met het EINDPUNT en de referentie als parameters.

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)

Uw toepassing bouwen

Tijdens het bouwen van uw toepassing werkt uw code voornamelijk met vier typen resources:

• De API voor NoSQL-account, de unieke naamruimte op het hoogste niveau voor uw Azure Cosmos DB-gegevens.

• Databases, die de containers in uw account organiseren.

• Containers, die een set afzonderlijke items in uw database bevatten.

• Items, die een JSON-document in uw container vertegenwoordigen.

Het volgende diagram geeft de relatie tussen deze resources weer.

Hiërarchisch diagram met een Azure Cosmos DB-account bovenaan. Het account heeft twee onderliggende databaseknooppunten. Een van de databaseknooppunten bevat twee onderliggende containerknooppunten. Het andere databaseknooppunt bevat één onderliggend containerknooppunt. Dat knooppunt met één container heeft drie onderliggende itemknooppunten.

Elk type resource wordt vertegenwoordigd door een of meer gekoppelde Python-klassen. Hier volgt een lijst met de meest voorkomende klassen voor synchrone programmering. (Er zijn vergelijkbare klassen voor asynchrone programmering onder de azure.cosmos.aio-naamruimte .)

Klas	Beschrijving
CosmosClient	Deze klasse biedt een logische weergave aan de clientzijde voor de Azure Cosmos DB-service. Het clientobject wordt gebruikt om aanvragen aan de service te configureren en uitvoeren.
DatabaseProxy	Een interface voor een database die al dan niet bestaat in de service. Deze klasse mag niet rechtstreeks worden geïnstantieerd. In plaats daarvan moet u de methode CosmosClient get_database_client gebruiken.
ContainerProxy	Een interface voor interactie met een specifieke Cosmos DB-container. Deze klasse mag niet rechtstreeks worden geïnstantieerd. Gebruik in plaats daarvan de methode DatabaseProxy get_container_client om een bestaande container op te halen, of de create_container methode om een nieuwe container te maken.

In de volgende handleidingen ziet u hoe u elk van deze klassen gebruikt om uw toepassing te bouwen.

Guide	Beschrijving
Een database maken	Databases maken
Container maken	Maak containers
Voorbeelden van items	Een specifiek item lezen

Zie ook

• PyPi
• Voorbeelden
• API-naslaginformatie
• Broncode van bibliotheek
• Feedback geven

Volgende stappen

Nu u verbinding hebt gemaakt met een API voor NoSQL-account, gebruikt u de volgende handleiding voor het maken en beheren van databases.

Een database maken in Azure Cosmos DB for NoSQL met behulp van Python