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

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 呼び出しで指定されるオーディエンスパラメータで構成されます。また、次のセクションで説明するように、サービスエージェントに特定のロールを付与する必要があります。

ユーザーが管理するサービスアカウント（必須）。push サブスクリプションに関連付けられているサービスアカウント。このアカウントは、生成された JSON Web Token（JWT）の email クレームとして使用されます。サービスアカウントの要件は次のとおりです。
- このサービスアカウントは、プッシュサブスクリプションと同じプロジェクトに存在する必要があります。
- push サブスクリプションを作成または変更するプリンシパルには、サービスアカウントに対する iam.serviceAccounts.actAs 権限が必要です。プロジェクト、フォルダ、または組織に対してこの権限を付与することで、呼び出し元が複数のサービスアカウントの権限を借用することを許可するか、サービスアカウントでこの権限を持つロールを付与して、呼び出し元がこのサービスアカウントのみの権限を借用するできるようにすることができます。
オーディエンス。Webhook が特定のトークンの対象オーディエンスの検証に使用する、大文字と小文字が区別されない単一の文字列。
サービスエージェント（必須）
- 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" }
  ]
}
```