サブスクリプションプロパティ

Pub/Sub サブスクリプションのプロパティは、サブスクリプションの特性です。サブスクリプションプロパティは、サブスクリプションを作成または更新するときに設定できます。

このドキュメントでは、サブスクリプションに設定可能なさまざまなサブスクリプションプロパティについて説明します。

準備

サブスクリプションについて確認する。
作成するサブスクリプションのワークフロー（pull、push、BigQuery）を理解します。

共通のサブスクリプションプロパティ

サブスクリプションを作成するときに、サブスクリプションを設定するいくつかのオプションを指定する必要があります。これらのプロパティの一部はすべてのタイプのサブスクリプションに共通しています。次のセクションで説明します。

メッセージ保持期間

メッセージの保持期間オプションにより、Pub/Sub がパブリッシュ後にメッセージを保持する期間が指定されます。メッセージの保持期間が経過すると、Pub/Sub はメッセージの確認応答状態とは無関係にメッセージを破棄する場合があります。メッセージ保持期間の間の確認済みメッセージの保持については、メッセージの再生と破棄をご覧ください。

[メッセージ保持期間] オプションの値は次のとおりです。

デフォルト値: 7 日
最小値: 10 分。
最大値: 7 日

未確認メッセージの原因は、アイドル状態のサブスクリプション、バックアップのニーズ、処理速度が遅いことである可能性があります。24 時間以内にメッセージを処理できれば追加料金は発生しません。新しい料金が発生しないようにするには、これらのシナリオを次のように管理します。

アイドル状態のサブスクリプション。アイドル状態のサブスクリプションを削除して、サブスクリプションのメッセージ保持料金が発生しないようにします。
バックアップストレージ。サブスクリプションの保持をバックアップストレージとして使用している場合は、トピックのメッセージ保持や確認済みメッセージの保持などの別のストレージオプションに切り替えることができます。トピックのメッセージ保持では、メッセージをトピックレベルで 1 回のみ保存し、必要に応じてすべてのサブスクリプションで使用できるよう、利用可能に保たれます。
処理の遅延。1 日以内にメッセージを処理できるように、サブスクライバーを追加します（可能な場合）。

確認済みメッセージを保持する

メッセージ保持期間を指定すると、確認済みメッセージを保持するかどうかも指定できます。

[確認済みメッセージを保持] オプションを使用すると、指定したメッセージ保持期間の間、確認済みメッセージを保持できます。このオプションを使用すると、メッセージのストレージ料金が発生します。詳細については、ストレージの費用をご覧ください。

有効期限

[有効期限] オプションを使用すると、サブスクリプションの有効期限を延長できます。

サブスクライバーのアクティビティまたはサブスクリプションプロパティへの変更がないサブスクリプションは、期限切れになります。Pub/Sub がサブスクライバーのアクティビティを検出するか、サブスクリプションプロパティを更新すると、サブスクリプション削除クロックが再起動されます。サブスクライバーのアクティビティの例には、オープン接続、アクティブな pull、push の成功などがあります。

有効期限を指定する場合は、メッセージ保持期間オプションで指定されたメッセージの保持期間よりも長くする必要があります。

[有効期限] オプションの値は次のとおりです。

デフォルト値: 31 日
最小値: 1 日
最大値: 365 日

サブスクリプションの有効期限が切れないようにするには、有効期限を never expire に設定します。

確認応答の期限。

[確認応答期限] オプションは、確認応答されていないメッセージが再送信される最初の期限を指定します。後続の ModifyAckDeadline リクエストを送信することで、メッセージごとに確認応答期限を延長できます。

確認応答期限オプションの値は次のとおりです。

デフォルト値: 10 秒
最小値: 10 秒
最大値: 600 秒

場合によっては、Pub/Sub クライアントライブラリによって配信レートを制御し、確認応答期限を動的に変更できます。その場合、設定した確認応答期限の前にメッセージが再配信される可能性があります。この動作をオーバーライドするには、minDurationPerAckExtension と maxDurationPerAckExtension を使用します。これらの値の使用の詳細については、クライアントライブラリでの 1 回限りの配信のサポートをご覧ください。

サブスクリプションフィルタ

このサブスクリプションフィルタオプションを使用して、フィルタリング式で文字列を指定します。。サブスクリプションにフィルタがある場合、サブスクリプションはフィルタに一致するメッセージのみを配信します。Pub/Sub サービスは、フィルタに一致しないメッセージの確認応答を自動的に行います。

メッセージは属性でフィルタできますが、メッセージ内のデータではフィルタできません。
指定がない場合は、サブスクリプションはメッセージをフィルタせず、サブスクライバーはすべてのメッセージを受け取ります。
フィルタは、適用後に変更または削除することはできません。

フィルタを含むサブスクリプションからメッセージを受信した場合、Pub/Sub が自動的に確認応答するメッセージに対して下り料金は発生しません。これらのメッセージに対しては、メッセージ配信料金とシーク関連のストレージ料金が発生します。

詳しくは、サブスクリプションからのメッセージをフィルタするをご覧ください。

メッセージの順序指定

サブスクリプションでメッセージの順序指定が有効になっている場合、サブスクライバークライアントは、サービスが受信した順序と同じ順序指定キーを持つ同じリージョンにパブリッシュされたメッセージを受信します。

順序付けされた配信を使用する場合、後のメッセージの確認応答は、以前のメッセージの確認応答が処理されるまで処理されません。

Pub/Sub がメッセージを順に配信できるように、パブリッシャーは順序指定キーを使用してメッセージを送信する必要があります。

設定されていない場合は、順序指定キーが存在しても、Pub/Sub がメッセージを順に配信しない可能性があります。

デッドレタートピック

設定した配信試行回数に達した後にメッセージを配信できない場合、またはサブスクライバーがメッセージを確認応答できない場合、こうしたメッセージに対してデッドレタートピックを構成できます。これは再公開可能です。

デッドレタートピックを設定する場合は、配信の最大試行回数も指定できます。デッドレタートピックの最大配信試行回数は次のとおりです。

デフォルト値 = 5 回の配信試行
最小値 = 5 回の配信試行
最大値: 100 配信試行

デッドレタートピックがサブスクリプションとは異なるプロジェクトにある場合は、デッドレタートピックとともにプロジェクト ID も指定する必要があります。

詳しくは、デッドレタートピックへの転送をご覧ください。

再試行ポリシー

確認応答期限が切れた場合、またはサブスクライバーが否定応答をした場合、Pub/Sub はメッセージを再度送信できます。この再配信の試行は、サブスクリプションの再試行ポリシーと呼ばれます。

デフォルトでは、サブスクリプションの再試行ポリシーは [すぐに再試行] を使用するように設定されています。このオプションを使用すると、確認応答期限が切れるか、サブスクライバーから否定応答が返されると、Pub/Sub はメッセージを再送信します。

値を [指数バックオフ遅延後の再試行] に設定することもできます。この場合、バックオフの最大値と最小値を指定する必要があります。

バックオフの最大値と最小値を設定するためのガイドラインを以下に示します。

バックオフ期間の最大値を設定した場合、最小バックオフ期間のデフォルト値は 10 秒です。
バックオフ期間の最小値を設定した場合、最大バックオフ期間のデフォルト値は 600 秒です。
指定できるバックオフ期間の最長値は 600 秒です。

ポリシーとバッチメッセージの再試行

メッセージがバッチにまとまっている場合、次のいずれかが発生すると、Pub/Sub は指数バックオフを開始します。

サブスクライバーにより、バッチ内のすべてのメッセージに対して否定応答が送信される。
確認応答期限が切れた。

ポリシーを再試行してサブスクリプションを push する

push サブスクリプションからメッセージを受信すると、指数バックオフ期間ではなく push バックオフ期間の経過後に、Pub/Sub がメッセージを再配信する場合があります。push バックオフの期間が指数バックオフの期間よりも長い場合、Pub/Sub は push バックオフ期間の経過後に確認応答していないメッセージを再配信します。

pull サブスクリプションプロパティ

pull サブスクリプションを構成するときに、次のプロパティを指定できます。

1 回限りの配信

1 回限りの配信。設定すると、Pub/Sub によって 1 回限りの配信の保証が履行されます。指定しない場合、サブスクリプションでメッセージごとに少なくとも 1 回の配信がサポートされます。

push サブスクリプションプロパティ

push サブスクリプションを構成するときに、次のプロパティを指定できます。

エンドポイント

エンドポイント URL（必須）。 一般公開されている HTTPS アドレス。push エンドポイントのサーバーには、認証局が署名した有効な SSL 証明書が必要です。Pub/Sub サービスでは、Pub/Sub サービスがメッセージを格納するのと同じ Google Cloud リージョンから push エンドポイントにメッセージを配信します。Pub/Sub サービスでは、同じ Google Cloud リージョンからベストエフォート方式でメッセージを配信します。

Pub/Sub では、push サブスクリプションの URL ドメインの所有権の証明が不要になりました。ドメインが Pub/Sub からの予期しない POST リクエストを受信した場合は、不正行為を報告できます。

Authentication

認証を有効にする。有効にすると、Pub/Sub によって push エンドポイントに配信されるメッセージに、エンドポイントがリクエストを認証するための承認ヘッダーが含まれます。サブスクリプションと同じプロジェクトでホストされる App Engine Standard エンドポイントと Cloud Functions エンドポイントでは、自動認証と自動承認のメカニズムを使用できます。

認証済み push サブスクリプションの認証構成は、ユーザーが管理するサービスアカウントと、create、patch または ModifyPushConfig 呼び出しで指定されるオーディエンスパラメータで構成されます。また、次のセクションで説明するように、特別な Google が管理するサービスアカウントに特定のロールを付与する必要もあります。

ユーザーが管理するサービスアカウント（必須）。push サブスクリプションに関連付けられているサービスアカウント。このアカウントは、生成された JSON Web Token（JWT）の email クレームとして使用されます。サービスアカウントの要件は次のとおりです。
- このサービスアカウントは、push サブスクリプションと同じプロジェクトに存在する必要があります。
- push サブスクリプションを作成または変更するプリンシパルには、サービスアカウントに対する iam.serviceAccounts.actAs 権限が必要です。プロジェクト、フォルダ、または組織に対してこの権限を付与することで、呼び出し元が複数のサービスアカウントの権限を借用することを許可するか、サービスアカウントでこの権限を持つロールを付与して、呼び出し元がこのサービスアカウントのみの権限を借用するできるようにすることができます。
オーディエンス。Webhook が特定のトークンの対象オーディエンスの検証に使用する、大文字と小文字が区別されない単一の文字列。
Google が管理するサービスアカウント（必須）。
- Pub/Sub により、service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com 形式のサービスアカウントが自動的に作成されます。
- このサービスアカウントに、Pub/Sub が認証された push リクエスト用の JWT トークンを作成できるように、iam.serviceAccounts.getOpenIdToken 権限（roles/iam.serviceAccountTokenCreator ロールに含まれる）が付与されている必要があります。

ペイロードのラップ解除

[ペイロードのラップ解除を有効にする] オプションは、メッセージデータを除くすべてのメッセージメタデータの Pub/Sub メッセージを削除します。ペイロードのラップ解除により、メッセージデータは HTTP 本文として直接配信されます。

メタデータを書き込む。前に削除されたメッセージメタデータをリクエストヘッダーに追加し直します。

BigQuery プロパティ

[BigQuery への書き込み] としてサブスクリプション配信タイプを選択する場合は、次の追加プロパティを指定できます。

トピックスキーマを使用する

このオプションにより、Pub/Sub は、サブスクリプションが接続されている Pub/Sub トピックのスキーマを使用できます。さらに、Pub/Sub はメッセージ内のフィールドを BigQuery テーブル内の対応する列に書き込みます。

このオプションを使用する場合は、以下の追加要件を確認してください。

トピックスキーマ内のフィールドと BigQuery スキーマ内のフィールドは、同じ名前でなければならず、その型には相互に互換性が必要です。
トピックスキーマのオプションフィールドは BigQuery スキーマでも省略可能な必要があります。
トピックスキーマの必須フィールドは、BigQuery スキーマでは必要ありません。
BigQuery フィールドがトピックスキーマに存在しない場合、これらの BigQuery フィールドは NULLABLE モードにする必要があります。
トピックスキーマに、BigQuery スキーマに存在しない追加のフィールドがあり、このようなフィールドを削除できる場合は、[不明な項目を削除する] オプションを選択します。
サブスクリプションプロパティとして [トピックスキーマを使用する] または [テーブルスキーマを使用する] のいずれか 1 つのみを選択できます。

[トピックスキーマを使用する] または [テーブルスキーマを使用する] オプションを選択しない場合は、BigQuery テーブルに、BYTES、STRING、または JSON 型の data という列があることを確認してください。Pub/Sub は、この BigQuery 列にメッセージを書き込みます。

Pub/Sub トピックスキーマまたは BigQuery テーブルスキーマの変更は、BigQuery テーブルに書き込まれたメッセージにすぐに反映されない場合があります。たとえば、[不明なフィールドを削除する] オプションが有効で、フィールドが Pub/Sub スキーマには存在するが BigQuery スキーマにはない場合、BigQuery テーブルに書き込まれるメッセージには、BigQuery スキーマに追加した後も、フィールドが含まれていない場合があります。最終的に、スキーマが同期され、後続のメッセージにこのフィールドが含まれます。

BigQuery サブスクリプションで [テーブルスキーマを使用する] オプションを使用すると、BigQuery 変更データキャプチャ（CDC）も利用できます。CDC は、既存の行を処理して変更を適用し、BigQuery テーブルを更新します。

この機能の詳細については、変更データキャプチャを使用してテーブル更新をストリーミングするをご覧ください。

BigQuery サブスクリプションでこの機能を使用する方法については、BigQuery の変更データキャプチャをご覧ください。

テーブルスキーマを使用する

このオプションにより、Pub/Sub は BigQuery テーブルのスキーマを使用して、JSON メッセージのフィールドを対応する列に書き込むことができます。このオプションを使用する場合は、次の追加要件を確認してください。

公開されるメッセージは JSON 形式である必要があります。
サブスクリプションのトピックにスキーマが関連付けられている場合は、メッセージエンコードプロパティを JSON に設定する必要があります。
メッセージに存在しない BigQuery フィールドがある場合、これらの BigQuery フィールドは NULLABLE モードにする必要があります。
BigQuery スキーマに存在しない追加のフィールドがメッセージにあり、このようなフィールドを削除できる場合は、[不明なフィールドを削除する] オプションを選択します。
JSON メッセージでは、DATE、DATETIME、TIME、TIMESTAMP の値は、サポートされている表現に準拠する整数でなければなりません。
JSON メッセージでは、NUMERIC と BIGNUMERIC の値は、BigDecimalByteStringEncoder を使用してバイトエンコードする必要があります。
サブスクリプションプロパティとして [トピックスキーマを使用する] または [テーブルスキーマを使用する] のいずれか 1 つのみを選択できます。

BigQuery テーブルスキーマの変更は、BigQuery テーブルに書き込まれたメッセージにすぐに反映されない場合があります。たとえば、[不明なフィールドを削除する] オプションが有効で、フィールドがメッセージには存在するが BigQuery スキーマにはない場合、BigQuery テーブルに書き込まれるメッセージには、BigQuery スキーマに追加した後も、フィールドが含まれていない場合があります。最終的に、スキーマが同期され、後続のメッセージにこのフィールドが含まれます。

BigQuery サブスクリプションで [テーブルスキーマを使用する] オプションを使用すると、BigQuery 変更データキャプチャ（CDC）も利用できます。 CDC は、既存の行を処理して変更を適用し、BigQuery テーブルを更新します。

この機能の詳細については、変更データキャプチャを使用してテーブル更新をストリーミングするをご覧ください。

BigQuery サブスクリプションでこの機能を使用する方法については、BigQuery 変更データキャプチャをご覧ください。

不明な項目を削除する

このオプションは、[トピックスキーマを使用する] または [テーブルスキーマを使用する] オプションで使用します。このオプションを使用すると、Pub/Sub は、トピックスキーマやメッセージには存在するが BigQuery スキーマには存在しないフィールドをドロップできます。[不明な項目を削除する] が設定されていない場合、余分な項目を含むメッセージは BigQuery に書き込まれず、サブスクリプションバックログに残ります。サブスクリプションがエラー状態になります。

メタデータを書き込む

このオプションを使用すると、Pub/Sub が各メッセージのメタデータを BigQuery テーブルの追加の列に書き込むようにする場合は、このオプションを選択できます。それ以外の場合、メタデータは BigQuery テーブルに書き込まれません。

[メタデータを書き込む] オプションを選択する場合は、BigQuery テーブルに次の表に示すフィールドがあることを確認してください。

メタデータを書き込むオプションを選択しない場合、use_topic_schema が true でない限り、宛先 BigQuery テーブルでは data フィールドのみが必要になります。[メタデータを書き込む] と [トピックスキーマを使用する] の両方のオプションを選択した場合、トピックのスキーマには、次の名前にメタデータパラメータと一致する名前のフィールドを含めないでください。この制限には、スネークケースパラメータのキャメルケースバージョンが含まれます。

パラメータ
`subscription_name`	STRING サブスクリプションの名前。
`message_id`	STRING メッセージの ID
`publish_time`	TIMESTAMP メッセージのパブリッシュ時刻。
`data`	BYTES、STRING、または JSON メッセージの本文。 `data` フィールドは、[トピックスキーマを使用する] を選択しないすべての宛先 BigQuery テーブルに必要です。フィールドの型が JSON の場合、メッセージ本文を有効な JSON にする必要があります。
`attributes`	STRING または JSON すべてのメッセージ属性を含む JSON オブジェクト。また、存在する場合、順序指定キーなど、Pub/Sub メッセージの一部である追加のフィールドも含まれています。

Cloud Storage のプロパティ

[Cloud Storage への書き込み] でサブスクリプション配信タイプを選択する場合は、次の追加プロパティを指定できます。

バケット名

Cloud Storage サブスクリプションを作成する前に、Cloud Storage バケットがすでに存在している必要があります。

メッセージはバッチとして送信され、Cloud Storage バケットに保存されます。単一のバッチまたはファイルは、バケットにオブジェクトとして保存されます。

Cloud Storage バケットでは、リクエスト元による支払いを無効にする必要があります。

Cloud Storage バケットを作成するには、バケットの作成をご覧ください。

ファイル名の接頭辞、接尾辞、日時

Cloud Storage サブスクリプションによって生成された Cloud Storage 出力ファイルは、オブジェクトとして Cloud Storage バケットに保存されます。Cloud Storage バケットに格納されているオブジェクトの名前は、<file-prefix><UTC-date-time>_<uuid><file-suffix> の形式になります。

次のリストに、ファイル形式とカスタマイズ可能なフィールドの詳細を示します。

<file-prefix> は、カスタムファイル名の接頭辞です。このフィールドは省略できます。
<UTC-date-time> は、オブジェクトの作成時間に基づいて自動生成されるカスタマイズ可能な文字列です。
<uuid> は、オブジェクトに対して自動生成されるランダムな文字列です。
<file-suffix> は、カスタムファイル名の接尾辞です。このフィールドは省略できます。ファイル名の接尾辞を「/」で終わることはできません。
ファイル名の接頭辞と接尾辞を変更できます。
- たとえば、ファイル名接頭辞の値が prod_ で、ファイル名接尾辞の値が _archive の場合、サンプルオブジェクト名は prod_2023-09-25T04:10:00+00:00_uN1QuE_archive です。
- ファイル名の接頭辞と接尾辞を指定しなかった場合、Cloud Storage バケットに保存されるオブジェクト名は <UTC-date-time>_<uuid> の形式になります。
- Cloud Storage オブジェクトの命名要件は、ファイル名の接頭辞と接尾辞にも適用されます。詳細については、Cloud Storage オブジェクトについてをご覧ください。
ファイル名での日時の表示方法を変更できます。
- 1 回だけ使用できる必須の日時マッチャー: 年（YYYY または YY）、月（MM）、日（DD）、時（hh）、分（mm）、秒（ss）。たとえば、YY-YYYY や MMM は無効です。
- 1 回だけ使用できる任意のマッチャー: 日時区切り文字（T）とタイムゾーンオフセット（Z または +00:00）。
- 複数回使用できるオプション要素: ハイフン（-）、アンダースコア（_）、コロン（:）、スラッシュ（/）。
- たとえば、ファイル名の日時形式の値が YYYY-MM-DD/hh_mm_ssZ の場合、サンプルオブジェクト名は prod_2023-09-25/04_10_00Z_uNiQuE_archive です。
- ファイル名の日時形式がマッチャー以外の文字で終わる場合、<UTC-date-time> と <uuid> の間の区切り文字はその文字に置き換えられます。たとえば、ファイル名の日時形式の値が YYYY-MM-DDThh_mm_ss- の場合、サンプルオブジェクト名は prod_2023-09-25T04_10_00-uNiQuE_archive です。

ファイルのバッチ処理

Cloud Storage サブスクリプションでは、新しい出力ファイルを作成するタイミングを決定して、Cloud Storage バケットにオブジェクトとして保存できます。Pub/Sub は、指定されたバッチ処理条件のいずれかに一致すると、出力ファイルを書き込みます。Cloud Storage のバッチ処理条件は次のとおりです。

ストレージのバッチ最大時間。これは必須の設定です。Cloud Storage サブスクリプションは、指定された最大値を超えると、新しい出力ファイルを書き込みます。値を指定しない場合、デフォルト値の 5 分が適用されます。最大時間が適用される値は次のとおりです。
- 最小値: 1 分
- デフォルト値: 5 分
- 最大値: 10 分。
ストレージのバッチ最大バイト数。この設定は省略できます。Cloud Storage サブスクリプションは、指定された最大バイト数を超えると、新しい出力ファイルを書き込みます。最大バイト数に適用される値は次のとおりです。
- 最小値: 1 KB
- 最大値: 10 GiB

たとえば、最大期間を 6 分、最大バイト数を 2 GB に構成できます。4 分で、出力ファイルがファイルサイズ 2 GB に達すると、Pub/Sub は前のファイルをファイナライズし、新しいファイルへの書き込みを開始します。

Cloud Storage サブスクリプションが Cloud Storage バケット内の複数のファイルに同時に書き込みを行うことができます。6 分ごとに新しいファイルを作成するようにサブスクリプションを構成した場合、6 分ごとに複数の Cloud Storage ファイルが作成されることがあります。

場合によっては、ファイルのバッチ処理の条件で構成されているよりも前に、Pub/Sub が新しいファイルへの書き込みを開始することがあります。サブスクリプションが最大バイト数の値より大きいメッセージを受信した場合、ファイルが最大バイト数の値を超えることもあります。

ファイル形式

Cloud Storage サブスクリプションを作成するときに、Cloud Storage バケットに格納される出力ファイルの形式を テキストまたは Avro として指定できます。

テキスト: メッセージは書式なしテキストとして保存されます。改行文字により、ファイル内の前のメッセージからメッセージが分離されます。メッセージペイロードのみが保存され、属性やその他のメタデータは保存されません。
Avro: メッセージは Apache Avro バイナリ形式で保存されます。

[Avro] を選択した場合は、さらに [書き込みメタデータ] オプションを有効にできます。このオプションを使用すると、メッセージのメタデータをメッセージとともに保存できます。

subscription_name、message_id、publish_time などのメタデータと属性のフィールドが、出力 Avro オブジェクトの最上位フィールドに書き込まれ、データ以外のすべてのメッセージプロパティ（たとえば、存在する場合 ordering_key）は、属性マップのエンティティとして追加されます。

書き込みメタデータが無効になっている場合、メッセージペイロードのみが出力 Avro オブジェクトに書き込まれます。

書き込みメタデータを有効にしていない出力メッセージの Avro スキーマは次のとおりです。
```
{
  "type": "record",
  "namespace": "com.google.pubsub",
  "name": "PubsubMessage",
  "fields": [
    { "name": "data", "type": "bytes" }
  ]
}
```
書き込みメタデータが有効になっている出力メッセージの Avro スキーマは次のとおりです。
```
{
  "type": "record",
  "namespace": "com.google.pubsub",
  "name": "PubsubMessageWithMetadata",
  "fields": [
    { "name": "subscription_name", "type": "string" },
    { "name": "message_id", "type": "string"  },
    { "name": "publish_time", "type": {
        "type": "long",
        "logicalType": "timestamp-micros"
      }
    },
    { "name": "attributes", "type": { "type": "map", "values": "string" } },
    { "name": "data", "type": "bytes" }
  ]
}
```