Cloud Storage のチュートリアル（第 1 世代）

このシンプルなチュートリアルでは、Cloud Storage イベントに応答する Cloud Storage トリガーを使用したイベント ドリブンの Cloud Run functions を作成、デプロイ、トリガーする方法について説明します。

Cloud Storage 自体を使用したコードサンプルについては、Google Cloud のサンプル ブラウザをご覧ください。

目標

• イベント ドリブンの Cloud Run 関数を作成してデプロイする。
• Cloud Storage にファイルをアップロードして関数をトリガーする。

費用

このドキュメントでは、課金対象である次の Google Cloudコンポーネントを使用します。

• Cloud Run functions
• Cloud Storage

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Functions, Cloud Build, Cloud Storage, and Eventarc APIs.

Enable the APIs

Install the Google Cloud CLI.

外部 ID プロバイダ（IdP）を使用している場合は、まずフェデレーション ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Functions, Cloud Build, Cloud Storage, and Eventarc APIs.

Enable the APIs

Install the Google Cloud CLI.

外部 ID プロバイダ（IdP）を使用している場合は、まずフェデレーション ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

gcloud CLI がすでにインストールされている場合は、次のコマンドを実行して更新します。

gcloud components update

1. 開発環境を準備します。

   Node.js

   Node.js 設定ガイドに移動

   Python

   Python 設定ガイドに移動

   Go

   Go 設定ガイドに移動

   Java

   Java 設定ガイドに移動

   Ruby

   Ruby 設定ガイドに移動

アプリケーションの準備

1. Cloud Storage バケットを作成しテストファイルをアップロードします。ここで、YOUR_TRIGGER_BUCKET_NAME はグローバルに固有のバケット名となります。

   gcloud storage buckets create gs://YOUR_TRIGGER_BUCKET_NAME

2. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   または、zip 形式のサンプルをダウンロードしてファイルを抽出してもかまいません。

   Python

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

   または、zip 形式のサンプルをダウンロードしてファイルを抽出してもかまいません。

   Go

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

   または、zip 形式のサンプルをダウンロードしてファイルを抽出してもかまいません。

   Java

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

   または、zip 形式のサンプルをダウンロードし、ファイルを抽出してもかまいません。

   Ruby

   git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git

   または、zip 形式のサンプルをダウンロードしてファイルを抽出してもかまいません。

3. Cloud Run functions のサンプルコードが含まれているディレクトリに移動します。

   Node.js

   cd nodejs-docs-samples/functions/helloworld/

   Python

   cd python-docs-samples/functions/helloworld/

   Go

   cd golang-samples/functions/helloworld/

   Java

   cd java-docs-samples/functions/helloworld/hello-gcs/

   Ruby

   cd ruby-docs-samples/functions/helloworld/storage/

関数のデプロイとトリガー

Cloud Storage の関数は Cloud Storage からの Pub/Sub 通知に基づいており、以下に挙げる類似のイベントタイプに対応しています。

• ファイナライズ

• 削除

• アーカイブ

• メタデータの更新

以降のセクションでは、上記の各イベントタイプについて、関数をデプロイしてトリガーする方法を説明します。

オブジェクトのファイナライズ

オブジェクト ファイナライズ イベントは、Cloud Storage オブジェクトの「書き込み」が正常にファイナライズされた時点でトリガーされます。つまり、新しいオブジェクトの作成または既存のオブジェクトの上書きによって、このイベントがトリガーされます。このトリガーにより、アーカイブとメタデータの更新オペレーションは無視されます。

オブジェクトのファイナライズ: 関数のデプロイ

Cloud Storage イベントを処理するサンプル関数を見てみましょう。

Node.js

/**
 * Generic background Cloud Function to be triggered by Cloud Storage.
 * This sample works for all Cloud Storage CRUD operations.
 *
 * @param {object} file The Cloud Storage file metadata.
 * @param {object} context The event metadata.
 */
exports.helloGCS = (file, context) => {
  console.log(`  Event: ${context.eventId}`);
  console.log(`  Event Type: ${context.eventType}`);
  console.log(`  Bucket: ${file.bucket}`);
  console.log(`  File: ${file.name}`);
  console.log(`  Metageneration: ${file.metageneration}`);
  console.log(`  Created: ${file.timeCreated}`);
  console.log(`  Updated: ${file.updated}`);
};

Python

def hello_gcs(event, context):
    """Background Cloud Function to be triggered by Cloud Storage.
       This generic function logs relevant data when a file is changed,
       and works for all Cloud Storage CRUD operations.
    Args:
        event (dict):  The dictionary with data specific to this type of event.
                       The `data` field contains a description of the event in
                       the Cloud Storage `object` format described here:
                       https://cloud.google.com/storage/docs/json_api/v1/objects#resource
        context (google.cloud.functions.Context): Metadata of triggering event.
    Returns:
        None; the output is written to Cloud Logging
    """

    print(f"Event ID: {context.event_id}")
    print(f"Event type: {context.event_type}")
    print("Bucket: {}".format(event["bucket"]))
    print("File: {}".format(event["name"]))
    print("Metageneration: {}".format(event["metageneration"]))
    print("Created: {}".format(event["timeCreated"]))
    print("Updated: {}".format(event["updated"]))

Go

// Package helloworld provides a set of Cloud Functions samples.
package helloworld

import (
	"context"
	"fmt"
	"log"
	"time"

	"cloud.google.com/go/functions/metadata"
)

// GCSEvent is the payload of a GCS event.
type GCSEvent struct {
	Kind                    string                 `json:"kind"`
	ID                      string                 `json:"id"`
	SelfLink                string                 `json:"selfLink"`
	Name                    string                 `json:"name"`
	Bucket                  string                 `json:"bucket"`
	Generation              string                 `json:"generation"`
	Metageneration          string                 `json:"metageneration"`
	ContentType             string                 `json:"contentType"`
	TimeCreated             time.Time              `json:"timeCreated"`
	Updated                 time.Time              `json:"updated"`
	TemporaryHold           bool                   `json:"temporaryHold"`
	EventBasedHold          bool                   `json:"eventBasedHold"`
	RetentionExpirationTime time.Time              `json:"retentionExpirationTime"`
	StorageClass            string                 `json:"storageClass"`
	TimeStorageClassUpdated time.Time              `json:"timeStorageClassUpdated"`
	Size                    string                 `json:"size"`
	MD5Hash                 string                 `json:"md5Hash"`
	MediaLink               string                 `json:"mediaLink"`
	ContentEncoding         string                 `json:"contentEncoding"`
	ContentDisposition      string                 `json:"contentDisposition"`
	CacheControl            string                 `json:"cacheControl"`
	Metadata                map[string]interface{} `json:"metadata"`
	CRC32C                  string                 `json:"crc32c"`
	ComponentCount          int                    `json:"componentCount"`
	Etag                    string                 `json:"etag"`
	CustomerEncryption      struct {
		EncryptionAlgorithm string `json:"encryptionAlgorithm"`
		KeySha256           string `json:"keySha256"`
	}
	KMSKeyName    string `json:"kmsKeyName"`
	ResourceState string `json:"resourceState"`
}

// HelloGCS consumes a(ny) GCS event.
func HelloGCS(ctx context.Context, e GCSEvent) error {
	meta, err := metadata.FromContext(ctx)
	if err != nil {
		return fmt.Errorf("metadata.FromContext: %w", err)
	}
	log.Printf("Event ID: %v\n", meta.EventID)
	log.Printf("Event type: %v\n", meta.EventType)
	log.Printf("Bucket: %v\n", e.Bucket)
	log.Printf("File: %v\n", e.Name)
	log.Printf("Metageneration: %v\n", e.Metageneration)
	log.Printf("Created: %v\n", e.TimeCreated)
	log.Printf("Updated: %v\n", e.Updated)
	return nil
}

Java

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;
import functions.eventpojos.GcsEvent;
import java.util.logging.Logger;

/**
 * Example Cloud Storage-triggered function.
 * This function can process any event from Cloud Storage.
 */
public class HelloGcs implements BackgroundFunction<GcsEvent> {
  private static final Logger logger = Logger.getLogger(HelloGcs.class.getName());

  @Override
  public void accept(GcsEvent event, Context context) {
    logger.info("Event: " + context.eventId());
    logger.info("Event Type: " + context.eventType());
    logger.info("Bucket: " + event.getBucket());
    logger.info("File: " + event.getName());
    logger.info("Metageneration: " + event.getMetageneration());
    logger.info("Created: " + event.getTimeCreated());
    logger.info("Updated: " + event.getUpdated());
  }
}

Ruby

require "functions_framework"

FunctionsFramework.cloud_event "hello_gcs" do |event|
  # This function supports all Cloud Storage events.
  # The `event` parameter is a CloudEvents::Event::V1 object.
  # See https://cloudevents.github.io/sdk-ruby/latest/CloudEvents/Event/V1.html
  payload = event.data

  logger.info "Event: #{event.id}"
  logger.info "Event Type: #{event.type}"
  logger.info "Bucket: #{payload['bucket']}"
  logger.info "File: #{payload['name']}"
  logger.info "Metageneration: #{payload['metageneration']}"
  logger.info "Created: #{payload['timeCreated']}"
  logger.info "Updated: #{payload['updated']}"
end

関数をデプロイするには、サンプルコードがあるディレクトリで次のコマンドを実行します。

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs20 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

サポートされている Node.js バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Python

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

サポートされている Python バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Go

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

サポートされている Go バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Java

gcloud functions deploy java-gcs-function \
--entry-point functions.HelloGcs \
--runtime java17 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

サポートされている Java バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Ruby

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

サポートされている Ruby バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

YOUR_TRIGGER_BUCKET_NAME は、関数をトリガーする Cloud Storage バケットの名前です。

オブジェクトのファイナライズ: 関数のトリガー

関数をトリガーするには、以下の手順に従います。

1. サンプルコードがあるディレクトリに空の gcf-test.txt ファイルを作成します。

2. 関数をトリガーするために、Cloud Storage にファイルをアップロードします。

   gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME

   YOUR_TRIGGER_BUCKET_NAME は、テストファイルをアップロードする Cloud Storage バケットの名前です。

3. 実行が完了したことをログで確認します。

   gcloud functions logs read --limit 50
   

オブジェクトの削除

オブジェクト削除イベントは、オブジェクトが削除（復元可能）になったときにトリガーされます。これは、オブジェクトのバージョニングが有効になっていないバケットでオブジェクトが上書きまたは削除された場合に発生します。世代番号を指定してオブジェクトを削除した場合も、オブジェクトは削除済み（復元可能）になります。

オブジェクトの削除: 関数のデプロイ

ファイナライズの例と同じサンプルコードを使用して、トリガー イベントとしてオブジェクトの削除を行う関数をデプロイします。サンプルコードがあるディレクトリで次のコマンドを実行します。

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs20 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

サポートされている Node.js バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Python

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

サポートされている Python バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Go

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

サポートされている Go バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Java

gcloud functions deploy java-gcs-function \
--entry-point functions.HelloGcs \
--runtime java17 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

サポートされている Java バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Ruby

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

サポートされている Ruby バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

YOUR_TRIGGER_BUCKET_NAME は、関数をトリガーする Cloud Storage バケットの名前です。

オブジェクトの削除: 関数のトリガー

関数をトリガーするには、以下の手順に従います。

1. サンプルコードがあるディレクトリに空の gcf-test.txt ファイルを作成します。

2. バケットがバージョニング対応でないことを確認します。

   gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --no-versioning

3. Cloud Storage にファイルをアップロードします。

   gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME

   YOUR_TRIGGER_BUCKET_NAME は、テストファイルをアップロードする Cloud Storage バケットの名前です。この時点ではまだ関数は実行されません。

4. ファイルを削除して関数をトリガーします。

   gcloud storage rm gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt

5. 実行が完了したことをログで確認します。

   gcloud functions logs read --limit 50
   

関数の実行が完了するまでに時間がかかる場合があることに注意してください。

オブジェクトのアーカイブ

オブジェクト アーカイブ イベントは、オブジェクトのライブ バージョンが非現行バージョンになったときにトリガーされます。これは、オブジェクトのバージョニングが有効になっているバケットでオブジェクトが上書きまたは削除された場合に発生します。

オブジェクトのアーカイブ: 関数のデプロイ

ファイナライズの例と同じサンプルコードを使用して、トリガー イベントとしてオブジェクトのアーカイブを行う関数をデプロイします。サンプルコードがあるディレクトリで次のコマンドを実行します。

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs20 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

サポートされている Node.js バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Python

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

サポートされている Python バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Go

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

サポートされている Go バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Java

gcloud functions deploy java-gcs-function \
--entry-point functions.HelloGcs \
--runtime java17 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

サポートされている Java バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Ruby

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

サポートされている Ruby バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

YOUR_TRIGGER_BUCKET_NAME は、関数をトリガーする Cloud Storage バケットの名前です。

オブジェクトのアーカイブ: 関数のトリガー

関数をトリガーするには、以下の手順に従います。

1. サンプルコードがあるディレクトリに空の gcf-test.txt ファイルを作成します。

2. バケットのバージョニングが有効になっていることを確認します。

   gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --versioning

3. Cloud Storage にファイルをアップロードします。

   gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME

   YOUR_TRIGGER_BUCKET_NAME は、テストファイルをアップロードする Cloud Storage バケットの名前です。この時点ではまだ関数は実行されません。

4. ファイルをアーカイブして関数をトリガーします。

   gcloud storage rm gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt

5. 実行が完了したことをログで確認します。

   gcloud functions logs read --limit 50
   

オブジェクト メタデータの更新

メタデータ更新イベントは、既存のオブジェクトのメタデータが更新された時点でトリガーされます。

オブジェクト メタデータの更新: 関数のデプロイ

ファイナライズの例と同じサンプルコードを使用して、トリガー イベントとしてメタデータの更新を行う関数をデプロイします。サンプルコードがあるディレクトリで次のコマンドを実行します。

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs20 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

サポートされている Node.js バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Python

gcloud functions deploy hello_gcs \
--runtime python312 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

サポートされている Python バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Go

gcloud functions deploy HelloGCS \
--runtime go121 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

サポートされている Go バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Java

gcloud functions deploy java-gcs-function \
--entry-point functions.HelloGcs \
--runtime java17 \
--memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

サポートされている Java バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

Ruby

gcloud functions deploy hello_gcs --runtime ruby33 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

サポートされている Ruby バージョンのランタイム ID を指定して関数を実行するには、--runtime フラグを使用します。

YOUR_TRIGGER_BUCKET_NAME は、関数をトリガーする Cloud Storage バケットの名前です。

オブジェクト メタデータの更新: 関数のトリガー

関数をトリガーするには、以下の手順に従います。

1. サンプルコードがあるディレクトリに空の gcf-test.txt ファイルを作成します。

2. バケットがバージョニング対応でないことを確認します。

   gcloud storage buckets update gs://YOUR_TRIGGER_BUCKET_NAME --no-versioning

3. Cloud Storage にファイルをアップロードします。

   gcloud storage cp gcf-test.txt gs://YOUR_TRIGGER_BUCKET_NAME

   YOUR_TRIGGER_BUCKET_NAME は、テストファイルをアップロードする Cloud Storage バケットの名前です。この時点ではまだ関数は実行されません。

4. ファイルのメタデータを更新します。

   gcloud storage objects update gs://YOUR_TRIGGER_BUCKET_NAME/gcf-test.txt --content-type=text/plain

5. 実行が完了したことをログで確認します。

   gcloud functions logs read --limit 50
   

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

プロジェクトの削除

課金されないようにする最も簡単な方法は、チュートリアル用に作成したプロジェクトを削除することです。

プロジェクトを削除するには:

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

関数の削除

Cloud Run functions を削除しても、Cloud Storage に保存されたリソースは削除されません。

このチュートリアルで作成した関数を削除するには、次のコマンドを実行します。

Node.js

gcloud functions delete helloGCS 

Python

gcloud functions delete hello_gcs 

Go

gcloud functions delete HelloGCS 

Java

gcloud functions delete java-gcs-function 

Ruby

gcloud functions delete hello_gcs 

Cloud Run functions の関数は Google Cloud コンソールで削除することもできます。

次のステップ

• バケットにアップロードされた画像で OCR を実行する方法を学ぶ。
• Cloud Run 関数を使用してテキスト ファイルを翻訳する方法を学ぶ。