共用方式為

針對搭配適用於 NoSQL 帳戶的 API 使用 Azure Cosmos DB Python SDK 時的問題進行疑難解答

  • 發行項

適用於：NoSQL

重要

本文僅涵蓋 Azure Cosmos DB Python SDK 的疑難解答。 如需詳細資訊，請參閱 Azure Cosmos DB Python SDK 自述檔版本資訊、套件（PyPI）、套件（Conda）和效能秘訣。

本文涵蓋當您搭配適用於 NoSQL 帳戶的 Azure Cosmos DB Python SDK 使用 Azure Cosmos DB Python SDK 時的常見問題、因應措施、診斷步驟和工具。 Azure Cosmos DB Python SDK 提供用戶端邏輯表示法，以存取適用於 NoSQL 的 Azure Cosmos DB。 此文章所說明的工具和方法，可以在您遇到任何問題時提供協助。

從此清單開始：

  • 查看此文章的常見問題和因應措施一節。
  • 查看 Azure Cosmos DB 中央存放庫中的 Python SDK，其可在 GitHub 上 開放原始碼 使用。 它有受到主動監視的議題區段。 查看您是否有任何含有已提出因應措施的類似問題。 其中一個有用的秘訣是依 *Cosmos* 標記來篩選問題。
  • 檢閱 Azure Cosmos DB Python SDK 的效能秘訣 ，並遵循建議的做法。
  • 如果找不到解決方案，請閱讀本文的其餘部分。 然後提出 GitHub 問題。 如果有選項可將標籤新增至您的 GitHub 問題，則請新增 *Cosmos* 標記。

記錄和擷取診斷

重要

我們建議使用最新版本的 Python SDK。 您可以在這裏檢查發行歷程記錄

此連結庫會使用標準 記錄 連結庫來記錄診斷。 關於 HTTP 工作階段的基本資訊 (URL、標頭等) 會記錄在「資訊」層級。

您可以在具有 自變數的用戶端 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從 azure 核心 HttpLoggingPolicy延伸的 logger 來記錄。 根據預設，它會使用 來自 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)

重試設計

如需如何設計具復原性應用程式的指導，並瞭解 SDK 的重試語意，請參閱使用 Azure Cosmos DB SDK 設計具復原性的應用程式指南。

常見問題和因應措施

一般建議

若要獲得最佳效能︰

  • 確定應用程式會在與您 Azure Cosmos DB 帳戶相同的區域上執行。
  • 在應用程式執行所在的主機上檢查 CPU 使用量。 如果 CPU 使用量為 50% 或更高，請在具有更高組態的主機上執行您的應用程式。 或者，您可將負載分散於更多電腦上。

檢查入口網站計量

檢查入口網站計量有助於判斷是否為用戶端問題，或者服務是否有問題。 例如，如果計量包含高比率的速率限制要求 (HTTP 狀態碼 429)，這表示要求正在進行節流處理，然後檢查要求率太大區段。

連線節流

連線節流可能會因為 [主計算機上的連線限制] 或 [Azure SNAT （PAT） 埠耗盡] 而發生。

主機電腦的連線限制

某些 Linux 系統 (例如 Red Hat) 具有開啟檔案的總數上限。 Linux 中的通訊端會實作為檔案，因此，這個數字也會限制連線總數。 執行下列命令。

ulimit -a

允許的開啟檔案數目上限 (識別為 "nofile") 必須至少是連線集區大小的兩倍。 如需詳細資訊，請參閱 Azure Cosmos DB Python SDK 效能秘訣。

Azure SNAT (PAT) 連接埠耗盡

如果您的應用程式部署於不具公用 IP 位址的 Azure 虛擬機器上，則 Azure SNAT 連接埠預設會建立與您 VM 外部任何端點的連線。 從 VM 到 Azure Cosmos DB 端點所允許的連線數目會受到 Azure SNAT 設定所限制。

只有在您的 VM 具有私人 IP 位址，而且來自 VM 的程序嘗試連線到公用 IP 位址時，才會使用 Azure SNAT 連接埠。 有兩種因應措施可避免 Azure SNAT 限制：

  • 將 Azure Cosmos DB 服務端點新增至您的 Azure 虛擬機器虛擬網路。 如需詳細資訊，請參閱 Azure 虛擬網路服務端點。

    啟用服務端點時，要求不再會從公用 IP 傳送到 Azure Cosmos DB。 改為傳送虛擬網路和子網路身分識別。 如果只允許公用 IP，此變更可能會導致防火牆卸除。 如果您使用防火牆，當您啟用服務端點時，請使用虛擬網路 ACL 將子網路新增至防火牆。

  • 將公用 IP 指派給您的 Azure VM。

無法連線到服務 - 防火牆

azure.core.exceptions.ServiceRequestError: 指出 SDK 無法連線服務。 遵循主電腦上的連線限制。

聯機到 Azure Cosmos DB 模擬器失敗

Azure Cosmos DB 模擬器的 HTTPS 憑證是自我簽署的。 若要讓 Python SDK 使用模擬器，請匯入模擬器憑證。 如需詳細資訊，請參閱匯出 Azure Cosmos DB 模擬器憑證。

HTTP Proxy

如果您使用 HTTP Proxy，請確定它可以支援在 SDK ConnectionPolicy 中設定的連線數目。 否則就會遇到連線問題。

常見的查詢問題

查詢計量有助於判斷查詢耗費大部分時間的位置。 您可以從查詢計量查看在後端與用戶端花費多少時間。 深入了解查詢效能指南。

下一步