Rozpoczynanie pracy z usługą Azure Cosmos DB for NoSQL przy użyciu języka Python

DOTYCZY: NoSQL

W tym artykule pokazano, jak nawiązać połączenie z usługą Azure Cosmos DB for NoSQL przy użyciu zestawu SDK języka Python. Po nawiązaniu połączenia można wykonywać operacje na bazach danych, kontenerach i elementach.

Package (PyPi) | Samples | — kod | źródłowy | biblioteki źródłowej interfejsu API

Wymagania wstępne

• Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
• Konto usługi Azure Cosmos DB for NoSQL. Utwórz interfejs API dla konta NoSQL.
• Środowisko Python w wersji 3.7 lub nowszej
• Interfejs wiersza polecenia platformy Azure lubprogram Azure PowerShell

konfigurowanie projektu

Utwórz środowisko, w którym można uruchomić kod języka Python.

Środowisko wirtualne

Za pomocą środowiska wirtualnego można zainstalować pakiety języka Python w izolowanym środowisku bez wpływu na pozostałą część systemu.

Zainstaluj zestaw SDK języka Python usługi Azure Cosmos DB for NoSQL w środowisku wirtualnym.

pip install azure-cosmos

Kontener deweloperski

Kontener deweloperski to wstępnie skonfigurowane środowisko, za pomocą którego można uruchamiać kod języka Python.

Aby uruchomić kontener deweloperski, możesz użyć:

• Visual Studio Code: sklonuj to repozytorium na komputer lokalny i otwórz folder przy użyciu rozszerzenia Kontenery deweloperów.

• GitHub Codespaces: otwórz to repozytorium w przeglądarce przy użyciu usługi GitHub Codespace.

Zainstaluj zestaw SDK języka Python usługi Azure Cosmos DB for NoSQL w kontenerze deweloperskim.

pip install azure-cosmos

Tworzenie aplikacji w języku Python

W środowisku utwórz nowy plik app.py i dodaj do niego następujący kod:

import json
import os
import sys
import uuid

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

Poprzedni kod importuje moduły, które będą używane w pozostałej części artykułu.

Połączenie do usługi Azure Cosmos DB for NoSQL

Aby nawiązać połączenie z interfejsem API dla noSQL usługi Azure Cosmos DB, utwórz wystąpienie klasy CosmosClient . Ta klasa jest punktem wyjścia do wykonywania wszystkich operacji względem baz danych. Istnieją trzy sposoby nawiązywania połączenia z interfejsem API dla konta NoSQL przy użyciu klasy CosmosClient :

• Połączenie za pomocą interfejsu API dla punktu końcowego NoSQL i klucza odczytu/zapisu
• Połączenie za pomocą interfejsu API dla parametry połączenia NoSQL
• Połączenie za pomocą identyfikatora Entra firmy Microsoft

Połączenie z punktem końcowym i kluczem

Konstruktor dla usługi CosmosClient ma dwa wymagane parametry:

Parametr	Przykładowa wartość	opis
url	COSMOS_ENDPOINT zmienna środowiskowa	Interfejs API dla punktu końcowego NoSQL do użycia dla wszystkich żądań.
credential	COSMOS_KEY zmienna środowiskowa	Klucz konta lub token zasobu do użycia podczas uwierzytelniania.

Pobieranie punktu końcowego i klucza konta

Interfejs wiersza polecenia platformy Azure

1. Utwórz zmienną powłoki dla właściwości resourceGroupName.

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

2. az cosmosdb list Użyj polecenia , aby pobrać nazwę pierwszego konta usługi Azure Cosmos DB w grupie zasobów i zapisać je w zmiennej powłoki accountName.

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

3. Pobierz identyfikator URI punktu końcowego interfejsu API dla programu NoSQL dla konta przy użyciu az cosmosdb show polecenia .

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

4. Znajdź KLUCZ PODSTAWOWY z listy kluczy dla konta za az-cosmosdb-keys-list pomocą polecenia .

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

5. Zapisz wartości identyfikatora URI i KLUCZA PODSTAWOWEgo. Te poświadczenia będą używane później.

Program PowerShell

1. Utwórz zmienną powłoki dla RESOURCE_GROUP_NAME.

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

2. Get-AzCosmosDBAccount Użyj polecenia cmdlet , aby pobrać nazwę pierwszego konta usługi Azure Cosmos DB w grupie zasobów i zapisać je w zmiennej powłoki ACCOUNT_NAME.

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

3. Pobierz identyfikator URI punktu końcowego interfejsu API dla programu NoSQL dla konta przy użyciu Get-AzCosmosDBAccount polecenia cmdlet .

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

4. Znajdź klucz PODSTAWOWY z listy kluczy dla konta za Get-AzCosmosDBAccountKey pomocą polecenia cmdlet .

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

5. Zapisz wartości identyfikatora URI i KLUCZA PODSTAWOWEgo. Te poświadczenia będą używane później.

Portal

Napiwek

W tym przewodniku zalecamy użycie nazwy msdocs-cosmos-python-howto-rggrupy zasobów .

1. Zaloguj się w witrynie Azure Portal.

2. Przejdź do istniejącej strony konta usługi Azure Cosmos DB for NoSQL.

3. Na stronie konta usługi Azure Cosmos DB for NoSQL wybierz opcję menu nawigacji Klucze .

   

4. Rejestruj wartości z pól Identyfikator URI i KLUCZ PODSTAWOWY. Te wartości będą używane w późniejszym kroku.

   

Aby użyć wartości URI i PRIMARY KEY w kodzie języka Python, utrwali je w nowych zmiennych środowiskowych na komputerze lokalnym z uruchomioną aplikacją.

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>"

Tworzenie klienta CosmosClient z punktem końcowym konta i kluczem

Utwórz nowe wystąpienie klasy CosmosClient ze zmiennymi COSMOS_ENDPOINT środowiskowymi i COSMOS_KEY jako parametrami.

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

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

Połączenie z parametry połączenia

Klasa CosmosClient ma metodę from_connection_string , której można użyć do nawiązania połączenia z jednym wymaganym parametrem:

Parametr	Przykładowa wartość	opis
conn_str	COSMOS_CONNECTION_STRING zmienna środowiskowa	Parametry połączenia do interfejsu API dla konta NoSQL.
credential	COSMOS_KEY zmienna środowiskowa	Opcjonalny alternatywny klucz konta lub token zasobu do użycia zamiast tego w parametry połączenia.

Pobieranie parametry połączenia konta

Interfejs wiersza polecenia platformy Azure

1. az cosmosdb list Użyj polecenia , aby pobrać nazwę pierwszego konta usługi Azure Cosmos DB w grupie zasobów i zapisać je w zmiennej powłoki accountName.

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

2. Znajdź podstawowe parametry POŁĄCZENIA z listy parametry połączenia dla konta za az-cosmosdb-keys-list pomocą polecenia .

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

Program PowerShell

1. Get-AzCosmosDBAccount Użyj polecenia cmdlet , aby pobrać nazwę pierwszego konta usługi Azure Cosmos DB w grupie zasobów i zapisać je w zmiennej powłoki ACCOUNT_NAME.

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

2. Znajdź podstawowe parametry połączenia z listy parametry połączenia dla konta za Get-AzCosmosDBAccountKey pomocą polecenia cmdlet .

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

Portal

Napiwek

W tym przewodniku zalecamy użycie nazwy msdocs-cosmos-python-howto-rggrupy zasobów .

1. Zaloguj się w witrynie Azure Portal.

2. Przejdź do istniejącej strony konta usługi Azure Cosmos DB for NoSQL.

3. Na stronie konta usługi Azure Cosmos DB for NoSQL wybierz opcję menu nawigacji Klucze .

4. Zarejestruj wartość z pola PODSTAWOWE PARAMETRY POŁĄCZENIA.

Aby użyć wartości PODSTAWOWE PARAMETRY POŁĄCZENIA w kodzie języka Python, utrąć ją w nowej zmiennej środowiskowej na komputerze lokalnym, na którym jest uruchomiona aplikacja.

Windows

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

Linux/macOS

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

Tworzenie klienta CosmosClient przy użyciu parametry połączenia

Utwórz nowe wystąpienie klasy CosmosClient ze zmienną COSMOS_CONNECTION_STRING środowiskową jako jedyny parametr.

CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]

client = CosmosClient.from_connection_string(conn_str=CONN_STR)

Połączenie przy użyciu Platforma tożsamości Microsoft

Aby nawiązać połączenie z kontem interfejsu API dla noSQL przy użyciu Platforma tożsamości Microsoft i identyfikatora Entra firmy Microsoft, użyj podmiotu zabezpieczeń. Dokładny typ podmiotu zabezpieczeń będzie zależeć od tego, gdzie hostujesz kod aplikacji. Poniższa tabela służy jako krótki przewodnik informacyjny.

Gdzie działa aplikacja	Podmiot zabezpieczeń
Maszyna lokalna (programowanie i testowanie)	Tożsamość użytkownika lub jednostka usługi
Azure	Tożsamość zarządzana
Serwery lub klienci spoza platformy Azure	Jednostka usługi

Importowanie pliku Azure.Identity

Pakiet azure-identity zawiera podstawowe funkcje uwierzytelniania, które są współużytkowane przez wszystkie biblioteki zestawu Azure SDK.

Zaimportuj pakiet azure-identity do środowiska.

pip install azure-identity

Tworzenie elementu CosmosClient z domyślną implementacją poświadczeń

Jeśli testujesz na komputerze lokalnym lub aplikacja będzie działać w usługach platformy Azure z bezpośrednią obsługą tożsamości zarządzanych, uzyskaj token OAuth, tworząc DefaultAzureCredential wystąpienie.

W app.py:

• Pobierz punkt końcowy, z którego ma nawiązać połączenie, jak pokazano w powyższej sekcji dla Połączenie z punktem końcowym i kluczem, a następnie ustaw go jako zmienną środowiskową COSMOS_ENDPOINT.

• Zaimportuj wartość DefaultAzureCredential i utwórz jego wystąpienie.

• Utwórz nowe wystąpienie klasy CosmosClient z punktem KOŃCOWYM i poświadczenie jako parametry.

from azure.identity import DefaultAzureCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]

credential = DefaultAzureCredential()

client = CosmosClient(ENDPOINT, credential)

Ważne

Aby uzyskać szczegółowe informacje na temat dodawania prawidłowej roli w celu umożliwienia DefaultAzureCredential pracy, zobacz Konfigurowanie kontroli dostępu opartej na rolach przy użyciu identyfikatora Entra firmy Microsoft dla konta usługi Azure Cosmos DB. W szczególności zapoznaj się z sekcją dotyczącą tworzenia ról i przypisywania ich do identyfikatora podmiotu zabezpieczeń.

Tworzenie klienta CosmosClient z niestandardową implementacją poświadczeń

Jeśli planujesz wdrożyć aplikację z platformy Azure, możesz uzyskać token OAuth przy użyciu innych klas w bibliotece klienta Azure.Identity dla języka Python. Te inne klasy pochodzą również z TokenCredential klasy .

W tym przykładzie utworzymy ClientSecretCredential wystąpienie przy użyciu identyfikatorów klienta i dzierżawy wraz z wpisem tajnym klienta.

W app.py:

• Uzyskaj informacje o poświadczeniach ze zmiennych środowiskowych dla jednostki usługi. Identyfikator klienta, identyfikator dzierżawy i klucz tajny klienta można uzyskać podczas rejestrowania aplikacji w usłudze Microsoft Entra ID. Aby uzyskać więcej informacji na temat rejestrowania aplikacji firmy Microsoft Entra, zobacz Rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.

• Zaimportuj parametr ClientSecretCredential i utwórz wystąpienie ze zmiennymi TENANT_IDśrodowiskowymi , CLIENT_IDi CLIENT_SECRET .

• Utwórz nowe wystąpienie klasy CosmosClient z punktem KOŃCOWYM i poświadczenie 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)

Kompilowanie aplikacji

Podczas kompilowania aplikacji kod będzie przede wszystkim współdziałać z czterema typami zasobów:

• Interfejs API dla konta NoSQL, który jest unikatową przestrzenią nazw najwyższego poziomu dla danych usługi Azure Cosmos DB.

• Bazy danych, które organizują kontenery na twoim koncie.

• Kontenery, które zawierają zestaw pojedynczych elementów w bazie danych.

• Elementy reprezentujące dokument JSON w kontenerze.

Na poniższym diagramie przedstawiono relacje między tymi zasobami.

Diagram hierarchiczny przedstawiający konto usługi Azure Cosmos DB u góry. Konto ma dwa podrzędne węzły bazy danych. Jeden z węzłów bazy danych zawiera dwa podrzędne węzły kontenera. Drugi węzeł bazy danych zawiera jeden podrzędny węzeł kontenera. Ten pojedynczy węzeł kontenera ma trzy węzły elementów podrzędnych.

Każdy typ zasobu jest reprezentowany przez co najmniej jedną skojarzona klasę języka Python. Oto lista najpopularniejszych klas programowania synchronicznego. (Istnieją podobne klasy do programowania asynchronicznego w przestrzeni nazw azure.cosmos.aio ).

Klasa	opis
CosmosClient	Ta klasa zapewnia logiczną reprezentację po stronie klienta dla usługi Azure Cosmos DB. Obiekt klienta służy do konfigurowania i wykonywania żądań względem usługi.
DatabaseProxy	Interfejs bazy danych, która może lub nie istnieje jeszcze w usłudze. Ta klasa nie powinna być tworzone bezpośrednio. Zamiast tego należy użyć metody get_database_client CosmosClient.
ContainerProxy	Interfejs umożliwiający interakcję z określonym kontenerem usługi Cosmos DB. Ta klasa nie powinna być tworzone bezpośrednio. Zamiast tego użyj metody get_container_client DatabaseProxy, aby uzyskać istniejący kontener lub metodę create_container w celu utworzenia nowego kontenera.

W poniższych przewodnikach pokazano, jak utworzyć aplikację przy użyciu każdej z tych klas.

Przewodnik	opis
Tworzenie bazy danych	Tworzenie baz danych
Tworzenie kontenera	Tworzenie kontenerów
Przykłady elementów	Punkt odczytu określonego elementu

Zobacz też

• PyPi
• Samples
• Dokumentacja interfejsu API
• Kod źródłowy biblioteki
• Prześlij opinię

Następne kroki

Po nawiązaniu połączenia z kontem interfejsu API dla noSQL użyj następnego przewodnika, aby utworzyć bazy danych i zarządzać nimi.

Tworzenie bazy danych w usłudze Azure Cosmos DB for NoSQL przy użyciu języka Python