Azure Cosmos DB 在 Azure 串流分析 中的輸出會將串流處理結果以 JSON 文件寫入 Azure Cosmos DB 容器。 它支援資料歸檔及對非結構化 JSON 資料的低延遲查詢。 了解這個輸出的行為，有助於你根據情境設定其吞吐量、一致性和分割。
將 Azure Cosmos DB 作為輸出目標的基本概念
Stream Analytics 中的 Azure Cosmos DB 輸出會將您的串流處理結果以 JSON 輸出寫入 Azure Cosmos DB 容器中。 如果您尚不熟悉 Azure Cosmos DB，請參閱 Azure Cosmos DB 文件以開始使用。
Stream Analytics 僅透過 SQL API 連接 Azure Cosmos DB。 其他 Azure Cosmos DB API 尚未支援。 如果您將串流分析指向使用其他 API 建立的 Azure Cosmos DB 帳戶，可能會無法正確儲存資料。 當你使用 Azure Cosmos DB 作為輸出時，請將工作設定為相容性等級 1.2。
串流分析不會在您的資料庫中建立容器。 相反地，系統要求您預先建立它們。 這可讓您控制 Azure Cosmos DB 容器的計費成本。 您也可以使用 Azure Cosmos DB APIs 來直接調整容器的效能、一致性及容量。 下列各節會詳述適用於 Azure Cosmos DB 的一些容器選項。
調整一致性、可用性與延遲
為了符合你的應用程式需求，請在 Azure Cosmos DB 中微調資料庫和容器，並在一致性、可用性、延遲和吞吐量之間做取捨。
根據您的情境對讀取一致性以及讀寫延遲的需求權衡，在資料庫帳戶上選擇一致性層級。 為了提升吞吐量，請在容器上擴充請求單元（RU）。 此外，Azure Cosmos DB 預設會在針對您容器的每個 CRUD 作業上進行同步索引。 這個選項是另一種控制 Azure Cosmos DB 讀寫效能的實用方式。 如需詳細資訊，請檢閱變更資料庫及查詢的一致性層級一文。
來自 Stream Analytics 的 Upsert
透過使用 Stream Analytics 與 Azure Cosmos DB 整合，您可以根據指定的文件 ID 欄位，在容器中插入或更新紀錄。 這項作業也稱為 upsert。 Stream Analytics 使用樂觀式 Upsert 方法。 更新只會在因文件識別碼衝突而導致插入失敗時發生。
透過相容性等級 1.0，Stream Analytics 將此更新視為 PATCH 操作，因此支援文件的部分更新。 串流分析會以累加方式加入新的屬性，或是取代現有的屬性。 但是，變更 JSON 文件中陣列屬性的值，會使系統覆寫整個陣列。 也就是這個陣列不會被合併。
使用相容性層級 1.2 時，upsert 行為會變更為插入或取代文件。 關於相容性層級 1.2 的後續小節會進一步說明此行為。
如果收到的 JSON 文件已有 ID 欄位，Azure Cosmos DB 會自動使用該欄位作為文件 ID 欄位。 Stream Analytics 會據此處理任何後續寫入，因此會出現下列其中一種情況：
- 唯一 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 所用的分割區索引鍵不必相同。 對於完全平行拓撲，請使用 Input Partition keyPartitionId 作為 Stream Analytics 查詢的分割鍵，但這個選項可能不是 Azure Cosmos DB 容器分割鍵的推薦選擇。
分區鍵也是 Azure Cosmos DB 中預存程序和觸發器的交易界限。 選擇分割鍵，使交易中同時出現的文件共享相同的分割鍵值。 Azure Cosmos DB 中的資料分割文章能針對選擇分割鍵提供更多詳細資料。
對於固定的 Azure Cosmos DB 容器，Stream Analytics 無法在容器滿後擴充或擴展。 其具有 10 GB 和 10,000 RU/秒的輸送量上限。 若要將資料從固定容器移轉到無限制的容器 (例如輸送量至少為 1,000 RU/秒，且具有分割區索引鍵的容器)，請使用資料移轉工具或變更摘要程式庫。
不再支援寫入多個已定義的容器。 不要用它來擴展你的串流分析工作。
改善吞吐量，達相容性層級 1.2
透過使用相容性層級 1.2，Stream Analytics 支援原生整合功能，可將資料大量寫入至 Azure Cosmos DB。 透過此整合，Stream Analytics 能有效寫入 Azure Cosmos DB，同時最大化吞吐量並有效處理限速請求。
由於 Upsert 行為有所不同，因此改良後的寫入機制會在新的相容性層級下提供。 使用 1.2 之前的層級時，upsert 行為是插入或合併文件。 使用 1.2 版本後，upsert 行為會改變，以插入或替換文件。
使用 1.2 之前的層級時，串流分析會使用自訂存放程序，依分割索引鍵將文件大量 Upsert 到 Azure Cosmos DB。 在該處，Stream Analytics 會將一個批次當作一筆交易寫入。 即使單一紀錄遇到暫態錯誤（限速），Stream Analytics 也必須重新嘗試整個批次。 這種行為會讓即使是合理限速的情境變慢。
下列範例顯示兩個相同的 Stream Analytics 作業，從相同的 Azure 事件中樞輸入讀取資料。 兩個 Stream Analytics 作業都已完全分割，使用傳遞查詢，並寫入相同的 Azure Cosmos DB 容器。 左側的指標來自設定為相容性層級 1.0 的作業。 右側的指標來自設定為 1.2 的專案。 Azure Cosmos DB 容器的分割索引鍵，是來自輸入事件的唯一 GUID。
事件中樞的即將到來事件速率比 Azure Cosmos DB 容器 (20,000 RUs) 設定可接收的速率高出兩倍，因此預期 Azure Cosmos DB 會發生節流。 不過，1.2 的作業持續以較高的輸送量 (每分鐘輸出事件數) 寫入，而且平均 SU% 使用率較低。 在你的環境中，這個差異還取決於幾個其他因素。 這些因素包括事件格式的選擇、輸入事件/訊息大小、分割區索引鍵，以及查詢。
透過使用 1.2 版本，Stream Analytics 更智慧地利用 Azure Cosmos DB 中 100% 的可用吞吐量，且很少有因限速或速率限制而重新提交的情況。 此行為可為其他工作負載提供更好的體驗，例如同時在容器上執行的查詢。 如果您想要了解串流分析如何以 Azure Cosmos DB 做為接收器，從每秒 1,000 個訊息擴增到每秒 10,000 個訊息，請嘗試這個 Azure 範例專案 \(英文\)。
使用 1.0 與 1.1 版本時，Azure Cosmos DB 輸出的吞吐量完全相同。 我們「強烈建議」您在搭配 Azure Cosmos DB 使用串流分析時，使用相容性層級 1.2。
適用於 JSON 輸出的 Azure Cosmos DB 設定
當你在 Stream Analytics 中將 Azure Cosmos DB 設定為輸出時，以下屬性定義了輸出。
| 欄位 | 描述 |
|---|---|
| 輸出別名 | 在 Stream Analytics 查詢中，用來參考此輸出的別名。 |
| 訂用帳戶 | Azure 訂用帳戶。 |
| 帳戶識別碼 | Azure Cosmos DB 帳戶的名稱或端點 URI。 |
| 帳戶金鑰 | Azure Cosmos DB 帳戶的共用存取金鑰。 |
| 資料庫 | Azure Cosmos DB 資料庫名稱。 |
| 容器名稱 | 容器名稱，例如 MyContainer。 名為 MyContainer 的容器必須存在。 |
| 文件識別碼 | 選擇性。 輸出事件中的欄位名稱，作為插入或更新操作的唯一鍵。 如果你留空，Stream Analytics 會自動插入所有事件，沒有更新選項。 |
在您設定 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 期間發生暫時性失敗、服務無法使用或節流，串流分析會無限期地重試，直到順利完成作業為止。 但對於 Unauthorized（HTTP 錯誤代碼 401）、NotFound（HTTP 錯誤代碼 404）、Forbidden（HTTP 錯誤代碼 403）或 BadRequest（HTTP 錯誤代碼 400）失敗，則不會嘗試重試。
導致 Azure Cosmos DB 輸出失敗的常見問題
有幾種情況會導致 Azure Cosmos DB 輸出失敗。 Stream Analytics 的輸出資料可能違反容器唯一的索引限制，欄位 PartitionKey 可能不存在，或欄位 Id 不存在。 欲了解更多關於唯一索引約束的資訊，請參閱 Azure Cosmos DB 中的獨特金鑰約束。