이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Cloud Storage로 트리거 만들기

Cloud Run에서는 Eventarc를 사용하여 Cloud Storage의 변경사항에 대한 응답으로 Cloud Storage에서 서비스를 트리거할 수 있습니다.

서비스에 Cloud Storage 트리거를 지정하면 이벤트 유형을 선택하고 Cloud Storage 버킷을 지정합니다. 이 트리거의 결과로 지정된 버킷 내의 객체 (파일)에 변경사항이 발생할 때마다 서비스가 호출됩니다.

Cloud Storage 버킷의 이벤트에 의해 서비스가 트리거되려면 서비스와 버킷이 동일한 Google Cloud 프로젝트에 있어야 합니다.

Cloud Run은 다음과 같은 Cloud Storage 이벤트 유형을 지원합니다.

이벤트	이벤트 유형	설명
객체 완료됨	`google.cloud.storage.object.v1.finalized` (Eventarc를 통해)	새 객체를 만들거나 기존 객체를 덮어쓰고 Cloud Storage에서 이 객체의 새 세대를 만들 때 발생합니다.
객체 삭제됨	`google.cloud.storage.object.v1.deleted` (Eventarc를 통해)	객체를 영구적으로 삭제할 때 발생합니다.
객체 보관처리됨	`google.cloud.storage.object.v1.archived` (Eventarc를 통해)	서비스 중인 객체 버전이 이전 버전이 될 때 발생합니다. 자세한 내용은 객체 버전 관리를 참조하세요.
객체 메타데이터가 업데이트됨	`google.cloud.storage.object.v1.metadataUpdated` (Eventarc를 통해)	기존 객체의 메타데이터를 변경할 때 발생합니다.

Google 이벤트 저장소에는 이벤트 데이터 작업을 위한 추가 리소스가 포함되어 있습니다.

시작하기 전에

설정 페이지에 설명된 대로 Cloud Run용 새 프로젝트를 설정했는지 확인합니다.
Artifact Registry, Cloud Build, Cloud Run Admin API, Eventarc, Cloud Logging, Pub/Sub, Cloud Storage API를 사용 설정합니다.

API 사용 설정

필요한 역할 설정

프로젝트 생성자에게는 기본 소유자 역할(roles/owner)이 부여됩니다. 기본적으로 Identity and Access Management(IAM) 역할에는 대부분의 Google Cloud 리소스에 대한 전체 액세스에 필요한 권한이 포함되며, 이 단계를 건너뛸 수 있습니다.

프로젝트 생성자가 아니면 프로젝트에서 적합한 주 구성원에 대해 필수 권한을 부여해야 합니다. 예를 들어 주 구성원은 Google 계정(최종 사용자)이거나 서비스 계정(애플리케이션 및 컴퓨팅 워크로드)일 수 있습니다. 자세한 내용은 이벤트 대상의 역할 및 권한 페이지를 참조하세요.

기본적으로 Cloud Build 권한에는 Artifact Registry 아티팩트를 업로드 및 다운로드할 수 있는 권한이 포함됩니다.
필수 권한

Cloud Storage 트리거를 구성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
- Cloud Build 편집자(roles/cloudbuild.builds.editor)
- Cloud Run 관리자(roles/run.admin)
- Eventarc 관리자(roles/eventarc.admin)
- 로그 뷰 접근자 (roles/logging.viewAccessor)
- 프로젝트 IAM 관리자(roles/resourcemanager.projectIamAdmin)
- 서비스 계정 관리자(roles/iam.serviceAccountAdmin)
- 서비스 계정 사용자(roles/iam.serviceAccountUser)
- 서비스 사용량 관리자(roles/serviceusage.serviceUsageAdmin)
- 스토리지 관리자(roles/storage.admin)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
테스트 목적으로 Eventarc 트리거에 연결할 때 트리거의 ID를 나타내기 위해 Compute Engine 기본 서비스 계정을 기록해 둡니다. 이 서비스 계정은 Compute Engine을 사용하는 Google Cloud 서비스를 사용 설정하거나 사용한 후에 다음 이메일 형식으로 자동 생성됩니다.
```
PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
PROJECT_NUMBER를 Google Cloud 프로젝트 번호로 바꿉니다. Google Cloud 콘솔의 시작 페이지에서 또는 다음 명령어를 실행하여 프로젝트 번호를 찾을 수 있습니다.
```
gcloud projects describe PROJECT_ID --format='value(projectNumber)'
```
프로덕션 환경의 경우 새 서비스 계정을 만들고 필요한 최소한의 권한을 포함하고 최소 권한 원칙을 따르는 하나 이상의 IAM 역할을 부여하는 것이 좋습니다.

참고:
iam.automaticIamGrantsForDefaultServiceAccounts 조직 정책 제약조건은 편집자 역할이 기본 서비스 계정에 자동으로 부여되지 않도록 합니다. 2024년 5월 3일 이후에 조직을 만든 경우 기본적으로 이 제약조건이 적용됩니다.

이 제약조건을 적용하여 자동 역할 부여를 사용 중지하는 것이 좋습니다. 자동 역할 부여를 중지한 경우 기본 서비스 계정에 부여할 역할을 결정한 후 직접 이러한 역할을 부여해야 합니다.

기본 서비스 계정에 이미 편집자 역할이 있으면 편집자 역할을 권한이 더 낮은 역할로 바꾸는 것이 좋습니다. 서비스 계정 역할을 안전하게 수정하려면 정책 시뮬레이터를 사용하여 변경사항의 영향을 확인한 후 적절한 역할을 부여하고 취소합니다.
기본적으로 Cloud Run 서비스는 프로젝트 소유자, 프로젝트 편집자, Cloud Run 관리자 및 호출자만 호출할 수 있습니다. 개발자는 서비스별로 액세스를 제어할 수 있지만, 테스트 목적으로 Compute Engine 서비스 계정에 Google Cloud 프로젝트에서 Cloud Run 호출자 역할(run.invoker)을 부여하세요. 이렇게 하면 프로젝트의 모든 Cloud Run 서비스 및 작업에 대한 역할을 부여하게 됩니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker
```
Cloud Run 호출자 역할을 부여하지 않고 인증된 Cloud Run 서비스에 대한 트리거를 만들어도 트리거가 성공적으로 생성되며 활성화됩니다. 하지만 트리거가 예상한 대로 작동하지 않고 다음과 비슷한 메시지가 로그에 표시됩니다.
The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
프로젝트의 Eventarc 이벤트 수신자 역할(roles/eventarc.eventReceiver)을 Compute Engine 기본 서비스 계정에 부여하세요. 그려면 Eventarc 트리거가 이벤트 제공자로부터 이벤트를 수신할 수 있습니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver
```
2021년 4월 8일 이전에 Cloud Pub/Sub 서비스 에이전트를 사용 설정하여 인증된 Pub/Sub 푸시 요청을 지원한 경우 서비스 계정 토큰 생성자 역할(roles/iam.serviceAccountTokenCreator)을 서비스 에이전트에 부여합니다. 그렇지 않으면 기본적으로 이 역할이 부여됩니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator
```

서비스의 트리거 만들기

서비스를 배포한 후 트리거를 지정할 수 있습니다.

선택한 도구 사용에 관한 안내를 보려면 해당 탭을 클릭하세요.

콘솔

컨테이너를 사용하거나 소스에서 Cloud Run 서비스를 배포합니다.
Google Cloud 콘솔에서 Cloud Run으로 이동합니다.

Cloud Run으로 이동
서비스 목록에서 기존 서비스를 클릭합니다.
서비스 세부정보 페이지에서 트리거 탭으로 이동합니다.
트리거 추가를 클릭하고 Cloud Storage 트리거를 선택합니다.
Eventarc 트리거 창에서 다음과 같이 트리거 세부정보를 수정합니다.
1. 트리거 이름 필드에 트리거의 이름을 입력하거나 기본 이름을 사용합니다.
2. 목록에서 트리거 유형을 선택하고 다음 트리거 유형 중 하나를 지정합니다.
  - Google 소스를 선택하면 Pub/Sub, Cloud Storage, Firestore, 기타 Google 이벤트 제공자의 트리거를 지정할 수 있습니다.
  - 서드 파티를 선택하면 Eventarc 소스를 제공하는 Google 이외의 제공자와 통합할 수 있습니다. 자세한 내용은 Eventarc의 서드 파티 이벤트를 참조하세요.
3. 이벤트 제공자 목록에서 Cloud Storage를 선택하여 서비스를 트리거하기 위한 이벤트 유형을 제공하는 제품을 선택합니다. 이벤트 제공자 목록은 이벤트 제공자 및 대상을 참고하세요.
4. 이벤트 유형 목록에서 google.cloud.storage.object.v1.finalized를 선택합니다. 트리거 구성은 지원되는 이벤트 유형에 따라 다릅니다. 자세한 내용은 이벤트 유형을 참고하세요.
5. 버킷 필드에서 찾아보기를 클릭하여 트리거로 모니터링할 Cloud Storage 버킷을 선택합니다. 이 버킷 내에서 객체가 변경되면 함수 호출이 트리거됩니다.
6. 리전 필드가 사용 설정된 경우 Eventarc 트리거의 위치를 선택합니다. 일반적으로 Eventarc 트리거의 위치는 이벤트에 대해 모니터링하려는 Google Cloud 리소스 위치와 일치해야 합니다. 대부분의 시나리오에서는 서비스도 동일한 리전에 배포해야 합니다. Eventarc 트리거 위치에 대한 자세한 내용은 Eventarc 위치 이해를 참조하세요.
7. 서비스 계정 필드에서 서비스 계정을 선택합니다. Eventarc 트리거는 서비스를 호출할 때 ID로 사용할 서비스 계정에 연결됩니다. Eventarc 트리거의 서비스 계정은 서비스 호출 권한이 있어야 합니다. 기본적으로 Cloud Run은 Compute Engine 기본 서비스 계정을 사용합니다.
8. 선택적으로 수신 요청을 전송할 서비스 URL 경로를 지정합니다. 이는 트리거의 이벤트가 전송되어야 하는 대상 서비스의 상대 경로입니다. 예를 들면 /, /route, route, route/subroute입니다.
9. 필수 필드를 작성했으면 트리거 저장을 클릭합니다.
트리거를 만든 후에는 트리거 탭에 체크 표시 이 있는지 확인하면 상태를 확인할 수 있습니다.

참고: 트리거는 즉시 생성되지만 트리거에서 이벤트를 전파하고 필터링하는 데 최대 2분이 걸릴 수 있습니다.

gcloud

컨테이너를 사용하거나 소스에서 Cloud Run 서비스를 배포합니다.
다음 명령어를 실행하여 이벤트를 필터링하는 트리거를 만듭니다.
```
gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=PROJECT_ID-bucket" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
다음과 같이 바꿉니다.
- TRIGGER_NAME을 트리거의 이름으로 바꿉니다.
- EVENTARC_TRIGGER_LOCATION을 Eventarc 트리거 위치로 바꿉니다. 일반적으로 Eventarc 트리거의 위치는 이벤트에 대해 모니터링하려는 Google Cloud 리소스 위치와 일치해야 합니다. 대부분의 시나리오에서는 서비스도 동일한 리전에 배포해야 합니다. 자세한 내용은 Eventarc 위치를 참고하세요.
- SERVICE를 배포하려는 서비스의 이름으로 바꿉니다.
- REGION을 서비스의 Cloud Run 리전으로 바꿉니다.
- PROJECT_NUMBER를 Google Cloud 프로젝트 번호로 바꿉니다. Eventarc 트리거는 서비스를 호출할 때 ID로 사용할 서비스 계정에 연결됩니다. Eventarc 트리거의 서비스 계정은 서비스 호출 권한이 있어야 합니다. 기본적으로 Cloud Run은 기본 컴퓨팅 서비스 계정을 사용합니다.
- event-filters 플래그는 트리거가 모니터링하는 이벤트 필터를 지정합니다. 모든 event-filters 필터와 일치하는 이벤트가 서비스 호출을 트리거합니다. 각 트리거는 지원되는 이벤트 유형이어야 합니다. 생성 후에는 이벤트 필터 유형을 변경할 수 없습니다. 이벤트 필터 유형을 변경하려면 새 트리거를 만들고 이전 트리거를 삭제해야 합니다. 원하는 경우 ATTRIBUTE=VALUE 형식으로 지원되는 필터를 사용해서 --event-filters 플래그를 반복하여 더 많은 필터를 추가할 수 있습니다.

함수의 트리거 만들기

선택한 도구 사용에 관한 안내를 보려면 해당 탭을 클릭하세요.

콘솔

Google Cloud 콘솔을 사용하여 함수를 만들 때 함수에 트리거를 추가할 수도 있습니다. 함수의 트리거를 만들려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Cloud Run으로 이동합니다.

Cloud Run으로 이동
함수 작성을 클릭하고 함수 세부정보를 입력합니다. 배포 중에 함수를 구성하는 방법에 관한 자세한 내용은 함수 배포를 참고하세요.
트리거 섹션에서 트리거 추가를 클릭합니다.
Cloud Storage 트리거를 선택합니다.
Eventarc 트리거 창에서 다음과 같이 트리거 세부정보를 수정합니다.
1. 트리거 이름 필드에 트리거의 이름을 입력하거나 기본 이름을 사용합니다.
2. 목록에서 트리거 유형을 선택하고 다음 트리거 유형 중 하나를 지정합니다.
  - Google 소스를 선택하면 Pub/Sub, Cloud Storage, Firestore, 기타 Google 이벤트 제공자의 트리거를 지정할 수 있습니다.
  - 서드 파티를 선택하면 Eventarc 소스를 제공하는 Google 이외의 제공자와 통합할 수 있습니다. 자세한 내용은 Eventarc의 서드 파티 이벤트를 참조하세요.
3. 이벤트 제공자 목록에서 Cloud Storage를 선택하여 함수 트리거를 위한 이벤트 유형을 제공하는 제품을 선택합니다. 이벤트 제공자 목록은 이벤트 제공자 및 대상을 참고하세요.
4. 이벤트 유형 목록에서 google.cloud.storage.object.v1.finalized를 선택합니다. 트리거 구성은 지원되는 이벤트 유형에 따라 다릅니다. 자세한 내용은 이벤트 유형을 참고하세요.
5. 버킷 필드에서 찾아보기를 클릭하여 트리거로 모니터링할 Cloud Storage 버킷을 선택합니다. 이 버킷 내에서 객체가 변경되면 함수 호출이 트리거됩니다.
6. 리전 필드가 사용 설정된 경우 Eventarc 트리거의 위치를 선택합니다. 일반적으로 Eventarc 트리거의 위치는 이벤트에 대해 모니터링하려는 Google Cloud 리소스 위치와 일치해야 합니다. 대부분의 시나리오에서는 함수도 동일한 리전에 배포해야 합니다. Eventarc 트리거 위치에 대한 자세한 내용은 Eventarc 위치 이해를 참조하세요.
7. 서비스 계정 필드에서 서비스 계정을 선택합니다. Eventarc 트리거는 함수를 호출할 때 ID로 사용할 서비스 계정에 연결됩니다. Eventarc 트리거의 서비스 계정은 함수 호출 권한이 있어야 합니다. 기본적으로 Cloud Run은 Compute Engine 기본 서비스 계정을 사용합니다.
8. 선택적으로 수신 요청을 전송할 서비스 URL 경로를 지정합니다. 이는 트리거의 이벤트가 전송되어야 하는 대상 서비스의 상대 경로입니다. 예를 들면 /, /route, route, route/subroute입니다.
필수 필드를 작성했으면 트리거 저장을 클릭합니다.

gcloud

gcloud CLI를 사용하여 함수를 만들 때는 먼저 함수를 deploy한 다음 트리거를 만들어야 합니다. 함수의 트리거를 만들려면 다음 단계를 따르세요.

샘플 코드가 포함된 디렉터리에서 다음 명령어를 실행하여 함수를 배포합니다.
```
gcloud beta run deploy FUNCTION \
        --source . \
        --function FUNCTION_ENTRYPOINT \
        --base-image BASE_IMAGE_ID \
        --region REGION
```
다음과 같이 바꿉니다.
- FUNCTION을 배포하려는 함수의 이름으로 바꿉니다. 이 매개변수를 완전히 생략할 수 있지만 생략하면 이름을 입력하라는 메시지가 표시됩니다.
- FUNCTION_ENTRYPOINT를 소스 코드에 있는 함수의 진입점으로 바꿉니다. 이는 함수가 실행될 때 Cloud Run이 실행하는 코드입니다. 이 플래그의 값은 소스 코드에 있는 함수 이름 또는 정규화된 클래스 이름이어야 합니다.
- BASE_IMAGE_ID를 함수의 기본 이미지 환경으로 바꿉니다. 기본 이미지 및 각 이미지에 포함된 패키지에 대한 자세한 내용은 런타임 기본 이미지를 참조하세요.
- REGION을 함수를 배포하려는 Google Cloud 리전으로 바꿉니다. 예를 들면 us-central1입니다.
다음 명령어를 실행하여 이벤트를 필터링하는 트리거를 만듭니다.
```
gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=PROJECT_ID-bucket" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
다음과 같이 바꿉니다.
- TRIGGER_NAME을 트리거의 이름으로 바꿉니다.
- EVENTARC_TRIGGER_LOCATION을 Eventarc 트리거 위치로 바꿉니다. 일반적으로 Eventarc 트리거의 위치는 이벤트에 대해 모니터링하려는 Google Cloud 리소스 위치와 일치해야 합니다. 대부분의 시나리오에서는 함수도 동일한 리전에 배포해야 합니다. 자세한 내용은 Eventarc 위치를 참고하세요.
- FUNCTION을 배포하려는 함수의 이름으로 바꿉니다.
- REGION을 함수의 Cloud Run 리전으로 바꿉니다.
- PROJECT_NUMBER를 Google Cloud 프로젝트 번호로 바꿉니다. Eventarc 트리거는 함수를 호출할 때 ID로 사용할 서비스 계정에 연결됩니다. Eventarc 트리거의 서비스 계정은 함수를 호출할 권한이 있어야 합니다. 기본적으로 Cloud Run은 기본 컴퓨팅 서비스 계정을 사용합니다.
- event-filters 플래그는 트리거가 모니터링하는 이벤트 필터를 지정합니다. 모든 event-filters 필터와 일치하는 이벤트가 함수 호출을 트리거합니다. 각 트리거는 지원되는 이벤트 유형이어야 합니다. 생성 후에는 이벤트 필터 유형을 변경할 수 없습니다. 이벤트 필터 유형을 변경하려면 새 트리거를 만들고 이전 트리거를 삭제해야 합니다. 원하는 경우 ATTRIBUTE=VALUE 형식으로 지원되는 필터를 사용해서 --event-filters 플래그를 반복하여 더 많은 필터를 추가할 수 있습니다.

이벤트 전송

Cloud Storage 트리거는 Cloud Storage용 Pub/Sub 알림으로 구현됩니다. 이벤트에는 Pub/Sub 알림 전송 보증이 적용됩니다.

Cloud Storage 버킷에는 특정 이벤트에 트리거되는 알림 구성이 10개까지 포함될 수 있습니다. 버킷 알림 제한을 초과하면 다음과 같은 오류와 함께 추가 함수 배포가 실패합니다.

Cloud Storage bucket ...: Pub/Sub notification limit reached

자세한 내용은 Cloud Storage 할당량 및 한도를 참조하세요.

다음 단계

이벤트로 트리거하는 방법을 알아보세요.
Eventarc를 사용하여 Cloud Storage에서 서비스를 트리거하는 방법을 알아보세요.
Eventarc를 사용하여 Cloud Storage에서 함수를 트리거하는 방법을 알아봅니다.

Cloud Storage로 트리거 만들기

시작하기 전에

필요한 역할 설정

필수 권한

서비스의 트리거 만들기

콘솔

gcloud

함수의 트리거 만들기

콘솔

gcloud

이벤트 전송

다음 단계