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" \
...

  • 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 \
...

이 이벤트 유형은 이미 이러한 이벤트를 사용 중인 기존 함수에 대해 지원됩니다. 하지만 이후에 삭제될 수 있으므로 이 이벤트 유형을 사용하지 않는 것이 좋습니다.

Console

Google Cloud Console을 사용하여 배포하는 경우 트리거 섹션에서 Cloud Storage 트리거를 구성할 수 있습니다.

  • Cloud Functions(2세대):

    1. 이벤트 트리거를 추가하려면 트리거 추가를 클릭합니다.

    2. Cloud Storage 트리거를 선택합니다.

      Eventarc 트리거 창이 열립니다. 이 창에는 Cloud Storage가 이벤트 제공업체로, google.cloud.storage.object.v1.finalized가 트리거 이벤트로 미리 채워집니다.

      이벤트 필드를 사용하여 다른 이벤트를 선택할 수 있습니다. Cloud 감사 로그를 사용하는 Cloud Storage 이벤트의 경우 Eventarc 트리거의 트리거 구성 안내를 참조하세요.

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

    4. 선택적으로 서비스 계정 필드에서 Eventarc 트리거의 ID로 사용할 서비스 계정을 선택합니다. 자세한 내용은 트리거 ID를 참조하세요.

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

    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 할당량 및 한도를 참조하세요.

다음 단계