使用 seek 重播及清除訊息

在 Pub/Sub 中確認訊息後，訂閱端用戶端就無法再存取這些訊息。此外，訂閱者用戶端必須處理訂閱項目中的每則訊息，即使只需要部分訊息也一樣。

跳轉功能可讓您大量變更訊息的確認狀態，進而擴充訂閱者功能。舉例來說，您可以重播先前確認過的訊息，或大量清除訊息。此外，您也可以搭配使用搜尋和快照，將某個訂閱項目的確認狀態複製到其他訂閱項目。

如要快速瞭解這些功能的運作方式，請參閱「根據快照或時間戳記還原狀態，重新傳送 Pub/Sub 訊息」。

快照和還原作業總覽

Pub/Sub 快照是兼具持久性、一致性和可靠度的檢視畫面，會顯示訂閱項目在特定時間點的訊息確認狀態。快照會記錄建立當下訂閱項目中所有訊息的確認狀態。快照會保留建立時來源訂閱項目的未確認訊息，以及快照建立後發布至主題的任何訊息。

快照的生命週期取決於來源訂閱項目的現有待處理工作。生命週期等於 7 天減去訂閱項目中最舊未確認訊息的存在時間。舉例來說，假設訂閱項目快照包含待處理工作，且最舊的未確認訊息已存在 1 天。快照會在 6 天後失效。快照必須有這段時間軸，才能提供強大的「至少傳送一次」保證。

快照的生命週期最長為七天。 您無法建立快照，因為快照會在建立後 1 小時內到期。

透過搜尋功能，您可以搜尋訂閱項目的特定快照或時間戳記。這項功能可讓您控管 Pub/Sub 如何從特定時間點或特定快照傳送訊息。

如要搜尋過去時間並重播先前已確認的訊息，請先在主題中設定訊息保留功能，或將訂閱項目設為保留已確認的訊息。

搜尋作業的最終一致性

就訊息傳送保證而言，搜尋作業嚴格一致。也就是說，根據搜尋條件而變成未確認的任何訊息，在搜尋作業成功後，保證最終會傳送。不過，傳送的訊息不會立即與搜尋作業保持一致。因此，在搜尋時間戳記之前發布的訊息，或是在快照中確認的訊息，可能會在搜尋作業後傳送。就搜尋作業而言，訊息傳遞作業可說是最終一致的系統；這項作業可能需要一分鐘才能完全生效。

搜尋作業的用途

  • 安全地更新訂閱者代碼。部署新訂閱端程式碼時，新執行檔可能會錯誤地確認訊息，導致訊息遺失。將快照納入部署程序，有助於從新訂閱者程式碼中的錯誤復原。
  • 解決訂閱者遇到的非預期問題。如果訂閱者問題與特定部署事件無關，您可能沒有相關快照。在這種情況下，如果您已為訂閱項目啟用已確認訊息保留功能，只要倒轉至過去的時間點，即可從錯誤中復原。
  • 節省處理時間和成本。大量確認不再相關的訊息，藉此清除大量待處理訊息。
  • 在已知資料上測試訂閱者程式碼。測試訂閱者程式碼的效能和一致性時，每次執行都使用相同資料會很有幫助。快照可提供語意明確的資料。此外，快照可以套用至指定主題的任何訂閱項目，包括新建立的項目。

設定訊息保留功能

您可以為主題設定訊息保留功能，並設定所有相關訂閱項目，保留已確認的訊息。如果希望訊息保留時間長於訂閱項目設定的訊息保留時間，以便重播訊息，建議設定主題訊息保留時間。在這種情況下，系統會根據主題和訂閱項目的訊息保留設定，向這兩個專案收取訊息儲存費用。

如果未設定主題訊息保留時間，當未確認的訊息超過訂閱項目的 message_retention_duration 屬性時，系統就會從訂閱項目中刪除該訊息。另一方面，如果已設定主題訊息保留時間，只有在未確認訊息的存留時間超過主題和訂閱項目的 message_retention_duration 上限時，系統才會從訂閱項目中刪除該訊息。

設定主題訊息保留時間

根據預設，Pub/Sub 主題會在所有附加的訂閱項目確認訊息後，立即捨棄訊息。設定主題時保留訊息可提供更多彈性，讓附加至主題的任何訂閱項目都能回溯時間，並重播先前確認的訊息 (最多可回溯至主題的message_retention_duration)。主題訊息保留功能也允許訂閱項目重播您建立訂閱項目之前發布的訊息。

即使所有附加訂閱項目都已確認訊息，主題最多仍可保留發布的訊息 31 天 (可透過主題的 message_retention_duration 屬性設定)。如果主題的 message_retention_duration 大於訂閱項目的 message_retention_duration，只有在訊息的存留時間超過主題的 message_retention_duration 時，Pub/Sub 才會捨棄訊息。

如果啟用主題訊息保留功能，系統會向主題的專案收取主題保留訊息的儲存費用。

控制台

如要建立啟用訊息保留功能的主題，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Pub/Sub topics」(Pub/Sub 主題) 頁面。

    前往主題頁面

  2. 按一下「建立主題」。

  3. 在「主題 ID」欄位中，輸入主題 ID。

  4. 啟用「設定訊息保留時間」。

    其他選項則保留預設設定。

  5. 使用「訊息保留時間長度」下拉式選單，選取要保留訊息的天數、時數和分鐘數。

  6. 按一下「建立主題」儲存主題。

如要更新主題的訊息保留設定，請按照下列步驟操作：

  1. 在「Pub/Sub topics」(Pub/Sub 主題) 頁面中選取主題。

    前往主題頁面

  2. 按一下主題詳細資料頁面頂端的「編輯」。

  3. 勾選或取消勾選「啟用訊息保留功能」選項，即可調整保留時間，或啟用/停用訊息保留功能。

  4. 按一下「更新」，儲存主題變更。

gcloud

如要建立主題，並將訊息保留時間設為 7 天，請使用下列 gcloud pubsub topics create 指令：

gcloud pubsub topics create TOPIC_ID --message-retention-duration=7d

您可以使用 gcloud pubsub topics update 更新這項設定。您也可以為現有主題啟用訊息保留功能：

gcloud pubsub topics update TOPIC_ID --message-retention-duration=1d

您也可以使用 update 指令，停用主題的訊息保留功能：

gcloud pubsub topics update TOPIC_ID --clear-message-retention-duration

設定訂閱訊息保留時間

建立訂閱項目後，Pub/Sub 就會開始代表該訂閱項目保留訊息。根據預設，Pub/Sub 會在訊息確認後，立即從訂閱項目捨棄該訊息。未確認的訊息預設會保留 7 天 (可透過訂閱項目的 message_retention_duration 屬性設定)。

將訂閱項目設為保留已確認的訊息 (使用 retain_acked_messages 屬性)，即可重播訂閱項目保留的先前已確認訊息。您可以在訂閱項目中設定訊息保留期限，最長為 31 天。這項設定適用於已確認及未確認訊息。

如果訂閱項目設為保留已確認的訊息，系統會向訂閱項目的專案收取訂閱項目保留的已確認訊息儲存費用。

控制台

如要建立啟用保留已確認訊息功能的訂閱項目，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Pub/Sub subscriptions」(Pub/Sub 訂閱項目) 頁面。

    前往「訂閱」頁面

  2. 按一下「Create Subscription」 (建立訂閱項目)。

  3. 在「Subscription ID」(訂閱 ID) 欄位中，輸入訂閱 ID。

  4. 使用「訊息保留時間長度」下拉式選單，選取訊息保留天數、時數和分鐘數。

  5. 啟用「保留已確認的訊息」。其他選項則保留預設設定。

  6. 按一下「建立訂閱項目」即可儲存訂閱項目。

如要更新訂閱項目的訊息保留設定，請按照下列步驟操作：

  1. 在「Pub/Sub subscriptions」(Pub/Sub 訂閱項目) 頁面中選取訂閱項目。

    前往「訂閱」頁面

  2. 按一下訂閱項目詳細資料頁面頂端的「編輯」。

  3. 調整訊息保留時間，或勾選/取消勾選標示為「保留已確認訊息」的欄位，啟用或停用保留已確認訊息的設定。

  4. 按一下「更新」，儲存訂閱方案變更。

gcloud

如要建立啟用保留已確認訊息功能的訂閱項目，請使用下列 gcloud pubsub subscriptions create 指令：

gcloud pubsub subscriptions create SUBSCRIPTION_ID
    --retain-acked-messages
    --message-retention-duration=5d

您可以使用 gcloud pubsub subscriptions update 更新這項設定。您也可以透過這項功能，為現有訂閱項目啟用保留已確認訊息的設定：

gcloud pubsub subscriptions update SUBSCRIPTION_ID --message-retention-duration=1d

您也可以使用 update 指令，為訂閱項目停用已確認訊息的保留功能：

gcloud pubsub subscriptions update SUBSCRIPTION_ID --no-retain-acked-messages

建立快照

您可以使用控制台、Google API 或 Google Cloud CLI 建立快照。

控制台

如要建立快照，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「快照」頁面。

    前往快照頁面

  2. 按一下 [Create snapshot] (建立快照)。

  3. 在「選取 Pub/Sub 訂閱項目」部分，選取訂閱項目。

  4. 在「Snapshot ID」(快照 ID) 中輸入快照的名稱。

    如要進一步瞭解如何命名 Pub/Sub 資源，請參閱主題、訂閱項目、結構定義或快照的命名規範。

  5. 按一下 [Create] (建立) 以建立快照。

您也可以從「訂閱項目」頁面建立快照。如果您在建立訂閱項目後立即建立快照，可能會因為新建立訂閱項目的傳播延遲而發生錯誤。

gcloud

如要建立快照，請使用下列 gcloud pubsub snapshots create 指令：

gcloud pubsub snapshots create \
    --project=PROJECT_ID \
    --subscription=SUBSCRIPTION_ID \
    SNAPSHOT_ID

更改下列內容：

  • PROJECT_ID：指定專案 ID。

  • SUBSCRIPTION_ID。指定訂閱項目的 ID。

  • SNAPSHOT_ID：指定快照的 ID。

根據時間戳記還原狀態

還原至先前的狀態後，Pub/Sub 在這個時間點之前收到的所有訊息會標示為已確認，之後收到的每則訊息會標示為未確認。

您可以根據時間戳記執行下列類型的搜尋作業：

  • 如要清除所有訊息，請跳轉至未來時間。

  • 如要重播及重新處理先前確認的訊息，請跳轉至過去的時間點。

訊息發布時間是由 Pub/Sub 伺服器所產生 (詳情請參閱 API 參考資料中的 publishTime)。這種做法不夠精確，原因如下：

  • Pub/Sub 伺服器之間可能存在時鐘偏差。

  • Pub/Sub 必須根據發布要求的抵達時間運作，而非來源系統中發生事件的時間。

您可以使用控制台、Google API 或 Google Cloud CLI CLI，搜尋特定時間戳記。如要根據時間戳記還原訂閱項目的狀態，請先在訂閱項目上啟用訊息保留功能。

控制台

如要跳到特定時間戳記，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Subscription」(訂閱) 頁面。

    前往「訂閱」頁面

  2. 按一下已啟用訊息保留功能的訂閱項目。

  3. 在訂閱詳細資料頁面中，按一下「重播訊息」。

  4. 在「Seek」部分，按一下「To a previous time point」。

  5. 選取適當的日期和時間，然後按一下「搜尋」。

gcloud

如要搜尋時間戳記，請使用下列 gcloud pubsub subscriptions seek 指令：

gcloud pubsub subscriptions seek SUBSCRIPTION_ID \
    --time=TIME \

更改下列內容：

  • TIME：要執行搜尋作業的時間。
  • SUBSCRIPTION_ID：訂閱 ID。

如要進一步瞭解支援的時間格式，請參閱 gcloud topic datetimes。

還原至快照

您可以透過快照，在主題的任何訂閱項目中搜尋，藉此重播未確認的訊息。

與搜尋時間不同，搜尋快照不需要執行任何特殊訂閱設定。您只需要事先建立快照即可。舉例來說，部署新的訂閱端程式碼時，您可能會建立快照，以防需要從非預期或錯誤的確認中復原。

如果訂閱項目的待處理項目過舊，導致產生的快照會在 1 小時內過期，搜尋作業就會失敗。

您可以使用控制台、Google API 或 Google Cloud CLI CLI 搜尋快照。

控制台

如要跳到特定時間點，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Subscription」(訂閱) 頁面。

    前往「訂閱」頁面

  2. 按一下訂閱方案。

  3. 在訂閱詳細資料頁面中，按一下「重播訊息」。

  4. 如要「Seek」(搜尋)，請按一下「To a snapshot」(快照)。

  5. 選取適當的快照，然後按一下「Seek」(搜尋)。

gcloud

如要搜尋快照，請使用下列 gcloud pubsub subscriptions seek 指令：

gcloud pubsub subscriptions seek SUBSCRIPTION_ID \
    --snapshot=SNAPSHOT_ID

更改下列內容：

  • SNAPSHOT_ID：快照的 ID。 快照的主題必須與訂閱項目相同。
  • SUBSCRIPTION_ID：訂閱 ID。

使用篩選器搜尋

你可以使用篩選器重播訂閱項目中的訊息。如果使用設有篩選器的訂閱項目，並以時間戳記搜尋，Pub/Sub 服務只會重新傳送符合篩選條件的訊息。

含有篩選條件的訂閱項目快照包含下列訊息：

  • 快照建立後的所有訊息，包括與篩選器不符的訊息。
  • 早於快照的未確認訊息。

如果您使用設有篩選器的訂閱項目搜尋快照，Pub/Sub 服務只會重新傳送快照中與提出搜尋要求的訂閱項目篩選器相符的訊息。

如要進一步瞭解篩選器，請參閱「篩選訊息」。

使用無效信件主題搜尋

如果您在設有 dead-letter 主題的訂閱項目中搜尋訊息，Pub/Sub 會將傳送嘗試次數設為 0。您從這些訂閱項目收到的訊息會包含一個欄位，用來計算傳送嘗試次數。

如要進一步瞭解 dead-letter 主題，請參閱「轉送至 dead-letter 主題」。

使用重試政策進行搜尋

如果您在設有重試政策的訂閱項目中搜尋訊息，Pub/Sub 會重設下列項目之間的延遲：

  1. 確認期限到期，或訂閱端傳送否定確認。
  2. Pub/Sub 重新傳送訊息。

如要進一步瞭解重試政策，請參閱「使用重試政策」。

使用「僅傳送一次」功能搜尋

如果您在「只傳送一次」的訂閱項目中搜尋訊息，Pub/Sub 會重新傳送先前確認過且符合傳送資格的訊息。如果是在搜尋作業前傳送，任何確認都會失敗。搜尋作業具有最終一致性。

如要進一步瞭解重試政策，請參閱僅傳送一次。