本文說明如何使用 Python SDK 連線到適用於 NoSQL 的 Azure Cosmos DB。 連接後，對資料庫、容器和項目進行操作。
套件 （PyPi） | API 參考 | 程式庫原始碼 | 提供意見反應
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 了解如何 免費建立帳戶。
- Azure Cosmos DB for NoSQL 帳戶。 瞭解如何 建立 API for NoSQL 帳戶。
- Python 3.7 或更新版本。
- Azure Command-Line 介面 （CLI） 或 Azure PowerShell。
設定您的專案
為 Python 程式碼建立環境。
使用 虛擬環境 來獨立安裝 Python 套件，而不會影響您的系統。
在您的虛擬環境中安裝適用於 NoSQL 的 Azure Cosmos DB 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
若要連線到適用於 NoSQL 的 Azure Cosmos DB API，請建立類別的 CosmosClient 執行個體。 此類別是針對資料庫執行所有作業的起點。
若要使用 Microsoft Entra 連線到 NoSQL 帳戶的 API，請使用安全性主體。 主體的確切類型取決於您託管應用程式程式碼的位置。 下表是快速參考指南。
| 應用程式的執行位置 | 安全性主體 |
|---|---|
| 本機電腦 (開發和測試) | 使用者身分識別或服務主體 |
| 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之正確角色的詳細資訊，請參閱 使用 Microsoft Entra ID 為您的 Azure Cosmos DB 帳戶設定角色型存取控制。 特別是，請參閱建立角色並將其指派給主體識別碼這一章節。
建置您的 應用程式
當您建置應用程式時，您的程式碼主要與四種類型的資源互動：
API for NoSQL 帳戶是 Azure Cosmos DB 資料的唯一最上層命名空間。
資料庫，用於組織帳戶中的容器。
容器，其中包含資料庫中的一組個別項目。
項目，代表容器中的 JSON 文件。
此圖顯示這些資源之間的關係。
在頂端顯示 Azure Cosmos DB 帳戶的階層式圖表。 帳戶有兩個子資料庫節點。 其中一個資料庫節點包含兩個子容器節點。 另一個資料庫節點包含單一子容器節點。 該單一容器節點有三個子項目節點。
一或多個關聯的 Python 類別代表資源類型。 此清單顯示同步程式設計最常見的類別。 (在 azure.cosmos.aio 命名空間下，有類似的類別可用於非同程式設計。)
| 類別 | 描述 |
|---|---|
CosmosClient |
此類別提供適用於 Azure Cosmos DB 服務的用戶端邏輯表示法。 用戶端物件會設定並執行針對服務的請求。 |
DatabaseProxy |
服務中可能存在或無法存在的資料庫介面。 這個類別不應該直接具現化。 請改用 CosmosClient get_database_client 方法。 |
ContainerProxy |
與特定 Cosmos DB 容器互動的介面。 這個類別不應該直接具現化。 請改用 DatabaseProxy get_container_client 方法來取得現有的容器，或 create_container 方法來建立新的容器。 |
這些指南示範如何使用每個類別來建置應用程式。
| 指南 | 描述 |
|---|---|
| 建立資料庫 | 建立資料庫。 |
| 建立容器 | 建立容器。 |