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 함수 배포를 참조하고 배포 중 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 Console을 사용하여 배포하는 경우 트리거 섹션에서 Cloud Storage 트리거를 구성할 수 있습니다.

  • Cloud Functions(2세대):

    1. 트리거 유형 필드에서 Cloud Storage를 선택합니다.

    2. 이벤트 유형 필드에서 트리거 이벤트를 선택합니다. 기본값은 google.cloud.storage.object.v1.finalized입니다.

      Cloud 감사 로그를 사용하는 Cloud Storage 이벤트의 경우 Eventarc 트리거의 트리거 구성 안내를 참조하세요.

    3. 버킷 필드에서 찾아보기를 클릭하여 트리거로 모니터링할 Cloud Storage 버킷을 선택합니다. 이 버킷 내에서 객체가 변경되면 함수 호출이 트리거됩니다.

    4. 실패 시 재시도 체크박스를 선택하거나 선택 해제하여 Cloud Functions가 실패한 함수 호출을 자동으로 재시도할지 여부를 제어합니다. 자세한 내용은 이벤트 기반 함수 재시도를 참조하세요.

    5. 옵션 더보기를 클릭하여 트리거에서 추가 구성을 수행합니다.

      • 트리거 유형 필드에서 Google 소스, 커스텀 또는 타사 중 하나를 지정합니다.

        • Google 소스를 사용하면 Pub/Sub, Cloud Storage, Firestore, 기타 Google 이벤트 제공업체의 트리거를 지정할 수 있습니다. Eventarc 트리거 창에서 이벤트 제공자 필드를 사용하여 함수를 트리거할 이벤트 유형을 제공하는 제품을 선택하세요. 그런 다음 이벤트 필드에서 트리거로 사용할 이벤트를 선택합니다.

        • 커스텀 옵션을 사용하면 애플리케이션 코드에서 이벤트를 생성하고 사용할 수 있습니다. Eventarc 트리거 창의 안내를 따라 채널을 만듭니다. 채널은 제작자로부터 소비자에게 맞춤 이벤트를 전달하기 위해 파이프라인으로 사용되는 리소스입니다. 맞춤 이벤트가 채널에 게시되고 Eventarc 트리거가 이러한 이벤트를 구독합니다.

        • 서드 파티 옵션을 사용하면 Eventarc 소스를 제공하는 Google 이외의 제공업체와 통합할 수 있습니다. 자세한 내용은 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 할당량 및 한도를 참조하세요.

다음 단계