Google Cloud Storage 트리거

Cloud Functions는 Google Cloud Storage에서 보내는 변경 알림에 응답할 수 있습니다. 객체 생성, 삭제, 보관, 메타데이터 업데이트와 같이 버킷 내의 다양한 이벤트에 대한 응답으로 트리거되도록 해당 알림을 구성할 수 있습니다.

이벤트 유형

Cloud Functions에서 사용되는 Cloud Storage 이벤트는 Google Cloud Storage용 Cloud Pub/Sub 알림을 기반으로 하며 유사한 방법으로 구성될 수 있습니다.

지원되는 트리거 유형 값은 다음과 같습니다.

  • google.storage.object.finalize

  • google.storage.object.delete

  • google.storage.object.archive

  • google.storage.object.metadataUpdate

객체 완료

트리거 유형 값: google.storage.object.finalize

이 이벤트는 버킷에서 새로운 객체를 만들거나 기존 객체를 덮어쓰고 해당 객체의 새로운 세대를 만들면 전송됩니다.

예를 들어 다음 함수는 이벤트가 발생하면 관련 데이터를 로깅합니다.

Node.js

/**
 * Generic background Cloud Function to be triggered by Cloud Storage.
 *
 * @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.

    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 Stackdriver Logging
    """

    print('Event ID: {}'.format(context.event_id))
    print('Event type: {}'.format(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 GCS event.
func HelloGCS(ctx context.Context, e GCSEvent) error {
	meta, err := metadata.FromContext(ctx)
	if err != nil {
		return fmt.Errorf("metadata.FromContext: %v", 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;

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());
  }
}

객체 완료 트리거를 사용하여 함수를 배포하려면 함수 코드가 있는 디렉터리에서 다음 명령어를 실행합니다.

Node.js

gcloud functions deploy helloGCS \
--runtime nodejs10 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime 플래그에 다음 값을 사용하여 원하는 Node.js 버전을 지정할 수 있습니다.
  • nodejs10
  • nodejs12

Python

gcloud functions deploy hello_gcs \
--runtime python37 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime 플래그에 다음 값을 사용하여 선호하는 Python 버전을 지정할 수 있습니다.
  • python37
  • python38

Go

gcloud functions deploy HelloGCS \
--runtime go111 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime 플래그에 다음 값을 사용하여 선호하는 Go 버전을 지정할 수 있습니다.
  • go111
  • go113

자바

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

여기서 YOUR_TRIGGER_BUCKET_NAME은 함수가 모니터링할 Cloud Storage 버킷 이름입니다.

객체 삭제

트리거 유형 값: google.storage.object.delete

이 이벤트는 객체가 영구적으로 삭제될 때 전송됩니다. 버킷의 객체 버전 관리 설정에 따라 다음과 같은 결과가 발생합니다.

  • 버전 관리 버킷의 경우 버전이 영구적으로 삭제될 때에만 전송됩니다(객체를 보관처리할 때는 전송되지 않음).

  • 버전 관리 버킷이 아닌 경우 객체가 삭제되거나 덮어쓰여질 때 전송됩니다.

객체 보관처리

트리거 유형 값: google.storage.object.archive

이 이벤트는 객체의 라이브 버전이 보관처리되거나 삭제될 때 전송됩니다.

이 이벤트는 버전 관리 버킷인 경우에만 전송됩니다.

객체 메타데이터 업데이트

트리거 유형 값: google.storage.object.metadataUpdate

이 이벤트는 기존 객체의 메타데이터가 변경될 때 전송됩니다.

이벤트 구조

스토리지 이벤트 데이터는 Cloud Storageobject 형식으로 제공됩니다.

이벤트 전송 메커니즘

이벤트는 Cloud Storage의 Pub/Sub 알림과 함께 전송됩니다. 동일 버킷에 대해 너무 많은 함수를 설정하면 버킷의 알림 한도가 소진되어 Cloud Storage bucket ...: Pub/Sub notification limit reached 오류가 표시되므로 함수를 만들 수 없게 됩니다. 알림 한도에 대한 자세한 내용은 Google Cloud Storage Cloud Pub/Sub 알림 문서를 참조하세요.

기존 Cloud Storage 트리거

아래의 gcloud 명령어는 특정 버킷의 기존 객체 변경 알림에 의해 트리거되는 함수를 배포합니다. 일반적으로 Cloud Pub/Sub 알림은 객체 변경 알림보다 사용이 더욱 쉽고 유연하며 강력합니다. 그러나 이러한 기존 알림은 이미 해당 이벤트를 사용하는 기존 함수에서 사용할 수 있습니다.

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event providers/cloud.storage/eventTypes/object.change \
FLAGS...
인수 설명
--trigger-resource NAME 함수가 변경 여부를 감시하는 Cloud Storage 버킷의 이름입니다.
--trigger-event NAME 함수가 수신할 이벤트 유형 이름입니다. 이 경우에는 기존 object.change 이벤트입니다.
FLAGS... 배포 시 --runtime과 같이 추가 플래그를 지정해야 합니다. 전체 참조를 보려면 gcloud functions deploy 문서를 참조하세요.

다음 단계

Cloud Storage에 의해 트리거되는 백그라운드 함수를 구현하는 방법에 대한 예시는 Cloud Storage 가이드를 참조하세요.