在 Azure Data Factory 和 Azure Synapse Analytics 中針對 Azure Cosmos DB 連接器進行疑難排解

適用於:Azure Data Factory Azure Synapse Analytics

本文提供建議,協助在 Azure Data Factory 和 Azure Synapse Analytics 中針對 Azure Cosmos DB 和 Azure Cosmos DB (SQL API) 連接器的常見問題進行疑難排解。

錯誤訊息:要求大小太大

  • 徵兆:將資料複製到有預設寫入批次大小的 Azure Cosmos DB 時,發生下列錯誤:Request size is too large.

  • 原因:Azure Cosmos DB 將單一要求的大小限制為 2 MB。 公式為「要求大小 = 單一文件大小 * 寫入批次大小」。 如果文件很大,預設行為會產生太大的要求。 您可以調整寫入批次大小。

  • 解決:在複製活動接收器中,降低「寫入批次大小」值 (預設值為 10000)。

錯誤訊息:唯一索引限制違規

  • 徵兆:將資料複製到 Azure Cosmos DB 時發生下列錯誤:

    Message=Partition range id 0 | Failed to import mini-batch. Exception was Message: {"Errors":["Encountered exception while executing function. Exception = Error: {\"Errors\":[\"Unique index constraint violation.\"]}...

  • 原因︰有兩個可能的原因:

    • 原因 1:如果使用 Insert 作為寫入行為,此錯誤表示來源資料中有資料列或物件具有相同識別碼。
    • 原因 2:如果使用 Upsert 作為寫入行為,並將另一個唯一索引鍵設定為容器,此錯誤表示來源資料中有資料列和物件具有不同識別碼,但定義的唯一索引鍵有相同的值。
  • 解決方案

    • 若為原因 1,請將 Upsert 設定為寫入行為。
    • 若為原因 2,請確定每個文件中定義的唯一索引鍵有不同的值。

錯誤訊息:要求率非常大

  • 徵兆:將資料複製到 Azure Cosmos DB 時發生下列錯誤:

    Type=Microsoft.Azure.Documents.DocumentClientException, Message=Message: {"Errors":["Request rate is large"]}

  • 原因:使用的要求單位 (RU) 數目大於 Azure Cosmos DB 中設定的可用 RU。 若要了解 Azure Cosmos DB 如何計算 RU,請參閱 Azure Cosmos DB 中的要求單位

  • 解決:嘗試下列兩種解決方案之一:

    • 在 Azure Cosmos DB 中提高「容器 RU」數目的值。 此解決方案可提升複製活動效能,但在 Azure Cosmos DB 中會增加成本。
    • 降低 writeBatchSize 的值,例如 1000,降低 parallelCopies 的值,例如 1。 此解決方案會降低複製執行效能,但在 Azure Cosmos DB 中不會增加成本。

資料行對應中遺漏資料行

  • 徵兆:匯入 Azure Cosmos DB 的結構描述來對應資料行時,遺漏某些資料行。

  • 原因:Azure Data Factory 和 Synapse 管線根據前 10 個 Azure Cosmos DB 文件來推斷結構描述。 如果某些文件資料行或屬性沒有值,則偵測不到結構描述,也就不會顯示結構描述。

  • 解決:您可以微調查詢,如下列程式碼所示,強制結果集以空白值顯示資料行值。 假設前 10 個文件中遺漏 impossible 資料行。 或者,您可以手動新增資料行來進行對應。

    select c.company, c.category, c.comments, (c.impossible??'') as impossible from c
    

錯誤訊息:讀取器的 GuidRepresentation 是 CSharpLegacy

  • 徵兆:從具有通用唯一識別碼 (UUID) 欄位的 Azure Cosmos DB MongoAPI 或 MongoDB 複製資料時,發生下列錯誤:

    Failed to read data via MongoDB client., Source=Microsoft.DataTransfer.Runtime.MongoDbV2Connector,Type=System.FormatException, Message=The GuidRepresentation for the reader is CSharpLegacy which requires the binary sub type to be UuidLegacy not UuidStandard.,Source=MongoDB.Bson,’“,

  • 原因︰以二進位 JSON (BSON) 表達 UUID 有兩種方式:UuidStardard 和 UuidLegacy。 根據預設,UuidLegacy 會用來讀取資料。 如果 MongoDB 中的 UUID 資料是 UuidStandard,則會發生錯誤。

  • 解決:在 MongoDB 連接字串中,新增 uuidRepresentation=standard 選項。 如需詳細資訊,請參閱 MongoDB 連接字串

錯誤碼:CosmosDbSqlApiOperationFailed

  • 訊息CosmosDbSqlApi operation Failed. ErrorMessage: %msg;.

  • 原因:CosmosDbSqlApi 作業發生問題。 特別是指 Cosmos DB (SQL API) 連接器。

  • 建議:若要查看錯誤詳細資料,請參閱 Azure Cosmos DB 說明文件。 如需進一步協助,請連絡 Azure Cosmos DB 小組。

錯誤碼:CosmosDbSqlApiPartitionKeyExceedStorage

  • 訊息The size of data each logical partition can store is limited, current partitioning design and workload failed to store more than the allowed amount of data for a given partition key value.

  • 原因:每個邏輯分割區的資料大小都受到限制,且分割區索引鍵達到邏輯分割區的大小上限。

  • 建議:檢查您的 Azure Cosmos DB 分割區設計。 如需詳細資訊,請參閱邏輯分割區

後續步驟

如需更多疑難排解的協助,請嘗試下列資源: