Ismerkedés a NoSQL-hez készült Azure Cosmos DB-vel a Python használatával

  • Cikk

A KÖVETKEZŐRE VONATKOZIK: NoSQL

Ez a cikk bemutatja, hogyan csatlakozhat az Azure Cosmos DB for NoSQL-hez a Python SDK használatával. A csatlakozás után műveleteket hajthat végre adatbázisokon, tárolókon és elemeken.

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

Előfeltételek

A projekt beállítása

Hozzon létre egy környezetet, amelyben Python-kódot futtathat.

Virtuális környezetben a Python-csomagokat izolált környezetben telepítheti anélkül, hogy a rendszer többi részét érintené.

Telepítse az Azure Cosmos DB for NoSQL Python SDK-t a virtuális környezetben.

pip install azure-cosmos

A Python-alkalmazás létrehozása

A környezetében hozzon létre egy új app.py fájlt, és adja hozzá a következő kódot:

import json
import os
import sys
import uuid

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

Az előző kód importálja a cikk többi részében használt modulokat.

Csatlakozás az Azure Cosmos DB for NoSQL-be

Az Azure Cosmos DB NoSQL-hez készült API-hoz való csatlakozáshoz hozza létre a CosmosClient osztály egy példányát. Ez az osztály a kiindulópont az adatbázisokon végzett összes művelet végrehajtásához. A CosmosClient osztály használatával háromféleképpen csatlakozhat egy API for NoSQL-fiókhoz:

Csatlakozás végponttal és kulccsal

A CosmosClient konstruktorának két kötelező paramétere van:

Parameter Példaérték Leírás
url COSMOS_ENDPOINT környezeti változó Az API for NoSQL-végpont az összes kéréshez használható.
credential COSMOS_KEY környezeti változó A hitelesítéshez használandó fiókkulcs vagy erőforrás-jogkivonat.

Fiókvégpont és kulcs lekérése

  1. Hozzon létre egy rendszerhéjváltozót a resourceGroupName számára.

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

  2. az cosmosdb list A paranccsal lekérheti az erőforráscsoport első Azure Cosmos DB-fiókjának nevét, és tárolhatja az accountName rendszerhéj változójában.

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

  3. Kérje le a noSQL-végpont URI API-jának lekérését a fiókhoz a az cosmosdb show paranccsal.

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

  4. Keresse meg az ELSŐDLEGES KULCSOT a parancsot tartalmazó az-cosmosdb-keys-list fiók kulcsainak listájából.

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

  5. Jegyezze fel az URI és AZ ELSŐDLEGES KULCS értékeit. Ezeket a hitelesítő adatokat később fogja használni.

A Python-kód URI- és ELSŐDLEGESKULCS-értékeinek használatához őrizze meg őket az alkalmazást futtató helyi gépen lévő új környezeti változókban.

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

CosmosClient létrehozása fiókvégponttal és kulccsal

Hozzon létre egy új CosmosClient-példányt paraméterekként a környezeti és COSMOS_KEY a COSMOS_ENDPOINT környezeti változókkal.

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

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

Csatlakozás kapcsolati sztring

A CosmosClient osztály egy from_connection_string metódussal rendelkezik, amellyel egyetlen szükséges paraméterrel csatlakozhat:

Parameter Példaérték Leírás
conn_str COSMOS_CONNECTION_STRING környezeti változó A Kapcsolati sztring a NoSQL-fiók API-hoz.
credential COSMOS_KEY környezeti változó Választható alternatív fiókkulcs vagy erőforrás-jogkivonat a kapcsolati sztring lévő helyett.

A fiók kapcsolati sztring lekérése

  1. az cosmosdb list A paranccsal lekérheti az erőforráscsoport első Azure Cosmos DB-fiókjának nevét, és tárolhatja az accountName rendszerhéj változójában.

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

  2. Keresse meg az ELSŐDLEGES KAPCSOLAT SZTRINGet a parancsot tartalmazó az-cosmosdb-keys-list fiók kapcsolati sztring listájából.

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

Az ELSŐDLEGES KAPCSOLATI SZTRING érték Python-kódban való használatához őrizze meg azt egy új környezeti változóban az alkalmazást futtató helyi gépen.

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

CosmosClient létrehozása kapcsolati sztring

Hozzon létre egy új CosmosClient-példányt, amelynek egyetlen paramétere a COSMOS_CONNECTION_STRING környezeti változó.

CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]

client = CosmosClient.from_connection_string(conn_str=CONN_STR)

Csatlakozás a Microsoft Identitásplatform

Ha a Microsoft Identitásplatform és a Microsoft Entra ID használatával szeretne csatlakozni a NoSQL API-fiókjához, használjon egy biztonsági tagot. Az egyszerűség pontos típusa attól függ, hogy hol tárolja az alkalmazás kódját. Az alábbi táblázat rövid útmutatóként szolgál.

Az alkalmazás futtatásának helye Rendszerbiztonsági tag
Helyi gép (fejlesztés és tesztelés) Felhasználói identitás vagy szolgáltatásnév
Azure Managed identity
Azure-on kívüli kiszolgálók vagy ügyfelek Service principal

Az Azure.Identity importálása

Az azure-identity csomag az összes Azure SDK-kódtár között megosztott alapvető hitelesítési funkciókat tartalmazza.

Importálja az azure-identity csomagot a környezetébe.

pip install azure-identity

CosmosClient létrehozása az alapértelmezett hitelesítő adatok implementálásával

Ha helyi gépen tesztel, vagy az alkalmazás a felügyelt identitások közvetlen támogatásával fog futni az Azure-szolgáltatásokban, szerezze be az OAuth-jogkivonatot egy DefaultAzureCredential példány létrehozásával.

A app.py:

from azure.identity import DefaultAzureCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]

credential = DefaultAzureCredential()

client = CosmosClient(ENDPOINT, credential)

Fontos

A megfelelő szerepkör DefaultAzureCredential hozzáadásáról további információt az Azure Cosmos DB-fiók szerepköralapú hozzáférés-vezérlésének konfigurálása a Microsoft Entra-azonosítóval című témakörben talál. Lásd különösen a szerepkörök létrehozásáról és egy egyszerű azonosítóhoz való hozzárendeléséről szóló szakaszt.

CosmosClient létrehozása egyéni hitelesítő adatok implementálásával

Ha azt tervezi, hogy az alkalmazást az Azure-on kívül helyezi üzembe, oAuth-jogkivonatot szerezhet be a PythonHoz készült Azure.Identity ügyfélkódtár más osztályainak használatával. Ezek a többi osztály is az TokenCredential osztályból származik.

Ebben a példában egy példányt ClientSecretCredential hozunk létre ügyfél- és bérlőazonosítók, valamint egy titkos ügyfélkód használatával.

A app.py:

  • Kérje le a hitelesítő adatokat egy szolgáltatásnév környezeti változóiból. Az alkalmazás Microsoft Entra-azonosítóban való regisztrálásakor beszerezheti az ügyfél-azonosítót, a bérlőazonosítót és az ügyfél titkos kódját. További információ a Microsoft Entra-alkalmazások regisztrálásáról: Alkalmazás regisztrálása a Microsoft Identitásplatform.

  • Importálja a ClientSecretCredential objektumot, és hozzon létre egy példányt paraméterekként a TENANT_ID, CLIENT_IDés CLIENT_SECRET környezeti változókkal.

  • Hozzon létre egy új CosmosClient-példányt az ENDPOINT és a hitelesítő adatok paraméterként.

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)

Az alkalmazás összeállítása

Az alkalmazás létrehozásakor a kód elsősorban négy erőforrástípussal fog működni:

  • Az API for NoSQL-fiók, amely az Azure Cosmos DB-adatok egyedi legfelső szintű névtere.

  • Adatbázisok, amelyek rendszerezik a tárolókat a fiókjában.

  • Tárolók, amelyek az adatbázis egyes elemeit tartalmazzák.

  • Elemek, amelyek egy JSON-dokumentumot jelölnek a tárolóban.

Az alábbi ábra az ezen erőforrások közötti kapcsolatot mutatja be.

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

Minden erőforrástípust egy vagy több társított Python-osztály jelöl. Íme a szinkron programozás leggyakoribb osztályainak listája. (Az azure.cosmos.aio névtérben hasonló osztályok vannak az aszinkron programozáshoz.)

Osztály Leírás
CosmosClient Ez az osztály ügyféloldali logikai reprezentációt biztosít az Azure Cosmos DB szolgáltatáshoz. Az ügyfélobjektum a szolgáltatással kapcsolatos kérések konfigurálására és végrehajtására szolgál.
DatabaseProxy Egy olyan adatbázis felülete, amely lehet, hogy még létezik a szolgáltatásban. Ezt az osztályt nem szabad közvetlenül példányosítva létrehozni. Ehelyett a CosmosClient get_database_client metódust kell használnia.
ContainerProxy Egy adott Cosmos DB-tárolóval való interakcióra szolgáló felület. Ezt az osztályt nem szabad közvetlenül példányosítva létrehozni. Ehelyett használja a DatabaseProxy get_container_client metódust egy meglévő tároló lekéréséhez, vagy a create_container metódust egy új tároló létrehozásához.

Az alábbi útmutatók bemutatják, hogyan használhatja ezeket az osztályokat az alkalmazás létrehozásához.

Útmutató Leírás
Adatbázis létrehozása Adatbázisok létrehozására
Tároló létrehozása Tárolók létrehozása
Példák elemre Adott elem pontolvasása

Kapcsolódó információk

Következő lépések

Most, hogy csatlakozott egy API for NoSQL-fiókhoz, használja a következő útmutatót az adatbázisok létrehozásához és kezeléséhez.

Adatbázis létrehozása az Azure Cosmos DB for NoSQL-ben a Python használatával