このページは Cloud Translation API によって翻訳されました。

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

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

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

始める前に

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

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

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

メッセージ保持期間

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

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

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

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

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

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

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

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

有効期限

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

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

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

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

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

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

確認応答の期限

確認期限オプションを使用すると、未確認メッセージが再度送信される最初の期限を指定できます。ModifyAckDeadline リクエストを続けて送ることで、メッセージごとに確認期限を延長できます。

[Acknowledgment deadline] オプションの値は次のとおりです。

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

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

単一メッセージ変換（SMT）

SMT を使用すると、Pub/Sub 内でメッセージ属性とデータに対する軽量な変更を直接行うことができます。この機能を使用すると、メッセージがサブスクライバークライアントに配信される前に、データのクリーンアップ、フィルタリング、形式変換を行うことができます。

詳細については、SMT の概要と SMT を使用してサブスクリプションを作成するをご覧ください。

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

このサブスクリプションフィルタオプションを使用して、フィルタリング式で文字列を指定します。。サブスクリプションにフィルタがある場合、サブスクリプションはフィルタに一致するメッセージのみを配信します。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 リージョンからベストエフォート方式でメッセージを配信します。

サブスクライバーがファイアウォールを使用している場合、push リクエストを受信できません。push リクエストを受信するには、ファイアウォールをオフにして、リクエストで使用されている JSON ウェブトークン（JWT）を検証する必要があります。購読者がファイアウォールを使用している場合、403 permission denied エラーが表示されることがあります。
Pub/Sub では、push サブスクリプションの URL ドメインの所有権の証明が不要になりました。ドメインが Pub/Sub からの予期しない POST リクエストを受信した場合は、不正行為を報告できます。

認証

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

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

オーディエンス。Webhook が特定のトークンの対象オーディエンスの検証に使用する、大文字と小文字が区別されない単一の文字列。
サービスアカウント。Pub/Sub は、service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com 形式のサービスアカウントを自動的に作成します。

認証を有効にするための前提条件

ユーザー管理サービスアカウントは、push サブスクリプションに関連付けられているサービスアカウントです。このアカウントは、生成された JSON ウェブトークン（JWT）の email クレームとして使用されます。サービスアカウントの要件は次のとおりです。

このユーザー管理のサービスアカウントは、プッシュサブスクリプションと同じプロジェクトに存在する必要があります。
push サブスクリプションを作成または変更するプリンシパルには、サービスアカウントを push サブスクリプションに関連付けるために、ユーザー管理のサービスアカウントに対する iam.serviceAccounts.actAs 権限が必要です。詳細については、サービスアカウントをリソースに関連付けるをご覧ください。
必要な権限: このサービスアカウントには、Pub/Sub が指定されたサービスアカウントの JWT トークンを作成して push リクエストを認証できるように、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 メッセージのフィールドを対応する列に書き込むことができます。このオプションを使用する場合は、次の追加要件を確認してください。

BigQuery テーブルの各列の名前には、英字（a ～ z、A ～ Z）、数字（0 ～ 9）、アンダースコア（_）のみを使用できます。
公開されるメッセージは JSON 形式である必要があります。

BigQuery テーブル列のデータ型が JSON の場合、Pub/Sub メッセージ内の対応するフィールドは、エスケープされた文字列内の有効な JSON である必要があります。たとえば、myData という名前の列の場合、メッセージフィールドは "myData": "{\"key\":\"value\"}" にする必要があります。BigQuery は、有効な JSON が含まれていないメッセージを拒否します。

次の JSON 変換がサポートされています。

JSON 型	BigQuery のデータ型
`string`	`NUMERIC`、`BIGNUMERIC`、`DATE`、`TIME`、`DATETIME`、または `TIMESTAMP`
`number`	`NUMERIC`、`BIGNUMERIC`、`DATE`、`TIME`、`DATETIME`、または `TIMESTAMP`

number から DATE、DATETIME、TIME、または TIMESTAMP への変換を使用する場合、数値はサポートされている表現に準拠している必要があります。
number から NUMERIC または BIGNUMERIC へのコンバージョンを使用する場合、値の適合率と範囲は、浮動小数点演算の IEEE 754 標準で許容されるものに制限されます。高い適合率やより広い範囲の値が必要な場合は、代わりに string から NUMERIC または BIGNUMERIC へのコンバージョンを使用します。
string から NUMERIC または BIGNUMERIC へのコンバージョンを使用する場合、Pub/Sub は文字列が人間が判読できる数値（"123.124" など）であると想定します。文字列を人間が判読できる数値として処理できない場合、Pub/Sub は文字列を BigDecimalByteStringEncoder でエンコードされたバイトとして扱います。

サブスクリプションのトピックにスキーマが関連付けられている場合、メッセージエンコードプロパティは JSON に設定する必要があります。
メッセージに存在しない BigQuery フィールドがある場合、これらの BigQuery フィールドは NULLABLE モードにする必要があります。
BigQuery スキーマに存在しない追加のフィールドがメッセージにあり、このようなフィールドを削除できる場合は、[不明なフィールドを削除する] オプションを選択します。
サブスクリプションプロパティとして [トピックスキーマを使用する] または [テーブルスキーマを使用する] のいずれか 1 つのみを選択できます。

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

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

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

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

不明な項目を削除する

このオプションは、[トピックスキーマを使用する] または [テーブルスキーマを使用する] オプションで使用します。このオプションを有効にすると、Pub/Sub は、トピックスキーマやメッセージには存在するが BigQuery スキーマには存在しないフィールドをドロップできます。BigQuery スキーマに含まれていないフィールドは、BigQuery テーブルにメッセージを書き込むときに削除されます。

[不明な項目を削除する] が設定されていない場合、デッドレタートピックを構成しない限り、余分な項目を含むメッセージは BigQuery に書き込まれず、サブスクリプションバックログに残ります。

[不明な項目を削除する] 設定は、Pub/Sub トピックスキーマまたは BigQuery テーブルスキーマのいずれにも定義されていないフィールドには影響しません。この場合、有効な Pub/Sub メッセージがサブスクリプションに配信されます。ただし、BigQuery にはこれらの追加フィールド用に定義された列がないため、これらのフィールドは BigQuery 書き込みプロセス中に削除されます。この動作を防ぐには、Pub/Sub メッセージに含まれるフィールドが BigQuery テーブルスキーマにも含まれていることを確認してください。

追加フィールドに関する動作は、使用する特定のスキーマタイプ（Avro、Protocol Buffer）とエンコード（JSON、バイナリ）によっても異なります。これらの要因が追加フィールドの処理にどのように影響するかについては、特定のスキーマタイプとエンコードのドキュメントをご覧ください。

メタデータを書き込む

このオプションを使用すると、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 です。
- ファイル名の日時形式が matcher ではない文字で終わる場合、その文字が <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
ストレージバッチの最大メッセージ数。この設定は省略できます。指定した最大メッセージ数を超えると、Cloud Storage サブスクリプションが新しい出力ファイルを書き込みます。最大メッセージ数に使用可能な値は次のとおりです。
- 最小値 = 1000

たとえば、最大時間を 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、attributes などのメタデータのフィールドが、出力 Avro オブジェクトの最上位フィールドに書き込まれ、データ以外のすべてのメッセージプロパティ（たとえば、存在する場合 ordering_key）は、attributes マップのエンティティとして追加されます。
  
  [メタデータの書き込み] が無効になっている場合、メッセージペイロードのみが出力 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" }
  ]
}
```
- トピックスキーマを使用する: このオプションを使用すると、Pub/Sub は、Avro ファイルの書き込み時に、サブスクリプションが接続されている Pub/Sub トピックのスキーマを使用できます。
  
  このオプションを使用する場合は、以下の追加要件を確認してください。
  - トピックスキーマは Apache Avro 形式にする必要があります。
  - [トピックスキーマを使用する] と [メタデータを書き込む] の両方が有効になっている場合、トピックスキーマのルートには Record オブジェクトが必要です。Pub/Sub は、メタデータフィールドを含めるように Record のフィールドのリストを拡張します。そのため、レコードにメタデータフィールド（subscription_name、message_id、publish_time、attributes）と同じ名前のフィールドを含めることはできません。

サービスアカウント

BigQuery テーブルまたは Cloud Storage バケットにメッセージを書き込むには、次のオプションがあります。

サービスアカウントに対する iam.serviceAccounts.actAs 権限を持つユーザーのみが、テーブルまたはバケットに書き込むサブスクリプションを作成できるように、カスタムサービスアカウントを構成します。iam.serviceAccounts.actAs 権限を含むロールの例として、サービスアカウントユーザー（roles/iam.serviceAccountUser）ロールがあります。
プロジェクトでサブスクリプションを作成できるユーザーがテーブルまたはバケットに書き込むサブスクリプションを作成できるようにするデフォルトの Pub/Sub サービスエージェントを使用します。カスタムサービスアカウントを指定しない場合、Pub/Sub サービスエージェントがデフォルト設定になります。