Share via

開始使用 Azure Cosmos DB for NoSQL 和 Python

  • 發行項

適用於：NoSQL

本文說明如何透過 Python SDK 與 Azure Cosmos DB for NoSQL 連線。 連線之後，您即可在資料庫、容器和項目上執行作業。

套件 (PyPi) | 範例 | API 參考 | 程式庫原始程式碼 | 提供意見反應

必要條件

設定您的專案

建立可以執行 Python 程式碼的環境。

透過虛擬環境，您可以在隔離的環境中安裝 Python 套件，而不會影響系統的其餘部分。

在虛擬環境中安裝適用於 Azure Cosmos DB for NoSQL 的 Python SDK。

pip install azure-cosmos

建立 Python 應用程式

在您的環境中，建立新的 app.py 檔案，並將下列程式碼新增至其中：

import json
import os
import sys
import uuid

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

上述程式碼會匯入您將在本文其餘部分使用的模組。

連線至 Azure Cosmos DB for NoSQL

若要連線到 Azure Cosmos DB 的 API for NoSQL，請建立 CosmosClient 類別的執行個體。 此類別是針對資料庫執行所有作業的起點。 使用 CosmosClient 類別連線到 API for NoSQL 帳戶有三種方法：

與端點和金鑰連線

CosmosClient 建構函式有兩個必要參數：

參數 範例值 描述
url COSMOS_ENDPOINT 環境變數 供所有要求使用的 API for NoSQL 端點。
credential COSMOS_KEY 環境變數 驗證時要使用的帳戶金鑰或資源權杖。

擷取您的帳戶端點和金鑰

  1. 建立 resourceGroupName 的殼層變數。

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

  2. 使用 az cosmosdb list 命令來擷取資源群組中第一個 Azure Cosmos DB 帳戶的名稱，並將其儲存在 accountName 殼層變數中。

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

  3. 使用 az cosmosdb show 命令取得帳戶的 API for NoSQL 端點 URI。

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

  4. 使用 az-cosmosdb-keys-list 命令，從帳戶的金鑰清單中尋找 PRIMARY KEY。

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

  5. 記錄 URI 和 PRIMARY KEY 值。 之後您將需要這些認證。

若要在 Python 程式碼中使用 URI 和 PRIMARY KEY 值，請將其保存在執行應用程式本機電腦上新的環境變數中。

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

使用帳戶端點和金鑰建立 CosmosClient

使用 COSMOS_ENDPOINT 和 COSMOS_KEY 環境變數作為參數，建立 CosmosClient 類別的新執行個體。

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

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

使用連接字串來連線

CosmosClient 類別具有 from_connection_string 方法，可用來與一個必要參數連線：

參數 範例值 描述
conn_str COSMOS_CONNECTION_STRING 環境變數 API for NoSQL 帳戶的連接字串.
credential COSMOS_KEY 環境變數 選用的替代帳戶金鑰或資源權杖，用來取代連接字串中的密鑰或資源權杖。

擷取您的帳戶連接字串

  1. 使用 az cosmosdb list 命令來擷取資源群組中第一個 Azure Cosmos DB 帳戶的名稱，並將其儲存在 accountName 殼層變數中。

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

  2. 使用 az-cosmosdb-keys-list 命令，從帳戶的連接字串清單中尋找 PRIMARY CONNECTION STRING。

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

若要在 Python 程式碼中使用 PRIMARY CONNECTION STRING 值，請將其保存在執行應用程式的本機電腦上新的環境變數。

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

使用連接字串建立 CosmosClient

使用 COSMOS_CONNECTION_STRING 環境變數作為唯一參數，建立 CosmosClient 類別的新執行個體。

CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]

client = CosmosClient.from_connection_string(conn_str=CONN_STR)

使用 Microsoft 身分識別平台進行連線

若要使用 Microsoft 身分識別平台和 Microsoft Entra ID 與您的 API for NoSQL 帳戶連線，請使用安全性主體。 主體的確切類型取決於您裝載應用程式程式碼的位置。 下表可作為快速參考指南。

應用程式的執行位置 安全性主體
本機電腦 (開發和測試) 使用者身分識別或服務主體
Azure 受控識別
Azure 外部的伺服器或用戶端 服務主體

匯入 Azure.Identity

Azure.Identity 套件包含所有 Azure SDK 程式庫之間共用的核心驗證功能。

將 azure-identity 套件匯入您的環境中。

pip install azure-identity

使用預設認證實作建立 CosmosClient

如果您要在本機電腦上進行測試，或應用程式將在 Azure 服務上執行，並直接支援受控識別，請建立 DefaultAzureCredential 執行個體以取得 OAuth 權杖。

在您的 app.py 中：

  • 取得要連線的端點，如上一節使用端點和密鑰進行連線 所示，並將其設定為環境變數 COSMOS_ENDPOINT。

  • 匯入 DefaultAzureCredential 並建立其執行個體。

  • 使用 ENDPOINT 和 認證作為參數，建立 CosmosClient 類別的新執行個體。

from azure.identity import DefaultAzureCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]

credential = DefaultAzureCredential()

client = CosmosClient(ENDPOINT, credential)

重要

如需如何新增正確角色以啟用 DefaultAzureCredential 的詳細資訊，請參閱 為您的 Azure Cosmos DB 帳戶使用 Microsoft Entra ID 設定角色型存取控制。 特別是，請參閱建立角色並將其指派給主體識別碼這一章節。

使用自訂的認證實作建立 CosmosClient

如果您規劃將應用程式部署至 Azure 外部，可以使用適用於 Python 的 Azure 身分識別用戶端程式庫中的其他類別，來取得 OAuth 權杖。 這些其他類別也是衍生自 TokenCredential 類別。

在此範例中，我們會使用用戶端和租用戶識別碼以及用戶端密碼來建立 ClientSecretCredential 執行個體。

在您的 app.py 中：

  • 從服務主體的環境變數取得認證資訊。 在 Microsoft Entra ID 中註冊應用程式時，您可以取得用戶端識別碼、租用戶識別碼和用戶端密碼。 如需註冊 Microsoft Entra 應用程式的詳細資訊，請參閱使用 Microsoft 身分識別平台註冊應用程式。

  • 匯入 ClientSecretCredential ，並使用 TENANT_ID、 CLIENT_ID和 CLIENT_SECRET 環境變數作為參數來建立執行個體。

  • 使用 ENDPOINT 和 認證作為參數，建立 CosmosClient 類別的新執行個體。

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)

建置您的 應用程式

組建應用程式時，程式碼主要與四種資源互動：

  • API for NoSQL 帳戶是 Azure Cosmos DB 資料的唯一最上層命名空間。

  • 資料庫，用於組織帳戶中的容器。

  • 容器，其中包含資料庫中的一組個別項目。

  • 項目，代表容器中的 JSON 文件。

下圖顯示資源之間的關係。

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

每種資源以一或多個相關聯的 Python 類別來表示。 以下是同步程式設計最常見的類別清單。 (在 azure.cosmos.aio 命名空間下，有類似的類別可用於非同程式設計。)

類別 描述
CosmosClient 此類別提供適用於 Azure Cosmos DB 服務的用戶端邏輯表示法。 用戶端物件會用於設定及執行針對服務的要求。
DatabaseProxy 服務中的介面可能存在或不存在資料庫參考。 這個類別不應該直接具現化。 您應該改用 CosmosClient get_database_client 方法。
ContainerProxy 與特定 Cosmos DB 容器互動的介面。 這個類別不應該直接具現化。 請改用 DatabaseProxy get_container_client 方法來取得現有的容器，或 create_container 方法來建立新的容器。

下列指南說明如何以上每個類別來組建應用程式。

指南 描述
建立資料庫 建立資料庫
建立容器 建立容器
項目範例 點讀取特定項目

另請參閱

下一步

既然您已連線到 API for NoSQL 帳戶，請使用下一個指南來建立和管理資料庫。

使用 Python 在 Azure Cosmos DB for NoSQL 中建立資料庫