Kom igång med Azure Cosmos DB för NoSQL med Python

  • Artikel

GÄLLER FÖR: NoSQL

Den här artikeln visar hur du ansluter till Azure Cosmos DB för NoSQL med hjälp av Python SDK. När du är ansluten kan du utföra åtgärder på databaser, containrar och objekt.

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

Förutsättningar

Konfigurera projektet

Skapa en miljö som du kan köra Python-kod i.

Med en virtuell miljö kan du installera Python-paket i en isolerad miljö utan att påverka resten av systemet.

Installera Azure Cosmos DB för NoSQL Python SDK i den virtuella miljön.

pip install azure-cosmos

Skapa Python-programmet

I din miljö skapar du en ny app.py-fil och lägger till följande kod i den:

import json
import os
import sys
import uuid

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

Föregående kod importerar moduler som du ska använda i resten av artikeln.

Anslut till Azure Cosmos DB för NoSQL

Om du vill ansluta till API:et för NoSQL för Azure Cosmos DB skapar du en instans av klassen CosmosClient . Den här klassen är utgångspunkten för att utföra alla åtgärder mot databaser. Det finns tre sätt att ansluta till ett API för NoSQL-konto med klassen CosmosClient :

Anslut med en slutpunkt och nyckel

Konstruktorn för CosmosClient har två obligatoriska parametrar:

Parameter Exempelvärde Description
url COSMOS_ENDPOINT miljövariabel API för NoSQL-slutpunkt som ska användas för alla begäranden.
credential COSMOS_KEY miljövariabel Kontonyckel eller resurstoken som ska användas vid autentisering.

Hämta din kontoslutpunkt och nyckel

  1. Skapa en gränssnittsvariabel för resourceGroupName.

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

  2. az cosmosdb list Använd kommandot för att hämta namnet på det första Azure Cosmos DB-kontot i resursgruppen och lagra det i variabeln accountName-gränssnittet.

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

  3. Hämta API:et för NoSQL-slutpunkts-URI för kontot med kommandot az cosmosdb show .

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

  4. Leta reda på PRIMÄRNYCKEL i listan över nycklar för kontot med az-cosmosdb-keys-list kommandot .

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

  5. Registrera värdena för URI och PRIMÄRNYCKEL . Du använder dessa autentiseringsuppgifter senare.

Om du vill använda värdena för URI och PRIMÄRNYCKEL i Python-koden sparar du dem i nya miljövariabler på den lokala dator som kör programmet.

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

Skapa CosmosClient med kontoslutpunkt och nyckel

Skapa en ny instans av klassen CosmosClient med COSMOS_ENDPOINT miljövariablerna och COSMOS_KEY som parametrar.

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

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

Anslut med en anslutningssträng

Klassen CosmosClient har en from_connection_string metod som du kan använda för att ansluta med en obligatorisk parameter:

Parameter Exempelvärde Description
conn_str COSMOS_CONNECTION_STRING miljövariabel Anslutningssträng till API:et för NoSQL-kontot.
credential COSMOS_KEY miljövariabel En valfri alternativ kontonyckel eller resurstoken som ska användas i stället för den i anslutningssträng.

Hämta ditt konto anslutningssträng

  1. az cosmosdb list Använd kommandot för att hämta namnet på det första Azure Cosmos DB-kontot i resursgruppen och lagra det i variabeln accountName-gränssnittet.

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

  2. Leta upp DEN PRIMÄRA ANSLUTNINGSSTRÄNGen i listan över anslutningssträng för kontot med az-cosmosdb-keys-list kommandot .

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

Om du vill använda värdet PRIMÄR ANSLUTNINGSSTRÄNG i Python-koden sparar du det i en ny miljövariabel på den lokala dator som kör programmet.

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

Skapa CosmosClient med anslutningssträng

Skapa en ny instans av klassen CosmosClient med COSMOS_CONNECTION_STRING miljövariabeln som den enda parametern.

CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]

client = CosmosClient.from_connection_string(conn_str=CONN_STR)

Anslut med hjälp av Microsofts identitetsplattform

Om du vill ansluta till ditt API för NoSQL-konto med hjälp av Microsofts identitetsplattform och Microsoft Entra-ID använder du ett säkerhetsobjekt. Den exakta typen av huvudnamn beror på var du är värd för programkoden. Tabellen nedan fungerar som en snabbreferensguide.

Där programmet körs Säkerhetsobjekt
Lokal dator (utveckla och testa) Användaridentitet eller tjänstens huvudnamn
Azure Hanterad identitet
Servrar eller klienter utanför Azure Tjänstens huvudnamn

Importera Azure.Identity

Azure-identitetspaketet innehåller grundläggande autentiseringsfunktioner som delas mellan alla Azure SDK-bibliotek.

Importera azure-identity-paketet till din miljö.

pip install azure-identity

Skapa CosmosClient med standardimplementering av autentiseringsuppgifter

Om du testar på en lokal dator, eller om programmet körs på Azure-tjänster med direkt stöd för hanterade identiteter, hämtar du en OAuth-token genom att skapa en DefaultAzureCredential instans.

I din app.py:

from azure.identity import DefaultAzureCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]

credential = DefaultAzureCredential()

client = CosmosClient(ENDPOINT, credential)

Viktigt!

Mer information om hur du lägger till rätt roll för att aktivera DefaultAzureCredential för att fungera finns i Konfigurera rollbaserad åtkomstkontroll med Microsoft Entra-ID för ditt Azure Cosmos DB-konto. Se särskilt avsnittet om hur du skapar roller och tilldelar dem till ett huvudnamns-ID.

Skapa CosmosClient med en anpassad implementering av autentiseringsuppgifter

Om du planerar att distribuera programmet från Azure kan du hämta en OAuth-token med hjälp av andra klasser i Azure.Identity-klientbiblioteket för Python. Dessa andra klasser härleds också från TokenCredential klassen.

I det här exemplet skapar vi en ClientSecretCredential instans med hjälp av klient- och klientidentifierare, tillsammans med en klienthemlighet.

I din app.py:

  • Hämta information om autentiseringsuppgifter från miljövariabler för ett huvudnamn för tjänsten. Du kan hämta klient-ID, klient-ID och klienthemlighet när du registrerar ett program i Microsoft Entra-ID. Mer information om hur du registrerar Microsoft Entra-program finns i Registrera ett program med Microsofts identitetsplattform.

  • Importera ClientSecretCredential och skapa en instans med TENANT_IDmiljövariablerna , CLIENT_IDoch CLIENT_SECRET som parametrar.

  • Skapa en ny instans av klassen CosmosClient med ENDPOINT och autentiseringsuppgifter som parametrar.

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)

Skapa ditt program

När du skapar ditt program interagerar koden främst med fyra typer av resurser:

  • API:et för NoSQL-kontot, som är det unika toppnivånamnområdet för dina Azure Cosmos DB-data.

  • Databaser som organiserar containrarna i ditt konto.

  • Containrar som innehåller en uppsättning enskilda objekt i databasen.

  • Objekt som representerar ett JSON-dokument i containern.

Följande diagram visar relationen mellan de här resurserna.

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

Varje typ av resurs representeras av en eller flera associerade Python-klasser. Här är en lista över de vanligaste klasserna för synkron programmering. (Det finns liknande klasser för asynkron programmering under namnområdet azure.cosmos.aio .)

Klass Description
CosmosClient Den här klassen tillhandahåller en logisk representation på klientsidan för Azure Cosmos DB-tjänsten. Klientobjektet används för att konfigurera och köra begäranden mot tjänsten.
DatabaseProxy Ett gränssnitt till en databas som kan, eller kanske inte, finns i tjänsten ännu. Den här klassen ska inte instansieras direkt. I stället bör du använda metoden CosmosClient get_database_client .
ContainerProxy Ett gränssnitt för att interagera med en specifik Cosmos DB-container. Den här klassen ska inte instansieras direkt. Använd i stället metoden DatabaseProxy get_container_client för att hämta en befintlig container eller metoden create_container för att skapa en ny container.

Följande guider visar hur du använder var och en av dessa klasser för att skapa ditt program.

Guide Description
Skapa en databas Skapa databaser
Skapa container Skapa containrar
Objektexempel Punktläsning av ett specifikt objekt

Se även

Nästa steg

Nu när du har anslutit till ett API för NoSQL-konto använder du nästa guide för att skapa och hantera databaser.

Skapa en databas i Azure Cosmos DB för NoSQL med Python