Cloud Storage トリガー

Cloud Functions では、Cloud Storage トリガーによって、Cloud Storage の変更に応じて関数を呼び出すことができます。関数に Cloud Storage トリガーを指定するときに、イベントタイプを選択して Cloud Storage バケットを指定します。この関数は、指定されたバケット内のオブジェクト（ファイル）が変更されるたびに呼び出されます。

次の Cloud Storage イベントタイプがサポートされています。

イベント イベントタイプ 説明
オブジェクトのファイナライズ
  • 第 2 世代: google.cloud.storage.object.v1.finalized（Eventarc 経由）
  • 第 1 世代: google.storage.object.finalize
 新しいオブジェクトが作成されるか、既存のオブジェクトが上書きされ、そのオブジェクトの新しい世代が作成されると送信されます。
オブジェクトの削除
  • 第 2 世代: google.cloud.storage.object.v1.deleted（Eventarc 経由）
  • 第 1 世代: google.storage.object.delete
 オブジェクトが完全に削除された場合に発生します。
オブジェクトのアーカイブ
  • 第 2 世代: google.cloud.storage.object.v1.archived（Eventarc 経由）
  • 第 1 世代: google.storage.object.archive
 オブジェクトのライブ バージョンが非現行バージョンになると送信されます。詳細については、オブジェクトのバージョニングをご覧ください。
オブジェクト メタデータの更新
  • 第 2 世代: google.cloud.storage.object.v1.metadataUpdated（Eventarc 経由）
  • 第 1 世代: google.storage.object.metadataUpdate
 既存オブジェクトのメタデータが変更された場合に送信されます。

Cloud Storage トリガーを使用するには、イベント ドリブン関数として実装する必要がありま

Google イベント リポジトリには、イベントデータを処理するための追加のリソースが含まれています。

権限

Cloud Functions（第 2 世代）で Cloud Storage トリガーを使用するには、プロジェクトで Cloud Storage サービス エージェントに Pub/Sub パブリッシャー（roles/pubsub.publisher）の IAM ロールが必要です。この要件は、Cloud Functions（第 1 世代）には適用されません。

デプロイ

関数のデプロイ時に Cloud Storage トリガーを指定できます。関数をデプロイする一般的な手順については、Cloud Functions のデプロイをご覧ください。デプロイ中に Cloud Storage トリガーを構成するための追加情報については、以下をご覧ください。

gcloud

gcloud CLI を使用してデプロイする場合は、次のフラグを指定して Cloud Storage の「オブジェクトのファイナライズ」イベントタイプを使用します。

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-bucket=YOUR_STORAGE_BUCKET \
[--retry] \
...
  • --trigger-bucket フラグには、トリガーがモニタリングする Cloud Storage バケットを指定します。このバケット内で「オブジェクトのファイナライズ」イベントが発生すると、関数呼び出しがトリガーされます。
  • --retry フラグは、失敗した関数呼び出しを自動的に再試行するかどうかを制御します。詳細については、イベント ドリブン関数の再試行をご覧ください。

「オブジェクトのファイナライズ」以外のイベントタイプを使用するには、次のフラグを使用します。

  • Cloud Functions（第 2 世代）の場合:

    gcloud functions deploy YOUR_FUNCTION_NAME \
--gen2 \
--trigger-event-filters="type=EVENT_TYPE" \
--trigger-event-filters="bucket=YOUR_STORAGE_BUCKET" \
...

    第 2 世代の関数をデプロイする場合は、先頭に gs:// を付けずにバケット名のみを指定します（例: --trigger-event-filters="bucket=my-bucket"）。

  • Cloud Functions（第 1 世代）の場合:

    gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-event=EVENT_TYPE \
--trigger-resource=YOUR_STORAGE_BUCKET \
...

以前の Cloud Storage イベント

Cloud Functions（第 1 世代）のレガシー関数は、Cloud Storage トリガーに以前のオブジェクト変更通知を使用します。

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-event=providers/cloud.storage/eventTypes/object.change \
--trigger-resource=YOUR_STORAGE_BUCKET \
...

このイベントタイプは、これらのイベントをすでに使用している以前の関数でサポートされています。ただし、今後削除される可能性があるため、このイベントタイプの使用はおすすめしません。

コンソール

Google Cloud コンソールを使用してデプロイする場合は、[トリガー] セクションで Cloud Storage トリガーを構成できます。

  • Cloud Functions（第 2 世代）の場合:

    1. [トリガーのタイプ] フィールドで、[Cloud Storage] を選択します。

    2. [イベントタイプ] フィールドで、トリガーとなるイベントを選択します。デフォルトは google.cloud.storage.object.v1.finalized です。

      Cloud Audit Logs を使用する Cloud Storage イベントについては、Eventarc トリガーのトリガー構成手順をご覧ください。

    3. [バケット] フィールドで [参照] をクリックして、トリガーをモニタリングする Cloud Storage バケットを選択します。このバケット内のオブジェクトが変更されると、関数の呼び出しがトリガーされます。

    4. [失敗時に再試行する] チェックボックスをオンまたはオフにして、失敗した関数呼び出しを Cloud Functions が自動的に再試行するかどうかを制御します。詳細については、イベント ドリブン関数の再試行をご覧ください。

    5. [その他のオプション] をクリックして、トリガーで追加の構成を行います。

      • [トリガーのタイプ] フィールドで、[Google ソース]、[カスタム]、[サードパーティ] のいずれかを指定します。

        • [Google ソース] を使用すると、Pub/Sub、Cloud Storage、Firestore、その他の Google イベント プロバイダのトリガーを指定できます。[Eventarc トリガー] ペインで、[イベント プロバイダ] フィールドを使用して、関数をトリガーするイベントのタイプを指定するプロダクトを選択します。次に、[イベント] フィールドで、トリガーとして使用するイベントを選択します。

        • [カスタム] オプションを使用すると、アプリケーション コードからイベントを生成して消費できます。[Eventarc トリガー] ペインのプロンプトに沿ってチャネルを作成します。チャネルは、カスタム イベントをプロデューサーからコンシューマに配信するパイプラインとして使用されるリソースです。カスタム イベントはチャネルに公開され、Eventarc トリガーがこれらのイベントに登録されます。

        • [サードパーティ] オプションを使用すると、Google 以外の Eventarc ソースを提供するプロバイダと統合できます。詳細については、Eventarc のサードパーティ イベントをご覧ください。

      • [イベント] フィールドで、トリガーとなるイベントを選択します。デフォルトは google.cloud.storage.object.v1.finalized です。

      • 必要に応じて、[サービス アカウント] フィールドで、Eventarc トリガーの ID として使用するサービス アカウントを選択します。詳細については、トリガー ID をご覧ください。

    6. [トリガーを保存] をクリックします。

  • Cloud Functions（第 1 世代）の場合:

    1. [トリガーのタイプ] フィールドで、[Cloud Storage] を選択します。
    2. [イベントタイプ] で、イベントタイプを選択します。
    3. [バケット] フィールドで [参照] をクリックして、トリガーをモニタリングする Cloud Storage バケットを選択します。このバケット内のオブジェクトが変更されると、関数の呼び出しがトリガーされます。
    4. [失敗時に再試行する] チェックボックスをオンまたはオフにして、失敗した関数の呼び出しを自動的に再試行するかどうかを制御します。詳細については、イベント ドリブン関数の再試行をご覧ください。

イベント配信

Cloud Storage トリガーは、Cloud Storage の Pub/Sub 通知を使用して実装されます。イベントには Pub/Sub 通知の配信の保証が適用されます。

Cloud Storage バケットには、特定のイベントをトリガーするように設定された通知構成を最大 10 個まで設定できます。バケットの通知の上限を超えると、関数のデプロイが失敗し、次のようなエラーが返されます。

Cloud Storage bucket ...: Pub/Sub notification limit reached

詳細については、Cloud Storage の割り当てと上限をご覧ください。

次のステップ