Začínáme se službou Azure Cosmos DB for NoSQL pomocí Pythonu

  • Článek

PLATÍ PRO: NoSQL

V tomto článku se dozvíte, jak se připojit ke službě Azure Cosmos DB for NoSQL pomocí sady Python SDK. Po připojení můžete provádět operace s databázemi, kontejnery a položkami.

Referenční informace ke zdrojovému kódu knihovny s referenčními informacemi | | k rozhraní API pro balíčky | (PyPi) |

Požadavky

Nastavení projektu

Vytvořte prostředí, ve které můžete spustit kód Pythonu.

S virtuálním prostředím můžete balíčky Pythonu nainstalovat v izolovaném prostředí, aniž by to ovlivnilo zbytek systému.

Nainstalujte sadu Azure Cosmos DB for NoSQL Python SDK ve virtuálním prostředí.

pip install azure-cosmos

Vytvoření aplikace v Pythonu

Ve svém prostředí vytvořte nový soubor app.py a přidejte do něj následující kód:

import json
import os
import sys
import uuid

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

Předchozí kód importuje moduly, které použijete ve zbývající části článku.

Připojení do služby Azure Cosmos DB for NoSQL

Pokud se chcete připojit k rozhraní API pro NoSQL služby Azure Cosmos DB, vytvořte instanci třídy CosmosClient . Tato třída je výchozím bodem pro provádění všech operací s databázemi. Existují tři způsoby připojení k účtu rozhraní API for NoSQL pomocí třídy CosmosClient :

Připojení s koncovým bodem a klíčem

Konstruktor pro CosmosClient má dva požadované parametry:

Parametr Příklad hodnoty Popis
url COSMOS_ENDPOINT proměnná prostředí Rozhraní API pro koncový bod NoSQL, které se má použít pro všechny požadavky.
credential COSMOS_KEY proměnná prostředí Klíč účtu nebo token prostředku, který se má použít při ověřování.

Načtení koncového bodu a klíče účtu

  1. Vytvořte proměnnou prostředí pro resourceGroupName.

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

  2. az cosmosdb list Pomocí příkazu načtěte název prvního účtu služby Azure Cosmos DB ve vaší skupině prostředků a uložte ho do proměnné prostředí accountName.

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

  3. Pomocí příkazu získejte identifikátor URI koncového bodu API pro NoSQL pro účetaz cosmosdb show.

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

  4. Pomocí příkazu najděte PRIMÁRNÍ KLÍČ ze seznamu klíčů pro účetaz-cosmosdb-keys-list.

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

  5. Zaznamená hodnoty identifikátoru URI a PRIMÁRNÍHO KLÍČE . Tyto přihlašovací údaje použijete později.

Pokud chcete použít hodnoty URI a PRIMARY KEY v kódu Pythonu, zachovejte je do nových proměnných prostředí na místním počítači, na kterém běží aplikace.

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

Vytvoření CosmosClient s koncovým bodem účtu a klíčem

Vytvořte novou instanci třídy CosmosClient s proměnnými COSMOS_ENDPOINT prostředí a COSMOS_KEY jako parametry.

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

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

Připojení s připojovací řetězec

Třída CosmosClient má from_connection_string metodu, kterou můžete použít pro připojení pomocí jednoho požadovaného parametru:

Parametr Příklad hodnoty Popis
conn_str COSMOS_CONNECTION_STRING proměnná prostředí Připojovací řetězec k účtu ROZHRANÍ API pro NoSQL.
credential COSMOS_KEY proměnná prostředí Volitelný alternativní klíč účtu nebo token prostředku, který se má použít místo klíče v připojovací řetězec.

Načtení připojovací řetězec účtu

  1. az cosmosdb list Pomocí příkazu načtěte název prvního účtu služby Azure Cosmos DB ve vaší skupině prostředků a uložte ho do proměnné prostředí accountName.

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

  2. V seznamu připojovací řetězec pro účet pomocí az-cosmosdb-keys-list příkazu vyhledejte PRIMÁRNÍ PŘIPOJOVACÍ ŘETĚZEC.

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

Pokud chcete použít hodnotu PRIMARY CONNECTION STRING v kódu Pythonu, zachovejte ji do nové proměnné prostředí na místním počítači, na kterém je spuštěná aplikace.

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

Vytvoření CosmosClient pomocí připojovací řetězec

Vytvořte novou instanci třídy CosmosClient s COSMOS_CONNECTION_STRING proměnnou prostředí jako jediný parametr.

CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]

client = CosmosClient.from_connection_string(conn_str=CONN_STR)

Připojení s využitím platformy Microsoft Identity Platform

Pokud se chcete připojit k účtu ROZHRANÍ API for NoSQL pomocí platformy Microsoft Identity Platform a ID Microsoft Entra, použijte instanční objekt zabezpečení. Přesný typ objektu zabezpečení bude záviset na tom, kde hostujete kód aplikace. Následující tabulka slouží jako stručná referenční příručka.

Kde aplikace běží Objekt zabezpečení
Místní počítač (vývoj a testování) Identita uživatele nebo instanční objekt
Azure Spravovaná identita
Servery nebo klienti mimo Azure Instanční objekt

Import Azure.Identity

Balíček azure-identity obsahuje základní funkce ověřování, které se sdílí mezi všemi knihovnami sady Azure SDK.

Naimportujte balíček azure-identity do svého prostředí.

pip install azure-identity

Vytvoření CosmosClient s výchozí implementací přihlašovacích údajů

Pokud testujete na místním počítači nebo vaše aplikace bude běžet na službách Azure s přímou podporou spravovaných identit, získejte token OAuth vytvořením DefaultAzureCredential instance.

V app.py:

  • Získejte koncový bod, ke kterému se chcete připojit, jak je znázorněno v části výše pro Připojení s koncovým bodem a klíčem, a nastavte ho jako proměnnou COSMOS_ENDPOINTprostředí .

  • Importujte DefaultAzureCredential a vytvořte jeho instanci.

  • Vytvořte novou instanci třídy CosmosClient s koncovým bodem a přihlašovacími údaji jako parametry.

from azure.identity import DefaultAzureCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]

credential = DefaultAzureCredential()

client = CosmosClient(ENDPOINT, credential)

Důležité

Podrobnosti o tom, jak přidat správnou roli, která se má povolit DefaultAzureCredential , najdete v tématu Konfigurace řízení přístupu na základě role pomocí Microsoft Entra ID pro váš účet služby Azure Cosmos DB. Konkrétně si přečtěte část o vytváření rolí a jejich přiřazování k ID objektu zabezpečení.

Vytvoření CosmosClient s vlastní implementací přihlašovacích údajů

Pokud plánujete nasadit aplikaci z Azure, můžete token OAuth získat pomocí jiných tříd v klientské knihovně Azure.Identity pro Python. Tyto další třídy jsou také odvozeny z TokenCredential třídy.

V tomto příkladu ClientSecretCredential vytvoříme instanci pomocí identifikátorů klienta a tenanta spolu s tajným klíčem klienta.

V app.py:

  • Získejte informace o přihlašovacích údajích z proměnných prostředí pro instanční objekt. ID klienta, ID tenanta a tajný klíč klienta můžete získat při registraci aplikace v Microsoft Entra ID. Další informace o registraci aplikací Microsoft Entra naleznete v tématu Registrace aplikace na platformě Microsoft Identity Platform.

  • Importujte ClientSecretCredential a vytvořte instanci s TENANT_IDproměnnou a CLIENT_IDCLIENT_SECRET proměnné prostředí jako parametry.

  • Vytvořte novou instanci třídy CosmosClient s koncovým bodem a přihlašovacími údaji jako parametry.

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)

Sestavení aplikace

Při vytváření aplikace bude váš kód primárně pracovat se čtyřmi typy prostředků:

  • Účet ROZHRANÍ API pro NoSQL, což je jedinečný obor názvů nejvyšší úrovně pro vaše data Azure Cosmos DB.

  • Databáze, které uspořádají kontejnery ve vašem účtu.

  • Kontejnery, které obsahují sadu jednotlivých položek v databázi.

  • Položky, které představují dokument JSON ve vašem kontejneru.

Na následujícím diagramu jsou vztahy těchto prostředků.

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

Každý typ prostředku je reprezentován jednou nebo více přidruženými třídami Pythonu. Tady je seznam nejběžnějších tříd pro synchronní programování. (Existují podobné třídy pro asynchronní programování v rámci oboru názvů azure.cosmos.aio .)

Třída Popis
CosmosClient Tato třída poskytuje logickou reprezentaci na straně klienta pro službu Azure Cosmos DB. Objekt klienta slouží ke konfiguraci a spouštění požadavků na službu.
DatabaseProxy Rozhraní databáze, která může nebo nemusí existovat ve službě, ještě existuje. Tato třída by neměla být vytvořena přímo. Místo toho byste měli použít metodu get_database_client CosmosClient.
ContainerProxy Rozhraní pro interakci s konkrétním kontejnerem Cosmos DB. Tato třída by neměla být vytvořena přímo. Místo toho pomocí metody DatabaseProxy get_container_client získejte existující kontejner nebo metodu create_container k vytvoření nového kontejneru.

Následující příručky vám ukážou, jak pomocí každé z těchto tříd sestavit aplikaci.

Průvodce Popis
Vytvoření databáze Vytvoření databází
Vytvoření kontejneru Vytváření kontejnerů
Příklady položek Načtení konkrétní položky

Viz také

Další kroky

Teď, když jste se připojili k účtu ROZHRANÍ API pro NoSQL, použijte další příručku k vytváření a správě databází.

Vytvoření databáze ve službě Azure Cosmos DB for NoSQL pomocí Pythonu