免責聲明

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_items SQL 查詢，此 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 狀態碼：

Azure Cosmos DB 的 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。