Pub/Sub でメッセージの確認応答を行うと、サブスクライバー クライアントはこれらのメッセージにアクセスできなくなります。さらに、サブスクライバーのクライアントは、一部しか必要でなくてもサブスクリプションに含まれるメッセージをすべて処理しなければなりません。
シーク機能はサブスクライバーの機能を拡張するもので、メッセージの確認応答状態を一括で変更できます。たとえば、確認応答済みのメッセージを再生することや、メッセージをまとめて消去することができます。さらに、シークとスナップショットを組み合わせて使用することで、あるサブスクリプションの状態を別のサブスクリプションにコピーすることもできます。
これらの機能の動作を簡単に確認するには、スナップショットまたはタイムスタンプまでシークして Pub/Sub でメッセージを再生するをご覧ください。
スナップショットとシークの概要
Pub/Sub スナップショットは、サブスクリプションのメッセージの確認応答（ack）状態に関する特定の時点のビューであり、耐久性、整合性、信頼性に優れています。スナップショットは、作成時にサブスクリプション内のすべてのメッセージの確認応答状態を記録します。スナップショットは、スナップショット作成時のソース サブスクリプションの未確認メッセージと、スナップショットの作成後にそのトピックにパブリッシュされたメッセージを保持します。
スナップショットの有効期間は、ソース サブスクリプションの既存のバックログによって決まります。存続期間は、7 日間からサブスクリプション内の最も古い未確認メッセージの経過日数を差し引いた期間です。たとえば、サブスクリプションのスナップショットにバックログがあり、その最も古い未確認メッセージが 1 日前のメッセージだとします。スナップショットは 6 日後に期限切れになります。このタイムラインはスナップショットで at-least-once 配信を確実に保証するために必要になります。
スナップショットの有効期間は、最大 7 日間です。作成後 1 時間未満で期限切れになるスナップショットは作成できません。
シーク機能を使用すると、サブスクリプションの特定のスナップショットまたはタイムスタンプまでシークできます。この機能を使用すると、Pub/Sub が特定の時点または特定のスナップショットからメッセージを配信する方法を制御できます。
過去に遡ってシークし、前に確認済みのメッセージを再生する場合は、まずトピックのメッセージ保持を構成するか、または確認済みのメッセージを保持するようにサブスクリプションを構成する必要があります。
シーク オペレーションの結果整合性
メッセージ配信の保証に関してシーク オペレーションには完全な整合性があります。つまり、シーク条件に基づいて確認応答されていないと判定されるメッセージは、シーク オペレーションの成功後に最終的に配信されることが保証されます。ただし、配信されるメッセージが直ちにシーク オペレーションと一致することはありません。シーク タイムスタンプよりも前にパブリッシュされたメッセージ（またはスナップショット内の確認応答済みのメッセージ）はシーク オペレーション後に配信される可能性があります。ある意味で、メッセージ配信はシーク オペレーションと最終的に一致するシステムとして動作します。オペレーションが完全に有効になるまで 1 分ほどかかることがあります。
シーク オペレーションのユースケース
- サブスクライバー コードを安全に更新する。 新しいサブスクライバー コードをデプロイするとき、新しい実行可能ファイルがメッセージに誤って確認応答し、メッセージが失われることが懸念されます。この場合、デプロイ プロセスにスナップショットを組み込むことで、新しいサブスクライバー コードのバグから回復できます。
- 予期しないサブスクライバーの問題から回復する。サブスクライバーの問題が特定のデプロイ イベントに関係していないと、関連するスナップショットが存在しない可能性があります。この場合、サブスクリプションの確認応答済みのメッセージを保持する設定を有効化してあれば、過去の時点までシークすることでエラーから回復できます。
- 処理時間とコストを節約する。関連性のないメッセージの大きなバックログに対して一括で確認応答を行います。
- サブスクライバー コードを既知のデータでテストする。 サブスクライバー コードをテストしてパフォーマンスや一貫性の向上を図るときは、毎回の実行で同じデータを使用すると便利です。スナップショットにより、強力なセマンティクスを伴う一貫したデータが実現します。また、スナップショットは、新しく作成されたサブスクリプションを含む、所定のトピックの任意のサブスクリプションに適用できます。
メッセージ保持を構成する
トピックにメッセージ保持を構成できるだけでなく、そのサブスクリプションのいずれかを構成して確認済みのメッセージを保持することもできます。サブスクリプションで構成されているメッセージ保持時間よりも長く再生できるようにメッセージを保持する場合は、トピック メッセージの保持を構成することをおすすめします。この場合、トピックのプロジェクトとサブスクリプションのプロジェクトは、それぞれのメッセージ保持の設定に従ってメッセージの保存に対して課金されます。
トピックのメッセージ保持が設定されていない場合、経過時間がサブスクリプションの message_retention_duration プロパティを超えると、サブスクリプションから未確認応答メッセージが削除されます。一方、トピックのメッセージ保持が設定されている場合、未確認応答メッセージがサブスクリプションから削除されるのは、メッセージの経過時間がトピックとサブスクリプションの message_retention_duration の最大値を超える場合だけです。
トピック メッセージ保持を構成する
デフォルトでは、Pub/Sub トピックは、そのトピックに関連付けられたすべてのサブスクリプションによって確認応答された時点でメッセージを破棄します。メッセージ保持を使用してトピックを設定すると、柔軟性が高まり、そのトピックに関連付けられたサブスクリプションが過去に遡ってシークして、以前に確認応答済みのメッセージをトピックの message_retention_duration まで再生できます。
トピックのメッセージ保持を使用すると、サブスクリプションを作成する前にパブリッシュされたメッセージを再生することもできます。
トピックは、関連付けられたすべてのサブスクリプションによって確認応答された後、最大 31 日間（トピックの message_retention_duration プロパティで設定可能）は保持できます。トピックの message_retention_duration がサブスクリプションの message_retention_duration よりも大きい場合、Pub/Sub は年齢がトピックの message_retention_duration を超えている場合にのみメッセージを破棄します。
トピックのメッセージ保持が有効になっている場合、トピックが保持するメッセージのストレージ料金はトピックのプロジェクトに課金されます。
Console
メッセージ保持を有効にしたトピックを作成する方法は次のとおりです。
Google Cloud コンソールで、Pub/Sub の [トピック] ページに移動します。
[トピックを作成] をクリックします。
[トピック ID] に、トピックの ID を入力します。
[メッセージの保持期間を設定する] を有効にします。
他のオプションはデフォルト設定のままにします。
[メッセージ保持期間] プルダウン メニューを使用して、メッセージを保持する日数、時間、分を選択します。
[トピックを作成] をクリックしてトピックを保存します。
トピックのメッセージ保持設定を更新するには:
[Pub/Sub トピック] ページからトピックを選択します。
トピックの詳細ページの上部にある [編集] をクリックします。
保持期間を調整したり、メッセージの保持を有効または無効にするには、[メッセージ保持を有効にする] オプションをオンまたはオフにします。
[更新] をクリックして、トピックへの変更を保存します。
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 プロパティを介して保持されるようにサブスクリプションを構成すると、サブスクリプションによって保持された確認済みのメッセージを再生できます。メッセージは、サブスクリプション内で最大 7 日間保持するように構成できます。この構成は、確認応答済みメッセージと確認応答されていないメッセージの両方に適用されます。ただし、トピックでメッセージの保持期間が 7 日以上で構成されている場合、メッセージは 7 日以上サブスクリプションに保持されます。
サブスクリプションが確認済みメッセージを保持するように構成されている場合、サブスクリプションによって保持される確認応答済みメッセージのストレージ費用はサブスクリプションのプロジェクトに課金されます。
Console
確認応答済みメッセージの保持を有効にしてサブスクリプションを作成する手順は次のとおりです。
Google Cloud コンソールで、[Pub/Sub サブスクリプション] ページに移動します。
[サブスクリプションを作成] をクリックします。
[サブスクリプション ID] フィールドにサブスクリプションの ID を入力します。
[メッセージ保持期間] プルダウン メニューを使用して、メッセージを保持する日数、時間、分を選択します。
[確認済みメッセージを保持する] を有効にします。他のオプションはデフォルト設定のままにします。
[サブスクリプションを作成] をクリックしてサブスクリプションを保存します。
サブスクリプションのメッセージ保持設定を更新するには:
[Pub/Sub サブスクリプション] ページからサブスクリプションを選択します。
サブスクリプションの詳細ページの上部にある [編集] をクリックします。
メッセージの保持期間を調整するか、[確認済みメッセージを保持] というラベルが付いたフィールドをオンまたはオフにして、確認応答済みのメッセージの保持を有効または無効します。
[更新] をクリックして、サブスクリプションへの変更を保存します。
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 を使用します。
Console
スナップショットの作成手順は次のとおりです。
Google Cloud コンソールで、[スナップショット] ページに移動します。
[スナップショットを作成] をクリックします。
[Pub/Sub サブスクリプションを選択してください] で、サブスクリプションを選択します。
[スナップショット ID] には、スナップショットの名前を入力します。
Pub/Sub リソースの名前を指定する方法の詳細については、トピック、サブスクリプション、スキーマ、スナップショットの指定方法のガイドラインをご覧ください。
[作成] をクリックしてスナップショットを作成します。
[サブスクリプション] ページからスナップショットを作成することもできます。サブスクリプションを作成した直後にスナップショットを作成すると、新しく作成したサブスクリプションの伝播の遅延によりエラーが発生することがあります。
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 を使用します。サブスクリプションでタイムスタンプまでシークする前に、サブスクリプションでメッセージ保持が有効になっていることを確認します。
Console
特定のタイムスタンプまでシークする手順は次のとおりです。
Google Cloud コンソールの [IAM] ページに移動します。
メッセージ保持が有効になっているサブスクリプションをクリックします。
[サブスクリプションの詳細] ページで、[メッセージの再生] をクリックします。
[シーク] で [前の時点まで] をクリックします。
適切な日時を選択して、[シーク] をクリックします。
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 を使用して、スナップショットまでシークできます。
Console
スナップショットにシークする手順は次のとおりです。
Google Cloud コンソールの [IAM] ページに移動します。
サブスクリプションをクリックします。
[サブスクリプションの詳細] ページで、[メッセージの再生] をクリックします。
シークするには、[スナップショットまで] をクリックします。
適切なスナップショットを選択し、[シーク] をクリックします。
gcloud
特定のスナップショットまでシークするには、次の gcloud pubsub subscriptions seek コマンドを使用します。
gcloud pubsub subscriptions seek SUBSCRIPTION_ID \
--snapshot=SNAPSHOT_ID
次のように置き換えます。
- SNAPSHOT_ID: スナップショットの ID。スナップショットのトピックは、サブスクリプションのトピックと同一でなければなりません。
- SUBSCRIPTION_ID: サブスクリプションの ID。
フィルタでシークする
フィルタを含むサブスクリプションから取得したメッセージを再生できます。フィルタを含むサブスクリプションを使用してタイムスタンプまでシークすると、Pub/Sub サービスは、フィルタに一致するメッセージのみを再配信します。
フィルタを含むサブスクリプションのスナップショットには、次のメッセージが含まれます。
- スナップショットより新しいすべてのメッセージ（フィルタに一致しないメッセージも含む）
- スナップショットより古い、未承認のメッセージ。
フィルタを含むサブスクリプションを使用してスナップショットまでシークした場合、Pub/Sub サービスは、シークリクエストを行ったサブスクリプションのフィルタに一致する、スナップショット内のメッセージのみを再配信します。
フィルタの詳細については、メッセージのフィルタをご覧ください。
デッドレター トピックでシークする
デッドレター トピックを含むサブスクリプションのメッセージをシークすると、Pub/Sub は配信試行を 0 に設定します。これらのサブスクリプションから受信するメッセージには、配信試行回数を集計するフィールドがあります。
デッドレター トピックの詳細については、デッドレター トピックへの転送をご覧ください。
再試行ポリシーでシークする
再試行ポリシーを含むサブスクリプション内のメッセージをシークすると、Pub/Sub によって次の場合の遅延がリセットされます。
- 確認応答期限が切れる、またはサブスクライバーが否定応答を送信する。
- Pub/Sub によるメッセージの再送信。
再試行ポリシーの詳細については、再試行ポリシーの使用をご覧ください。
1 回限りの配信でシークする
サブスクリプション内で正確に 1 回配信を行うメッセージまでシークすると、以前に確認応答済みの配信対象メッセージが Pub/Sub により再送信されます。シーク オペレーションの前に行われた配信の確認応答は失敗します。シーク オペレーションには結果整合性があります。
再試行ポリシーの詳細については、1 回限りの配信をご覧ください。