免責聲明
Python 2.7 的 Azure SDK Python 套件支援已于 2022 年 1 月 1 日結束。 如需詳細資訊和問題，請參閱 https://github.com/Azure/azure-sdk-for-python/issues/20691
適用于 Python 的 Azure Cosmos DB SQL API 用戶端程式庫 - 4.5.1 版
Azure Cosmos DB 是全域散發、多模型資料庫服務，支援文件、索引鍵/值組、寬列資料行及圖形資料庫。
使用適用于 Python 的 Azure Cosmos DB SQL API SDK 來管理資料庫及其包含在此 NoSQL 資料庫服務中的 JSON 檔。 高階功能包括：
- 建立 Cosmos DB 資料庫 並修改其設定
- 建立和修改 容器 以儲存 JSON 檔的集合
- 在容器中建立、讀取、更新和刪除 JSON 檔 (專案)
- 使用類似 SQL 的語法查詢資料庫中的檔
SDK 原始程式碼 | 套件 (PyPI) | 封裝 (Conda) | API 參考檔 | 產品檔 | 樣品
此 SDK 用於 SQL API。 如需所有其他 API，請參閱 Azure Cosmos DB 檔 ，以評估您專案的最佳 SDK。
開始使用
Python 2.x 支援的重要更新
從 2022 年 1 月 1 日開始，此 SDK 的新版本不再支援 Python 2.x。 請檢查 CHANGELOG 以取得詳細資訊。
必要條件
- Azure 訂用帳戶 - 建立免費帳戶
- Azure Cosmos DB 帳戶 - SQL API
- Python 3.6+
如果您需要 Cosmos DB SQL API 帳戶，您可以使用此 Azure CLI 命令來建立帳戶：
az cosmosdb create --resource-group <resource-group-name> --name <cosmos-account-name>
安裝套件
pip install azure-cosmos
設定虛擬環境 (選擇性)
如果您使用虛擬環境，則可以讓基底系統與 Azure SDK 環境彼此隔離，但您不一定要這麼做。 執行下列命令來設定，然後使用 venv輸入虛擬環境：
python3 -m venv azure-cosmosdb-sdk-environment
source azure-cosmosdb-sdk-environment/bin/activate
驗證用戶端
與 Cosmos DB 的互動是從 CosmosClient 類別的實例開始。 您需要 帳戶、其 URI和其中一個 帳戶金鑰 ，才能具現化用戶端物件。
使用下列 Azure CLI 程式碼片段，將資料庫帳戶 URI 及其主要金鑰填入兩個環境變數， (您也可以在Azure 入口網站) 中找到這些值。 此程式碼片段會針對 Bash Shell 加以格式化。
RES_GROUP=<resource-group-name>
ACCT_NAME=<cosmos-db-account-name>
export ACCOUNT_URI=$(az cosmosdb show --resource-group $RES_GROUP --name $ACCT_NAME --query documentEndpoint --output tsv)
export ACCOUNT_KEY=$(az cosmosdb list-keys --resource-group $RES_GROUP --name $ACCT_NAME --query primaryMasterKey --output tsv)
建立用戶端
填入 ACCOUNT_URI 和 ACCOUNT_KEY 環境變數之後，您可以建立 CosmosClient。
from azure.cosmos import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
AAD 驗證
您也可以使用服務主體的 AAD 認證和 Azure 身分識別套件來驗證用戶端。 您可以直接將認證資訊傳遞至 ClientSecretCredential，或使用 DefaultAzureCredential：
from azure.cosmos import CosmosClient
from azure.identity import ClientSecretCredential, DefaultAzureCredential
import os
url = os.environ['ACCOUNT_URI']
tenant_id = os.environ['TENANT_ID']
client_id = os.environ['CLIENT_ID']
client_secret = os.environ['CLIENT_SECRET']
# Using ClientSecretCredential
aad_credentials = ClientSecretCredential(
tenant_id=tenant_id,
client_id=client_id,
client_secret=client_secret)
# Using DefaultAzureCredential (recommended)
aad_credentials = DefaultAzureCredential()
client = CosmosClient(url, aad_credentials)
請務必確定您用於 AAD 驗證的受控識別具有 readMetadata 許可權。
有關如何設定 AAD 驗證的詳細資訊： 設定 AAD 驗證的 RBAC
AAD 已驗證用戶端允許作業的詳細資訊： RBAC 許可權模型
重要概念
當您將 CosmosClient 初始化之後，便能與 Cosmos DB 中的主要資源類型互動：
資料庫：一個 Cosmos DB 帳戶可以包含多個資料庫。 在建立資料庫時，您可以指定在與資料庫內文件互動時想使用的 API：SQL、MongoDB、Gremlin、Cassandra 或 Azure Table。 使用 DatabaseProxy 物件來管理其容器。
容器：容器是 JSON 文件的集合。 您可以使用 ContainerProxy 物件上的方法，在容器中建立 (插入) 、讀取、更新和刪除專案。
專案：專案是儲存在容器中的 JSON 檔的字典標記法。 您新增至容器的每個專案都必須包含索引鍵，其中包含可唯一
id識別容器內專案的值。
如需這些資源的詳細資訊，請參閱使用 Azure Cosmos 資料庫、容器和項目。
如何使用 enable_cross_partition_query
keyword-argument enable_cross_partition_query 接受 2 個選項： None (預設) 或 True 。
依識別碼使用查詢的注意事項
使用嘗試根據 識別碼 值尋找專案的查詢時，請一律確定您傳入字串類型變數。 Azure Cosmos DB 只允許字串識別碼值，如果您使用任何其他資料類型，則此 SDK 不會傳回任何結果，也不會傳回任何錯誤訊息。
用戶端一致性層級的注意事項
從 4.3.0b3 版開始，如果使用者未將明確一致性層級傳入其用戶端初始化，則其用戶端會使用其資料庫帳戶的預設層級。 先前，預設值已設定為 Session 一致性。
如果基於某些原因而想要繼續執行此動作，您可以變更用戶端初始化，以包含此的明確參數，如下所示：
from azure.cosmos import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY, consistency_level='Session')
限制
目前 不支援下列功能。 如需替代選項，請查看下方 的因應措施 一節。
資料平面限制：
- 依查詢分組
- 來自 DISTINCT 子查詢的 COUNT 查詢：SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
- 大量/交易式批次處理
- 直接 TCP 模式存取
- 匯總跨分割區查詢的接續權杖支援，例如排序、計數和相異。
可串流查詢，例如
SELECT * FROM WHERE支援接續權杖。 - 變更摘要：處理器
- 變更摘要：讀取多個分割區索引鍵值
- 變更摘要：讀取特定時間
- 變更摘要：從頭讀取
- 變更摘要：提取模型
- 混合類型的跨分割區 ORDER BY
- 啟用非同步查詢類型方法的診斷
控制平面限制：
- 取得 CollectionSizeUsage、DatabaseUsage 和 DocumentUsage 計量
- 建立地理空間索引
- 取得連接字串
- 取得容器的最低 RU/秒
因應措施
大量處理限制因應措施
如果您想要使用 Python SDK 對 Cosmos DB 執行大量插入，最佳替代方法是使用 預存程式 來寫入具有相同分割區索引鍵的多個專案。
控制平面限制因應措施
一般而言，您可以針對控制平面不支援的限制，使用 Azure 入口網站、 Azure Cosmos DB 資源提供者 REST API、 Azure CLI 或 PowerShell 。
Boolean 資料類型
雖然 Python 語言對布林類型 使用 「True」 和 「False」，但 Cosmos DB 只 接受 「true」 和 「false」。 換句話說，Python 語言會使用具有第一個大寫字母和所有其他小寫字母的布林值，而 Cosmos DB 及其 SQL 語言只針對相同的布林值使用小寫字母。 如何處理這項挑戰？
- 使用 Python 建立的 JSON 檔必須使用 「True」 和 「False」，才能通過語言驗證。 SDK 會為您轉換為 「true」 和 「false」。 這表示 「true」 和 「false」 會儲存在 Cosmos DB 中。
- 如果您使用 Cosmos DB 入口網站的Data Explorer來擷取這些檔，您會看到 「true」 和 「false」。
- 如果您使用這個 Python SDK 擷取這些檔，則 「true」 和 「false」 值會自動轉換成 「True」 和 「False」。
SQL 查詢 x FROM 子句子專案
此 SDK 會使用 query_items 方法， 將 SQL 查詢提交至 Azure Cosmos DB。
Cosmos DB SQL 語言可讓您 使用 FROM 子句來取得子專案，以將來源縮減為較小的子集。 例如，您可以使用 select * from Families.children ， select * from Families 而不是 。 但請注意：
- 對於使用 方法的
query_itemsSQL 查詢，此 SDK 會要求您指定partition_key或使用enable_cross_partition_query旗標。 - 如果您要取得子專案並指定
partition_key，請確定您的分割區索引鍵包含在子專案中，這在大部分情況下並不成立。
最大項目計數
這是query_items方法的參數，整數表示每個頁面要傳回的專案數上限。 None您可以指定 值，讓服務判斷最佳專案計數。 這是建議的組態值，如果未設定此 SDK 的預設行為。
範例
下列各節提供數個程式碼片段，內容涵蓋一些最常見的 Cosmos DB 工作，包括：
建立資料庫
驗證 CosmosClient 之後，您便能使用帳戶中的任何資源。 下列程式碼片段會建立 SQL API 資料庫，這是叫用 create_database 時未指定 API 時的預設值。
from azure.cosmos import CosmosClient, exceptions
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
try:
database = client.create_database(DATABASE_NAME)
except exceptions.CosmosResourceExistsError:
database = client.get_database_client(DATABASE_NAME)
建立容器
此範例會建立具有預設設定的容器。 如果資料庫中已經有相同名稱的容器， (產生 409 Conflict 錯誤) ，則會改為取得現有的容器。
from azure.cosmos import CosmosClient, PartitionKey, exceptions
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
try:
container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
except exceptions.CosmosResourceExistsError:
container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
raise
建立啟用分析存放區的容器
此範例會建立已啟用分析存放區的容器，以供報表、BI、AI 和 Advanced Analytics 與Azure Synapse Link使用。
analytical_storage_ttl的選項如下：
- 0 或 Null 或未通知：未啟用。
- -1：資料會無限地儲存。
- 任何其他數位：實際 ttl，以秒為單位。
CONTAINER_NAME = 'products'
try:
container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"),analytical_storage_ttl=-1)
except exceptions.CosmosResourceExistsError:
container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
raise
如果容器建立失敗，上述程式碼片段也會處理 CosmosHttpResponseError 例外狀況。 如需錯誤處理和疑難排解的詳細資訊，請參閱 一 節。
取得現有的容器
從資料庫擷取現有的容器：
from azure.cosmos import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)
差入資料
若要將專案插入容器中，請將包含資料的字典傳遞至 ContainerProxy.upsert_item。 您新增至容器的每個專案都必須包含索引鍵，其中包含可唯一 id 識別容器內專案的值。
此範例會將數個專案插入容器中，每個專案都有唯 id 一的 ：
from azure.cosmos import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)
for i in range(1, 10):
container.upsert_item({
'id': 'item{0}'.format(i),
'productName': 'Widget',
'productModel': 'Model {0}'.format(i)
}
)
刪除資料
若要從容器中刪除專案，請使用 ContainerProxy.delete_item。 Cosmos DB 中的 SQL API 不支援 SQL DELETE 語句。
from azure.cosmos import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)
for item in container.query_items(
query='SELECT * FROM products p WHERE p.productModel = "Model 2"',
enable_cross_partition_query=True):
container.delete_item(item, partition_key='Widget')
注意：如果您使用資料分割集合，則上述範例程式碼中的 值
partitionKey應該設定為此特定專案的分割區索引鍵值，而不是集合中資料分割索引鍵資料行的名稱。 這適用于點讀取和刪除。
查詢資料庫
Cosmos DB SQL API 資料庫支援使用類似 SQL 語法 ContainerProxy.query_items 查詢容器中的專案。
此範例會查詢具有特定 id 之專案的容器：
from azure.cosmos import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)
# Enumerate the returned items
import json
for item in container.query_items(
query='SELECT * FROM mycontainer r WHERE r.id="item3"',
enable_cross_partition_query=True):
print(json.dumps(item, indent=True))
注意：雖然您可以在 子句中
FROM指定容器名稱的任何值，但建議您使用容器名稱來保持一致性。
傳遞包含參數及其值的字典，以執行參數化查詢 ，以ContainerProxy.query_items：
discontinued_items = container.query_items(
query='SELECT * FROM products p WHERE p.productModel = @model',
parameters=[
dict(name='@model', value='Model 7')
],
enable_cross_partition_query=True
)
for item in discontinued_items:
print(json.dumps(item, indent=True))
如需使用 SQL API 查詢 Cosmos DB 資料庫的詳細資訊，請參閱使用 SQL 查詢進行 Azure Cosmos DB 資料查詢。
取得資料庫屬性
取得並顯示資料庫的屬性：
from azure.cosmos import CosmosClient
import os
import json
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
properties = database.read()
print(json.dumps(properties))
取得資料庫和容器輸送量
取得並顯示資料庫和具有專用輸送量之容器的輸送量值：
from azure.cosmos import CosmosClient
import os
import json
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
# Database
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
db_offer = database.read_offer()
print('Found Offer \'{0}\' for Database \'{1}\' and its throughput is \'{2}\''.format(db_offer.properties['id'], database.id, db_offer.properties['content']['offerThroughput']))
# Container with dedicated throughput only. Will return error "offer not found" for containers without dedicated throughput
CONTAINER_NAME = 'testContainer'
container = database.get_container_client(CONTAINER_NAME)
container_offer = container.read_offer()
print('Found Offer \'{0}\' for Container \'{1}\' and its throughput is \'{2}\''.format(container_offer.properties['id'], container.id, container_offer.properties['content']['offerThroughput']))
修改容器屬性
您可以修改現有容器的特定屬性。 本範例會將容器中專案的預設存留時間設定為 10 秒 (TTL) ：
from azure.cosmos import CosmosClient, PartitionKey
import os
import json
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)
database.replace_container(
container,
partition_key=PartitionKey(path="/productName"),
default_ttl=10,
)
# Display the new TTL setting for the container
container_props = container.read()
print(json.dumps(container_props['defaultTtl']))
如需 TTL 的詳細資訊，請參閱 Azure Cosmos DB 資料的存留時間。
使用非同步用戶端
非同步 cosmos 用戶端是個別的用戶端，其外觀和運作方式與現有的同步用戶端類似。 不過，非同步用戶端必須個別匯入，而且其方法必須與 async/await 關鍵字搭配使用。 非同步用戶端必須在使用之後初始化和關閉，這可以手動完成或使用內容管理員。 下列範例示範如何手動執行這項操作。
from azure.cosmos.aio import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'
async def create_products():
client = CosmosClient(URL, credential=KEY)
database = client.get_database_client(DATABASE_NAME)
container = database.get_container_client(CONTAINER_NAME)
for i in range(10):
await container.upsert_item({
'id': 'item{0}'.format(i),
'productName': 'Widget',
'productModel': 'Model {0}'.format(i)
}
)
await client.close() # the async client must be closed manually if it's not initialized in a with statement
強烈建議使用 async with 關鍵字，而不是手動開啟和關閉用戶端。 這會建立內容管理員，此管理員會在您離開 語句之後初始化用戶端，稍後關閉用戶端。 下列範例示範如何執行這項操作。
from azure.cosmos.aio import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'
async def create_products():
async with CosmosClient(URL, credential=KEY) as client: # the with statement will automatically initialize and close the async client
database = client.get_database_client(DATABASE_NAME)
container = database.get_container_client(CONTAINER_NAME)
for i in range(10):
await container.upsert_item({
'id': 'item{0}'.format(i),
'productName': 'Widget',
'productModel': 'Model {0}'.format(i)
}
)
使用非同步用戶端進行查詢
不同于同步用戶端，非同步用戶端在要求中沒有 enable_cross_partition 旗標。 沒有指定資料分割索引鍵值的查詢預設會嘗試執行跨資料分割查詢。
您可以逐一查看查詢結果，但查詢的原始輸出會傳回非同步反覆運算器。 這表示反覆運算器中的每個物件都是可等候的物件，而且尚未包含真正的查詢結果。 若要取得查詢結果，您可以使用 async for 迴圈，它會在您逐一查看物件時等候每個結果，或在逐一查看非同步反覆運算器時手動等候每個查詢結果。
由於查詢結果是非同步反覆運算器，因此無法直接轉換成清單;相反地，如果您需要從結果建立清單，請使用 async for 迴圈或 Python 的清單理解來填入清單：
from azure.cosmos.aio import CosmosClient
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)
async def create_lists():
results = container.query_items(
query='SELECT * FROM products p WHERE p.productModel = "Model 2"')
# iterates on "results" iterator to asynchronously create a complete list of the actual query results
item_list = []
async for item in results:
item_list.append(item)
# Asynchronously creates a complete list of the actual query results. This code performs the same action as the for-loop example above.
item_list = [item async for item in results]
await client.close()
使用整合式快取
整合式快取是記憶體內部快取，可協助您在要求磁片區成長時確保可管理的成本和低延遲。 整合式快取有兩個部分：點讀取的專案快取，以及查詢的查詢快取。 下列程式碼片段示範如何搭配點讀取和查詢快取方法使用此功能。
使用這項功能的優點是，叫用整合式快取的點讀取和查詢不會使用任何 RU。 這表示您會比從後端讀取的作業成本低很多。
如何設定 Azure Cosmos DB 整合式快取 (預覽)
import azure.cosmos.cosmos_client as cosmos_client
import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = cosmos_client.CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'testContainer'
container = database.get_container_client(CONTAINER_NAME)
def integrated_cache_snippet():
item_id = body['id']
query = 'SELECT * FROM c'
#item cache
container.read_item(item=item_id, partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)
#query cache
container.query_items(query=query,
partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)
如需整合式快取的詳細資訊，請參閱 Azure Cosmos DB 整合式快取 - 概觀。
疑難排解
一般
當您使用 Python SDK 與 Cosmos DB 互動時，服務所傳回的例外狀況會對應至針對 REST API 要求傳回的相同 HTTP 狀態碼：
例如，如果您嘗試使用已在 Cosmos DB 資料庫中使用的識別碼 (名稱) 建立容器， 409 則會傳回錯誤，指出衝突。 下列程式碼片段會藉由攔截例外狀況並顯示錯誤的其他相關資訊，來適當地處理錯誤。
try:
database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
except exceptions.CosmosResourceExistsError:
print("""Error creating container
HTTP status code 409: The ID (name) provided for the container is already in use.
The container name must be unique within the database.""")
記錄
此程式庫會使用標準記錄程式庫進行 記錄 。 HTTP 會話的基本資訊 (URL、標頭等。) 會記錄在 INFO 層級。
您可以在具有 引數的用戶端 logging_enable 上啟用詳細的 DEBUG 層級記錄，包括要求/回應主體和未回應標頭：
import sys
import logging
from azure.cosmos import CosmosClient
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)
# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CosmosClient(URL, credential=KEY, logging_enable=True)
同樣地，logging_enable 可對單一作業啟用詳細記錄，即使未對用戶端啟用也可行：
database = client.create_database(DATABASE_NAME, logging_enable=True)
或者，您可以使用 CosmosHttpLoggingPolicy 進行記錄，其會透過將記錄器傳入自 logger 變數，從 azure 核心 HttpLoggingPolicy 擴充。
根據預設，它會使用來自 HttpLoggingPolicy 的行為。 傳入 自 enable_diagnostics_logging 變數將會啟用 CosmosHttpLoggingPolicy，並在回應中具有與 Cosmos 問題相關的其他資訊。
import logging
from azure.cosmos import CosmosClient
#Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
# Configure a file output
handler = logging.FileHandler(filename="azure")
logger.addHandler(handler)
# This client will log diagnostic information from the HTTP session by using the CosmosHttpLoggingPolicy.
# Since we passed in the logger to the client, it will log information on every request.
client = CosmosClient(URL, credential=KEY, logger=logger, enable_diagnostics_logging=True)
同樣地，您可以藉由將記錄器傳入單一要求來啟用單一作業的記錄。
不過，如果您想要使用 CosmosHttpLoggingPolicy 取得其他資訊， enable_diagnostics_logging 則必須在用戶端建構函式中傳入 引數。
# This example enables the CosmosHttpLoggingPolicy and uses it with the `logger` passed in to the `create_database` request.
client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
database = client.create_database(DATABASE_NAME, logger=logger)
遙測
Azure Core 可讓 Python SDK 搭配使用 OpenTelemetry。 唯一需要安裝才能使用此功能的套件如下：
pip install azure-core-tracing-opentelemetry
pip install opentelemetry-sdk
如需詳細資訊，建議您從 Azure Core 查看此 檔 ，說明如何設定。 我們也新增 了範例檔案 ，以顯示它如何與 SDK 搭配使用。 不論您使用的 Cosmos 用戶端為何，這都能以相同方式運作。
後續步驟
如需 Cosmos DB 服務的更多詳細文件，請參閱 docs.microsoft.com 上的 Azure Cosmos DB 文件。
參與
此專案歡迎參與和提供建議。 大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。 如需詳細資料，請前往 https://cla.microsoft.com 。
當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。 請遵循 bot 提供的指示。 您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。
此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。 如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應