Azure 串流分析可以將 JSON 格式的數據輸出至 Azure Cosmos DB。 它可針對非結構化 JSON 數據啟用數據封存和低延遲查詢。 本文涵蓋實作此設定的一些最佳做法（串流分析至 Cosmos DB）。 如果您尚不熟悉 Azure Cosmos DB，請參閱 Azure Cosmos DB 文件以開始使用。
注意
- 目前，串流分析僅支援透過 SQL API 連線至 Azure Cosmos DB。尚不支援其他 Azure Cosmos DB API。 如果您將串流分析指向使用其他 API 建立的 Azure Cosmos DB 帳戶，可能會無法正確儲存資料。
- 建議您在使用 Azure Cosmos DB 作為輸出時，將作業設定為相容性層級 1.2。
將 Azure Cosmos DB 作為輸出目標的基本概念
串流分析中的 Azure Cosmos DB 輸出可將串流處理結果以 JSON 輸出的形式寫入到您的 Azure Cosmos DB 容器。 串流分析不會在您的資料庫中建立容器。 相反地，系統要求您預先建立它們。 這可讓您控制 Azure Cosmos DB 容器的計費成本。 您也可以使用 Azure Cosmos DB APIs 來直接調整容器的效能、一致性及容量。 下列各節會詳述適用於 Azure Cosmos DB 的一些容器選項。
調整一致性、可用性與延遲
為了符合您的應用程式需求，Azure Cosmos DB 允許您微調資料庫與容器，並在一致性、可用性、延遲及輸送量之間進行取捨。
您可以視案例針對讀取與寫入延遲所需的讀取一致性層級，來選擇資料庫帳戶上的一致性層級。 您可以透過增加容器上的「要求單位」（RU）來提高吞吐量。 此外，Azure Cosmos DB 預設會在針對您容器的每個 CRUD 作業上進行同步索引。 此選項是另一個有用的選項，可用來控制 Azure Cosmos DB 中的寫入/讀取效能。 如需詳細資訊，請檢閱變更資料庫及查詢的一致性層級一文。
來自 Stream Analytics 的 Upsert
串流分析與 Azure Cosmos DB 的整合可讓您根據指定的 [文件識別碼] 資料行，在容器中插入或更新記錄。 這項作業也稱為 upsert。 Stream Analytics 使用樂觀式 Upsert 方法。 更新只會在因文件識別碼衝突而導致插入失敗時發生。
使用相容性層級 1.0 時，串流分析會以 PATCH 作業的形式執行此更新，因此其會針對文件啟用部分更新。 串流分析會以累加方式加入新的屬性，或是取代現有的屬性。 但是，變更 JSON 文件中陣列屬性的值，會使系統覆寫整個陣列。 也就是這個陣列不會被合併。
使用 1.2 時，upsert 行為會修改為插入或取代文件。 關於相容性層級 1.2 的後續小節會進一步說明此行為。
如果內送 JSON 文件有現有的 [識別碼] 欄位，系統會在 Azure Cosmos DB 中自動將該欄位作為 [文件識別碼] 資料行。 任何後續的寫入都會以這種方式處理，並導致下列其中一種情況：
- 唯一 ID 會導致插入。
- 重複的 ID，且文件 ID 設為 ID 時，會導致 upsert。
- 未設定的重複識別碼和 [文件識別碼] 會在第一個文件之後導致錯誤。
如果您想要儲存「所有」文件 (包括具有重複識別碼的文件)，請將查詢中的 [識別碼] 欄位重新命名 (使用 AS 關鍵字)。 讓 Azure Cosmos DB 建立 [識別碼] 欄位，或是以另一個資料行的值取代 [識別碼] 欄位 (使用 AS 關鍵字或使用 [文件識別碼] 設定)。
Azure Cosmos DB 中的資料分割
Azure Cosmos DB 會根據您的工作負載自動調整分割區。 因此，我們建議您使用 無限制 的容器來分割數據。 當串流分析寫入無限制的容器時，其會使用與先前查詢步驟或輸入資料分割配置同樣數目的平行寫入器。
注意
Azure 串流分析僅支援具備位於頂層的分割區索引鍵的無限制容器。 例如，支援 /region。 不支援巢狀分割區鍵 (例如 /region/name)。
視您選擇的分割區索引鍵而定，您可能會收到此「警告」：
CosmosDB Output contains multiple rows and just one row per partition key. If the output latency is higher than expected, consider choosing a partition key that contains at least several hundred records per partition key.
請務必選擇具有許多相異值的分割區索引鍵屬性，這可讓您將工作負載平均分散到這些值。 作為資料分割的自然產物，涉及相同的分割區鍵的要求會受到單一分割區的最大吞吐量限制。
屬於相同分割區索引鍵值的文件儲存大小限制為 20 GB (實體分割區大小限制為 50 GB)。 理想的分割索引鍵，是在查詢中經常作為篩選條件出現，且具有足夠基數，以確保解決方案可擴縮的索引鍵。
串流分析查詢和 Azure Cosmos DB 所用的分割區索引鍵不必相同。 完全平行拓撲建議使用 輸入分割區索引鍵 作為串流分析查詢的分區索引鍵，然而，這可能不是 Azure Cosmos DB 容器的分區索引鍵的最佳選擇。
分區鍵也是 Azure Cosmos DB 中預存程序和觸發器的交易界限。 您應選擇分割區索引鍵，以確保在交易中共同處理的文件共享相同的分割區索引鍵值。 Azure Cosmos DB 中的資料分割文章能針對選擇分割鍵提供更多詳細資料。
針對固定 Azure Cosmos DB 容器，在其空間已滿時，串流分析並未提供任何擴大或擴增的方法。 其具有 10 GB 和 10,000 RU/秒的輸送量上限。 若要將資料從固定容器移轉到無限制的容器 (例如輸送量至少為 1,000 RU/秒，且具有分割區索引鍵的容器)，請使用資料移轉工具或變更摘要程式庫。
不再支援寫入多個已定義的容器。 我們不建議將其用來擴增您的串流分析作業。
改善吞吐量，達相容性層級 1.2
使用相容性層級 1.2 時，串流分析支援原生整合以大量寫入 Azure Cosmos DB。 此整合可讓系統有效地寫入 Azure Cosmos DB，同時將輸送量最大化並有效率地處理節流要求。
由於 Upsert 行為有所不同，因此改良後的寫入機制會在新的相容性層級下提供。 在版本低於 1.2 的情況下，upsert 的行為是插入或合併文件。 使用 1.2 時，upsert 行為會修改為插入或取代文件。
在 1.2 之前的層級中，Stream Analytics 會使用自訂預存程序，依分割索引鍵將文件大量 Upsert 到 Azure Cosmos DB。 在該情況下，批次會作為交易寫入。 即使只有單一記錄遇到暫時性錯誤 (節流)，也必須重試整個批次。 這種行為會使即使是合理節流的案例，也變得相對緩慢。
下列範例顯示兩個相同的 Stream Analytics 作業，從相同的 Azure 事件中樞輸入讀取資料。 兩個 Stream Analytics 作業都已完全分割，使用傳遞查詢，並寫入相同的 Azure Cosmos DB 容器。 左側的指標來自設定為相容性層級 1.0 的作業。 右側的度量指標已被設定為 1.2。 Azure Cosmos DB 容器的分割索引鍵，是來自輸入事件的唯一 GUID。
事件中樞的內送事件速率是 Azure Cosmos DB 容器（20,000 個 RU）所能處理量的兩倍，因此預期 Azure Cosmos DB 會發生流量限制。 不過，1.2 的作業持續以較高的輸送量 (每分鐘輸出事件數) 寫入，而且平均 SU% 使用率較低。 在您的環境中，此差異取決於更多因素。 這些因素包括事件格式的選擇、輸入事件/訊息大小、分割區索引鍵，以及查詢。
在使用 1.2 版本時，Stream Analytics 更能智慧地充分利用 Azure Cosmos DB 的 100% 可用吞吐量，並且因節流或速率限制而導致的重新提交情況幾乎不會發生。 此行為可為其他工作負載提供更好的體驗，例如同時在容器上執行的查詢。 如果您想要了解串流分析如何以 Azure Cosmos DB 做為接收器，從每秒 1,000 個訊息擴增到每秒 10,000 個訊息，請嘗試這個 Azure 範例專案 \(英文\)。
Azure Cosmos DB 輸出的輸送量與 1.0 和 1.1 相同。 我們「強烈建議」您在搭配 Azure Cosmos DB 使用串流分析時，使用相容性層級 1.2。
適用於 JSON 輸出的 Azure Cosmos DB 設定
在串流分析中使用 Azure Cosmos DB 作為輸出會產生下列資訊提示。
| 欄位 | 描述 |
|---|---|
| 輸出別名 | 在 Stream Analytics 查詢中，用來參考此輸出的別名。 |
| 訂用帳戶 | Azure 訂用帳戶。 |
| 帳戶識別碼 | Azure Cosmos DB 帳戶的名稱或端點 URI。 |
| 帳戶金鑰 | Azure Cosmos DB 帳戶的共用存取金鑰。 |
| 資料庫 | Azure Cosmos DB 資料庫名稱。 |
| 容器名稱 | 容器名稱，例如 MyContainer。 名為 MyContainer 的容器必須存在。 |
| 文件識別碼 | 選擇性。 輸出事件中的資料行名稱，作為插入或更新作業所依據的唯一索引鍵。 如果您將它保留空白，則會插入所有事件，且沒有更新選項。 |
在您設定 Azure Cosmos DB 輸出之後，您可以在查詢中將其作為 INTO 陳述式 \(英文\) 的目標使用。 當您以該方式使用 Azure Cosmos DB 輸出時，必須明確設定分區金鑰。
輸出記錄必須包含區分大小寫的資料行，其名稱必須以 Azure Cosmos DB 中的分割區索引鍵命名。 若要達成更高的平行化，該陳述式可能需要使用相同資料行的 PARTITION BY 子句。
以下是查詢範例：
SELECT TollBoothId, PartitionId
INTO CosmosDBOutput
FROM Input1 PARTITION BY PartitionId
錯誤處理和重試
如果在串流分析將事件傳送到 Azure Cosmos DB 期間發生暫時性失敗、服務無法使用或節流，串流分析會無限期地重試，直到順利完成作業為止。 但其不會針對下列失敗嘗試重試：
- 未經授權 (HTTP 錯誤碼 401)
- 找不到 (HTTP 錯誤碼 404)
- 禁止 (HTTP 錯誤碼 403)
- 不正確的要求 (HTTP 錯誤碼 400)
常見問題
唯一索引條件約束會新增至集合，而串流分析的輸出資料違反此條件約束。 請確定串流分析的輸出資料不會違反唯一條件約束，或是移除條件約束。 如需詳細資訊，請參閱 Azure Cosmos DB 中的唯一索引鍵條件約束。
PartitionKey欄不存在。Id欄位不存在。