Cloud Pub/Sub Notifications for Cloud Storage

このページでは、Cloud Pub/Sub Notifications for Cloud Storage の概要を説明します。Cloud Pub/Sub Notifications の設定と使用方法については、オブジェクト変更の登録をご覧ください。

概要

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

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

他の通知オプション

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

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

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

通知設定

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

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

1 つのバケットに複数の通知構成を適用できます。各イベントに最大 10 個の通知を構成できます。

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

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

  • 通知設定を作成したとき
  • バケットの通知構成のリストを作成したとき
  • 通知構成でトリガーされた通知の notificationConfig 属性

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

イベントの種類

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

イベントの種類 説明
OBJECT_FINALIZE バケットで新しいオブジェクト(または既存オブジェクトの新しい世代)が正常に作成された場合に送信されます。既存のオブジェクトをコピーまたは再作成した場合にも送信されます。アップロードが失敗した場合、このイベントはトリガーされません。
OBJECT_METADATA_UPDATE 既存オブジェクトのメタデータが変更された場合に送信されます。
OBJECT_DELETE オブジェクトが完全に削除された場合に送信されます。バケットのライフサイクル構成で上書きまたは削除されたオブジェクトも対象になります。オブジェクトのバージョニングが有効になっているバケットについては、オブジェクトがアーカイブされたときに、このイベントは送信されません(OBJECT_ARCHIVE をご覧ください)。storage.objects.delete メソッドによりアーカイブが行われた場合も同様です。
OBJECT_ARCHIVE バケットでオブジェクトのバージョニングが有効になっている場合にのみ送信されます。このイベントは、アーカイブまたは同じ名前のオブジェクトのアップロードにより、オブジェクトのライブ バージョンがアーカイブ バージョンになったことを表します。

オブジェクトの上書き

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

通知形式

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

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

属性

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

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

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

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

次のキー / 値のペアはサポートを終了しています。新しいサブスクリプションには表示されません。また、2018 年 6 月 1 日以降はいずれのサブスクリプションにも表示されません。

属性名 説明
resource projects/_/buckets/foo/objects/bar#123456 変更された Cloud Storage オブジェクトのパス。

上記の属性以外に、通知にカスタム属性を入れることもできます。こうした属性を定義するには、通知構成を作成するときに gsutil notification コマンド-m フラグを使用するか、POST notificationConfigs JSON リクエストの本文で custom_attributes オブジェクトを使用します。

ペイロード

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

ペイロードの種類 説明
NONE 通知にペイロードを追加しません。
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 は Cloud Pub/Sub に少なくとも 1 回以上配信を行います。Cloud Pub/Sub は、受信者にも 1 回以上の配信を行います。つまり、同じ Cloud Storage イベントを表す異なる ID のメッセージを受信する場合があります。現在のところ配信時間についての SLA はありませんが、通知は一般に数秒以内に配信されます。非常にまれですが、通知が長時間遅れることもあります。

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

Cloud Pub/Sub トピックに通知を配信できない状態が一貫して続いた場合、Cloud Storage は 7 日後に通知を削除することがあります。Cloud Pub/Sub トピックが存在しなくなったとき、Cloud Storage がそのトピックに公開する権限をもう持っていないとき、またはトピックを所有するプロジェクトが公開容量を超過したときに配信エラーが発生する可能性があります。

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。