Cloud Storage 튜토리얼(1세대)

이 튜토리얼에서는 Cloud Storage 트리거를 사용하여 이벤트 기반 Cloud Run 함수를 작성, 배포, 트리거하여 Cloud Storage 이벤트에 응답하는 방법을 간략하게 설명합니다.

참고: 이벤트는 Cloud Storage의 Pub/Sub 알림을 사용하여 전송됩니다. 특정 이벤트에 트리거되는 알림 구성은 10개까지 사용할 수 있습니다. 동일한 버킷에 알림을 너무 많이 설정하면 버킷의 알림 한도가 초과되어 Cloud Storage bucket ...: Pub/Sub notification limit reached 오류가 표시되면서 함수를 만들 수 없게 됩니다. 한도에 도달하면 알림 삭제와 같은 구제 조치를 취할 때까지 함수를 만들 수 없습니다.

Cloud Storage 자체를 사용하기 위한 코드 샘플을 찾고 있다면 Google Cloud 샘플 브라우저를 방문하세요.

애플리케이션 준비

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 파일로 샘플을 다운로드하고 압축을 풀 수 있습니다.

   자바

   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 알림을 기반으로 하며 다음과 같은 유사한 이벤트 유형을 지원합니다.

• finalize

• 삭제

• archive

• 메타데이터 업데이트

다음 섹션에서는 이러한 각 이벤트 유형에 대해 함수를 배포하고 트리거하는 방법을 설명합니다.

객체 완료

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
}

자바

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 nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Node.js 버전의 런타임 ID를 지정합니다.

Python

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Python 버전의 런타임 ID를 지정합니다.

Go

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Go 버전의 런타임 ID를 지정합니다.

자바

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Java 버전의 런타임 ID를 지정합니다.

Ruby

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Ruby 버전의 런타임 ID를 지정합니다.

여기서 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 nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.delete

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Node.js 버전의 런타임 ID를 지정합니다.

Python

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Python 버전의 런타임 ID를 지정합니다.

Go

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Go 버전의 런타임 ID를 지정합니다.

자바

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Java 버전의 런타임 ID를 지정합니다.

Ruby

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Ruby 버전의 런타임 ID를 지정합니다.

여기서 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 nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.archive

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Node.js 버전의 런타임 ID를 지정합니다.

Python

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Python 버전의 런타임 ID를 지정합니다.

Go

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Go 버전의 런타임 ID를 지정합니다.

자바

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Java 버전의 런타임 ID를 지정합니다.

Ruby

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Ruby 버전의 런타임 ID를 지정합니다.

여기서 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 nodejs22 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.metadataUpdate

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Node.js 버전의 런타임 ID를 지정합니다.

Python

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Python 버전의 런타임 ID를 지정합니다.

Go

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Go 버전의 런타임 ID를 지정합니다.

자바

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Java 버전의 런타임 ID를 지정합니다.

Ruby

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

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Ruby 버전의 런타임 ID를 지정합니다.

여기서 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