Azure Cosmos DB 中的變更摘要模式

適用於：NoSQL

Azure Cosmos DB 提供兩種變更摘要模式， 兩種模式的核心功能都相同， 不同之處在於從摘要中擷取的作業、每次變更可取得的中繼資料，以及變更記錄的保留期間。 針對相同的 Azure Cosmos DB 容器，您可以在多個應用程式上以不同模式取用變更摘要，以滿足各個工作負載的需求。 每個變更摘要應用程式只能設定為以一種模式讀取變更摘要。 以一種模式取用變更摘要後，您依然可以在不同應用程式中以另一種模式取用變更摘要。

注意

對於變更摘要模式有任何意見反應嗎？ 我們想要知道您的看法！ 歡迎您將意見反應直接告訴 Azure Cosmos DB 工程小組：cosmoschangefeed@microsoft.com。

最新版本變更摘要模式

最新版本模式會從項目建立至更新持續留下變更記錄， 讓您取得容器內每個項目的最新版本。 舉例來說，如果項目是在您讀取變更摘要之前建立並進行更新，變更摘要中便只會顯示更新版本。 系統不會擷取刪除作業並將其列入變更記錄，摘要中也不會顯示已刪除的項目。 最新版本變更摘要模式預設為啟用，並且幾乎與所有 Azure Cosmos DB 帳戶相容，僅有 API for Table 與 API for PostgreSQL 除外。 這個模式原本是變更摘要的預設取用方式。

所有版本和刪除變更摘要模式 (預覽版)

所有版本和刪除模式 (預覽版) 中持續記錄了項目從建立、更新至刪除期間的所有變更， 會按發生順序記下每次項目變更，包括在兩次變更摘要讀取之間的項目中繼變更。 舉例來說，如果項目是在您讀取變更摘要之前建立並進行更新，那麼變更摘要中會顯示項目的建立及更新版本。 若要讀取所有版本和刪除模式的變更摘要，您必須為自己的 Azure Cosmos DB 帳戶設定連續備份 (機器翻譯)。 啟用連續備份後，便會建立所有版本和刪除變更摘要。 使用這個變更摘要模式時，您只能讀取發生在連續備份期間的變更。 此模式僅與 Azure Cosmos DB for NoSQL 帳戶相容。 深入了解如何註冊預覽版。

變更摘要使用案例

最新版本模式

最新版本模式可讓您輕鬆處理容器中項目的即時和歷史變更，且能夠從容器開頭返回變更。

以下是適合運用此模式的案例：

• 將整個容器移轉至次要位置。

• 能夠從容器開頭重新處理變更。

• 即時處理容器中因建立和更新作業而產生的項目變更。

• 不需要擷取刪除作業或兩次讀取之間的中繼變更之工作負載。

所有版本和刪除模式 (預覽版)

所有版本和刪除變更摘要模式能夠用於變更摘要新案例，並簡化其他案例。 您可以讀取項目發生的每項變更 (即使在兩次變更摘要讀取之間發生了多次變更)、識別處理中變更作業類型，以及掌握因刪除作業而產生的變更。

此模式可運用和改善的一些常見案例如下：

• 在兩個位置之間即時傳輸資料，不實作虛刪除。

• 如果特定項目預計會在變更摘要輪詢之間進行多次變更作業，則觸發以累加變更為基礎的邏輯。

• 針對刪除作業觸發警示，例如在稽核案例中。

• 能夠根據作業類型，以不同方式處理項目的建立、更新和刪除。

各種模式的功能

除了所有變更摘要模式的通用功能 (機器翻譯) 之外，每種變更摘要模式都有下列特性：

最新版本模式

• 變更摘要包括對容器內項目進行的插入與更新作業。

• 這種變更摘要模式不會記錄刪除作業。 若要擷取刪除作業，請在項目中設定「虛刪除」旗標，而非直接刪除項目。 舉例來說，您可以替名為 deleted 且值為 true 的項目新增屬性，然後為項目設定存留時間 (TTL)， 這樣一來，變更摘要就會將其擷取為更新作業，且項目會在 TTL 到期時自動刪除。 此外，您也可以使用 TTL 功能 (機器翻譯) 為項目設定有限的到期期間。 使用此解決方案，您必須在比 TTL 逾期期限更短的時間間隔內處理變更。

• 變更摘要中只會包含指定項目的最新變更， 可能不會保留中繼變更。

• 項目刪除後，變更摘要便不會有該項目。

• 變更可以從任何時間點同步處理，也就是說，可存取的變更沒有固定資料保留期間。

• 您無法篩選特定作業類型的變更摘要。 一種可能的替代方案，是在變更摘要中處理項目時，在項目上新增「軟標記」以用於更新，並據以篩選。

• 讀取變更摘要的起點可以為容器開頭、任一時間點、「現在」，或者特定檢查點。 開始時間的精確度大約是五秒。

所有版本和刪除模式 (預覽版)

• 變更摘要包含對容器內項目進行的插入、更新與刪除作業， 也會擷取 TTL 到期日的刪除作業。

• 會提供用於判斷變更類型的中繼資料，包含是否因 TTL 到期而執行刪除作業。

• 變更摘要項目會按修改時間順序排列。 TTL 到期的刪除作業不一定會在項目到期後立即顯示在摘要中； 待項目自容器刪除後，才會顯示。

• 您可以讀取帳戶上連續備份之保留期間內發生的所有變更。 若嘗試讀取在保留期間外發生的變更，則會導致錯誤。 舉例來說，如果您的容器是在八天前建立，而您的連續備份資料保留期間是七天，您便只能讀取過去七天內發生的變更。

• 變更摘要的起點可以是「現在」或保留期間內的特定檢查點。 使用此模式時，您無法從容器開頭或特定時間點讀取變更。

使用變更摘要

讀取使用各種語言的變更摘要時，每種模式的相容方法都不同。

最新版本模式

在最新版本模式中，您可以透過下列方式取用變更摘要中的變更：

讀取變更摘要的方法	.NET	Java	Python	Node.js
變更摘要提取模型	Yes	.是	.是	Yes
變更摘要處理器	Yes	是	無	No
Azure Functions 觸發程序 (機器翻譯)	Yes	.是	.是	Yes

剖析回應物件

在最新版本模式中，預設回應物件是已變更的項目陣列。 每個項目都包含 Azure Cosmos DB 項目的標準中繼資料，包含 _etag 與 _ts，以及新增的屬性 _lsn。

_etag 格式是作為內部之用，因為該格式可以隨時變更，請別依賴它。 _ts 是修改或建立的時間戳記， 您可以使用 _ts，依時間順序進行比較。 _lsn 是僅為變更摘要新增的批次識別碼，代表交易識別碼。 許多項目都可能有相同的 _lsn。

FeedResponse 上的 ETag 與您在項目上看到的 _etag 不同。 _etag 是內部識別碼，用於並行控制。 _etag 屬性代表項目的版本，而 ETag 屬性則式用於替摘要排序。

所有版本和刪除模式 (預覽版)

在預覽期間，各用戶端 SDK 可透過下列方法讀取變更摘要：

讀取變更摘要的方法	.NET	Java	Python	Node.js
變更摘要提取模型	>= 3.32.0-preview (英文)	>= 4.42.0 (英文)	No	>= 4.1.0
變更摘要處理器	>= 3.40.0-preview.0	>= 4.42.0 (英文)	No	No
Azure Functions 觸發程序	No	無	無	無

注意

無論應用程式中設定的連線模式 (機器翻譯) 為何，透過所有版本和刪除變更摘要提出的一切要求都會使用網路閘道模式。

開始使用

若要開始使用所有版本和刪除變更摘要模式，請透過 Azure 訂用帳戶概觀頁面中的 [預覽功能] 頁面註冊預覽版。 搜尋 AllVersionsAndDeletesChangeFeed 功能，然後選取 [註冊]。

請先確定您的訂用帳戶中至少有一個 Azure Cosmos DB 帳戶，再提交要求。 此帳戶可為現有帳戶，或是您為了試用預覽功能而建立的新帳戶。 如果收到要求時訂用帳戶中沒有任何帳戶，要求會遭到拒絕，因為沒有帳戶可套用此功能。

Azure Cosmos DB 小組會檢閱您的要求，並透過電子郵件與您連絡，確認您想用訂用帳戶中哪個 Azure Cosmos DB 帳戶註冊預覽版。 若要使用預覽版，您必須為 Azure Cosmos DB 帳戶設定連續備份。 在獲准使用預覽版之前或之後啟用連續備份都無妨，但在透過所有版本和刪除模式讀取變更摘要前，一定要先啟用連續備份。

剖析回應物件

回應物件是代表各項變更的項目所組成的陣列， 根據變更類型，將會填入不同的屬性。 目前無法取得舊版的專案，以進行取代或刪除作業。

• 建立作業

  {
    "current": {
      <The current version of the item that changed. All the properties of your item will appear here.>
    },
    "metadata": {
      "operationType": "create",
      "lsn": <A number that represents the batch ID. Many items can have the same lsn.>,
      "crts": <A number that represents the Conflict Resolved Timestamp. It has the same format as _ts.>
    }
  }
  

• 取代作業

  {
    "current": {
      <The current version of the item that changed. All the properties of your item will appear here.>
    },
    "metadata": {
      "operationType": "replace",
      "lsn": <A number that represents the batch ID. Many items can have the same lsn.>,
      "crts": <A number that represents the Conflict Resolved Timestamp. It has the same format as _ts.>,
      "previousImageLSN" : <A number that represents the batch ID of the change prior to this one.>,
    }
  }
  

• 刪除作業

  {
    "metadata": {
      "operationType": "delete",
      "lsn": <A number that represents the batch ID. Many items can have the same lsn.>,
      "crts": <A number that represents the Conflict Resolved Timestamp. It has the same format as _ts.>,
      "previousImageLSN" : <A number that represents the batch ID of the change prior to this one.>,
      "id": "<Id of the deleted item.>",
      "partitionKey": {
        "<Partition key property name>": "<Partition key property value>"
      }
    }
  }
  

限制

• 僅支援 Azure Cosmos DB for NoSQL 帳戶， 不支援其他 Azure Cosmos DB 帳戶類型。

• 必須啟用連續備份才能使用這個變更摘要模式。 如需了解使用連續備份的限制，請參閱文件。

• 在帳戶啟用連續備份前已存在的容器上，無法讀取變更。

• 目前不支援從頭開始讀取變更摘要，或者根據過去的時間戳選取開始時間的功能。 您可以從「現在」、先前的租用或接續權杖開始。

• 目前無法使用已刪除或更新的舊版專案。

• 不支援啟用 合併數據分割的 帳戶。

下一步

若要深入了解變更摘要，請參閱下列文章：

• 變更摘要概觀
• 變更摘要設計模式
• 讀取變更摘要的選項