Cloud Storage の Pub/Sub 通知

設定

このページでは、Cloud Storage の Pub/Sub 通知の概要を説明します。

概要

Pub/Sub 通知は、バケット内のオブジェクトに変更が加えられるとその情報を Pub/Sub に送信します。情報は、メッセージの形式で選択した Pub/Sub トピックに追加されます。これにより、バケット内で作成されたオブジェクトと削除されたオブジェクトの追跡などを行えます。各通知には、トリガーとなったイベントと変更されたオブジェクトの両方の情報が含まれます。

通知は、自分に必要な権限が付与されているプロジェクトの任意の Pub/Sub トピックに送信できます。Pub/Sub トピックで受信されると、トピックのサブスクライバーは関連するメッセージを受信できます。Cloud Storage バケットを Pub/Sub トピックに接続する方法については、前提条件をご覧ください。

他の通知オプション

Pub/Sub 通知に登録すると、バケット内で発生した変更に対してアラートをトリガーし、アクションを実行できます。ほかに、次の方法もあります。

  • Cloud Run functions: Pub/Sub のトピックを管理するのではなく、イベントへのレスポンスとしてスタンドアロン型の軽量関数のみトリガーする場合は、Cloud Run functions を使用します。Cloud Run functions を使用すると、バケット内のオブジェクトが変更されたときに、C#、Go、Java、Node.js、Python、PHP、Ruby の関数を実行できます。バケットは Cloud Run functions と同じプロジェクトに存在する必要があります。Cloud Storage で Cloud Run functions を使用する方法については、関連するチュートリアルをご覧ください。

  • オブジェクト変更通知: オブジェクト変更通知は、通知を生成する Cloud Storage の古い別の機能です。この機能は、別に設定したクライアント アプリケーションに HTTPS メッセージを送信します。一般に、Pub/Sub 通知のほうが低価格で、使いやすく、柔軟性に優れているため、この機能を使用することはおすすめしません。

通知構成

通知構成はバケットに適用されるルールで、次の項目を指定します。

  • 通知を受信する Pub/Sub トピック
  • 通知の送信をトリガーするイベント
  • 通知に含まれる情報

1 つのバケットに複数の通知構成を適用できます。バケットには通知構成を合計で 100 個まで設定できます。また、特定のイベントのトリガー用に、最大 10 個の通知構成を設定できます。

たとえば、削除通知を 1 つの Pub/Sub トピックに送信する通知構成がある場合、別のトピックに削除通知を送信する別の通知構成をバケットに追加できます。ただし、同じイベントに対して 10 個を超える通知構成を作成しようとすると、エラーが発生します。また、オブジェクトの作成などの他のイベントを通知する構成も作成できます。この通知は、削除通知の送信を構成した Pub/Sub トピックだけでなく、別のトピックにも送信できます。

各通知構成は整数値で識別されます。次の場合に、この整数値が返されます。

  • 通知設定を作成したとき
  • バケットの通知構成のリストを作成したとき
  • 通知構成によってトリガーされる各通知の notificationConfig 属性内

通知構成の作成、削除を行うと、バケットのメタ世代番号が増えます。

イベントタイプ

Cloud Storage でサポートされているイベントの種類は次のとおりです。

イベントタイプ 説明
OBJECT_FINALIZE バケットで新しいオブジェクト（または既存オブジェクトの新しい世代）が正常に作成された場合に送信されます。既存のオブジェクトをコピー、再作成、または復元した場合にも送信されます。アップロードが失敗した場合、このイベントはトリガーされません。
OBJECT_METADATA_UPDATE 既存オブジェクトのメタデータが変更された場合に送信されます。
OBJECT_DELETE オブジェクトが完全に削除された場合に送信されます。バケットのライフサイクル構成で置換または削除されたオブジェクトも対象になります。非現行オブジェクト（OBJECT_ARCHIVE を参照）になったオブジェクトや、マルチパート アップロードが中止されたオブジェクトは含まれません。
OBJECT_ARCHIVE バケットでオブジェクトのバージョニングが有効になっている場合にのみ送信されます。このイベントは、明示的に非現行になったか、同じ名前のオブジェクトのアップロードによって置換されたことにより、オブジェクトのライブ バージョンが非現行バージョンになったことを表します。

バケット オペレーションやオブジェクトの読み取りなど、他の Cloud Storage イベントについては、Cloud Audit Logs で適切な監査ログのタイプを有効にし、フィルタを使用して監査ログを Pub/Sub に転送できます。

オブジェクトの置換

既存のオブジェクトを同じ名前の新しいオブジェクトで置換すると、2 つのイベントがトリガーされます。1 つはオブジェクトの新しいバージョンに対する OBJECT_FINALIZE、もう 1 つは置換されたオブジェクトに対する OBJECT_ARCHIVE または OBJECT_DELETE です。OBJECT_FINALIZE イベントには追加の属性 overwroteGeneration が含まれます。これにより、置換されたオブジェクトの世代番号が示されます。OBJECT_ARCHIVE イベントまたは OBJECT_DELETE イベントには追加の属性 overwrittenByGeneration が含まれます。これにより、新しいオブジェクトの世代番号が示されます。

通知形式

Pub/Sub トピックに送信される通知は、次の 2 つの部分で構成されます。

  • 属性: イベントを記述する Key-Value ペアのセット
  • ペイロード: 変更されたオブジェクトのメタデータを含む文字列

属性

属性は、Cloud Storage から Pub/Sub トピックに送信されるすべての通知に含まれる Key-Value ペアです。ペイロードに関係なく、通知には次の Key-Value ペアが含まれます。

属性名 例 説明
notificationConfig projects/_/buckets/foo/notificationConfigs/3 この通知をトリガーする通知設定の識別子。
eventType OBJECT_FINALIZE 発生したイベントの種類。有効な値については、イベントの種類をご覧ください。
payloadFormat JSON_API_V1 オブジェクトのペイロードの形式。有効な値については、ペイロードをご覧ください。
bucketId foo 変更されたオブジェクトを含むバケット名。
objectId bar 変更されたオブジェクトの名前。
objectGeneration 123456 変更されたオブジェクトの世代番号。
eventTime 2021-01-15T01:30:15.01Z イベントが発生した時間。RFC 3339 形式で表します。

ペイロードに関係なく、通知には次のキー / 値ペアのセットが含まれることがあります。

属性名 例 説明
overwrittenByGeneration 107458 この通知が関係するオブジェクトを置換したオブジェクトの世代番号。この属性は、置換の場合にのみ OBJECT_ARCHIVE または OBJECT_DELETE イベントに含まれます。
overwroteGeneration 352947 この通知が関係するオブジェクトによって置換されたオブジェクトの世代番号。この属性は、置換の場合にのみ OBJECT_FINALIZE イベントに含まれます。

上記の属性に加えて、通知構成には最大 10 個のカスタム属性を含めることができます。カスタム属性を定義するには、通知構成を作成するときに gcloud storage コマンドで --custom-attributes を使用するか、POST notificationConfigs JSON リクエストの本文で custom_attributes オブジェクトを使用します。

ペイロード

ペイロードは、変更されたオブジェクトのメタデータを含む文字列です。通知設定を作成するときに、トリガーされた通知に入れるペイロードの種類を指定します。次の種類のペイロードを指定できます。

ペイロードの種類 説明
なし 通知にペイロードを追加しません。
JSON_API_V1 ペイロードは、オブジェクトのメタデータのリソース表現を含む UTF-8 形式の文字列になります。

OBJECT_DELETE 通知の場合、ペイロードに含まれるメタデータは、削除前のオブジェクトのメタデータと timeDeleted プロパティを表します。それ以外の通知では、ペイロードに含まれるメタデータは、変更発生後のオブジェクトのメタデータを表します。

たとえば、OBJECT_METADATA_UPDATE イベントを追跡する通知構成を定義したとします。ユーザーがオブジェクトの contentType プロパティを binary/octet-stream から video/mp4 に変更すると、OBJECT_METADATA_UPDATE 通知が送信され、ペイロードのメタデータには "contentType":"video/mp4" が含まれます。

配信の保証

通知構成を追加してから Cloud Storage が関連する通知を送信するまでに 30 秒ほどかかる場合があります。送信が開始されると、Cloud Storage は Pub/Sub に少なくとも 1 回以上配信を行います。Pub/Sub は、受信者にも 1 回以上の配信を行います。つまり、同じ Cloud Storage イベントを表す異なる ID のメッセージを受信する場合があります。

通知の公開順序は、Pub/Sub で受信する順序と必ずしも一致しません。通知に基づいて Cloud Storage オブジェクトを変更する場合には、オブジェクトの世代番号とメタ世代番号を基準に更新リクエストを行うことをおすすめします。

Pub/Sub トピックに一貫して通知を配信できない場合、Cloud Storage は 7 日後に通知を削除することがあります。Pub/Sub トピックが存在しない場合、Cloud Storage がトピックに公開する権限を持たない場合、またはトピックを所有するプロジェクトが公開割り当てを超えた場合、配信が失敗する可能性があります。

次のステップ