Cloud Firestore 이벤트를 Workflows로 라우팅

Eventarc 트리거는 특정 이벤트 또는 이벤트 집합에 관심이 있음을 선언합니다. 이벤트 소스나 대상 서비스 등의 트리거 필터를 지정하여 이벤트 라우팅을 구성할 수 있습니다.

이벤트는 HTTP 요청을 통해 CloudEvents 형식으로 전달됩니다. Workflows 서비스는 이벤트를 JSON 객체(CloudEvents 사양에 따름)로 변환하고 이벤트를 워크플로 실행에 워크플로 런타임 인수로 전달합니다. 이벤트 크기가 512KB를 초과하지 않도록 유의하세요. 이벤트가 최대 Workflows 인수 크기보다 큰 경우 워크플로 실행이 트리거되지 않습니다.

Cloud Firestore는 CloudEvents 형식에 대한 확장 프로그램 속성으로 인증 컨텍스트를 지원합니다. 트리거를 만들 때 인증 정보로 이벤트를 필터링하도록 이 이벤트 유형 속성을 적용할 수 있습니다.

이 안내에서는 직접Cloud Firestore 이벤트에 대한 응답으로 워크플로 실행이 트리거되도록 이벤트 라우팅을 구성하는 방법을 보여줍니다. 자세한 내용은 지원되는 직접 이벤트 목록을 참조하세요.

참고: Google 제공자에 직접 및 감사 로그 이벤트가 모두 지원되는 경우 직접 이벤트를 필터링하는 트리거를 만드는 것이 좋습니다. 직접 이벤트는 감사 로그 이벤트에 비해 여러 가지 이점을 제공합니다. 자세한 내용은 이벤트 경로를 참조하세요.

트리거 만들기 준비

대상 워크플로에 대한 Eventarc 트리거를 만들기 전에 다음 작업을 완료해야 합니다.

콘솔

1. Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 만들거나 선택합니다.

   참고: 이 절차에서 생성한 리소스를 유지하지 않으려면 기존 프로젝트를 선택하지 말고 프로젝트를 새로 만드세요. 작업이 끝나면 프로젝트를 삭제하여 프로젝트와 관련된 모든 리소스를 삭제할 수 있습니다.

   프로젝트 선택기로 이동

2. Eventarc, Eventarc Publishing, Workflows, Workflow Executions API를 사용 설정합니다.

   API 사용 설정

3. 해당하는 경우 직접 이벤트와 관련된 API를 사용 설정합니다. 예를 들어 Cloud Firestore 이벤트의 경우Cloud Firestore API를 사용 설정합니다.

4. 아직 계정이 없는 경우 사용자 관리형 서비스 계정을 만들고 Eventarc가 대상 워크플로의 이벤트를 관리할 수 있도록 필요한 역할과 권한을 계정에 부여합니다.

   1. Google Cloud 콘솔에서 서비스 계정 페이지로 이동합니다.

      서비스 계정으로 이동

   2. 프로젝트를 선택합니다.

   3. 서비스 계정 이름 필드에 이름을 입력합니다. Google Cloud 콘솔은 이 이름을 기반으로 서비스 계정 ID 필드를 채웁니다.

      서비스 계정 설명 필드에 설명을 입력합니다. 예를 들면 Service account for event trigger입니다.

   4. 만들고 계속하기를 클릭합니다.

   5. 적절한 액세스 권한을 제공하기 위해 역할 선택 목록에서 서비스 계정에 부여할 필요한 Identity and Access Management(IAM) 역할을 선택합니다. 자세한 내용은 Workflows 대상의 역할 및 권한을 참조하세요.

      역할을 추가하려면 다른 역할 추가를 클릭하고 각 역할을 추가합니다.

   6. 계속을 클릭합니다.

   7. 계정 만들기를 마치려면 완료를 클릭합니다.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Eventarc, Eventarc Publishing, Workflows, Workflow Executions API를 사용 설정합니다.

   gcloud services enable eventarc.googleapis.com \
       eventarcpublishing.googleapis.com \
       workflows.googleapis.com \
       workflowexecutions.googleapis.com

3. 해당하는 경우 직접 이벤트와 관련된 API를 사용 설정합니다. 예를 들어 Cloud Firestore 이벤트의 경우 firestore.googleapis.com를 사용 설정합니다.

4. 아직 계정이 없는 경우 사용자 관리형 서비스 계정을 만들고 Eventarc가 대상 워크플로의 이벤트를 관리할 수 있도록 필요한 역할과 권한을 계정에 부여합니다.

   1. 서비스 계정을 만듭니다.

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      SERVICE_ACCOUNT_NAME을 서비스 계정의 이름으로 바꿉니다. 6~30자(영문 기준) 사이여야 하며 소문자 영숫자 문자와 대시를 포함할 수 있습니다. 서비스 계정을 만든 후에는 이름을 변경할 수 없습니다.

   2. 필요한 Identity and Access Management(IAM) 역할 또는 권한을 부여합니다. 자세한 내용은 Workflows 대상의 역할 및 권한을 참조하세요.

트리거 만들기

Google Cloud CLI(gcloud 또는 Terraform)를 사용하거나 Google Cloud 콘솔을 통해 배포된 워크플로를 이벤트 수신자로 사용하여 Eventarc 트리거를 만들 수 있습니다.

참고: 정확히 일치해야 필터링이 수행되며 필터링에서 와일드 카드나 정규 표현식은 지원되지 않습니다. 그러나 다음 gcloud CLI 명령어에서 --event-filters-path-pattern 플래그를 사용하거나 콘솔을 통해 경로 패턴을 정의할 수 있습니다. 자세한 내용은 경로 패턴 이해를 참조하세요.

콘솔

1. Google Cloud 콘솔에서 Eventarc 트리거 페이지로 이동합니다.

   트리거로 이동

2. 트리거 만들기를 클릭합니다.
3. 트리거 이름을 입력합니다.

   트리거의 ID이며 문자로 시작해야 합니다. 최대 63자(영문 기준)의 소문자, 숫자, 하이픈을 포함할 수 있습니다.

4. 트리거 유형으로 Google 소스를 선택합니다.
5. 이벤트 제공자 목록에서 Cloud Firestore를 선택합니다.

   연결된 Google Cloud 문서에 사용된 이벤트 제공자 이름에 Cloud 또는 Google Cloud 프리픽스가 없을 수 있습니다. 예를 들어 콘솔에서는 Redis용 Memorystore를 Redis용 Google Cloud Memorystore라고 합니다.

6. 이벤트 유형 목록의 직접 이벤트에서 이벤트 유형을 선택합니다.
7. 이벤트 데이터 콘텐츠 유형 목록에서 이벤트 페이로드의 인코딩을 선택합니다.

   Cloud Firestore의 직접 이벤트에서는 application/protobuf여야 하고 이벤트 데이터는 바이트 배열입니다. Cloud Firestore 이벤트의 protobuf 메시지에 대한 자세한 내용은 일반적인 이벤트를 참조하세요. Workflows 표준 라이브러리 함수를 사용하여 바이트를 Base64 텍스트로 인코딩할 수 있습니다. 자세한 내용은 바이트 반환을 참조하세요.

8. 리전 목록에서 이벤트를 생성하는 Google Cloud 서비스와 동일한 리전을 선택합니다.

   자세한 내용은 Eventarc 위치를 참조하세요.

9. 이벤트 제공자에 해당하는 경우 필터 추가를 클릭하고 다음을 지정합니다.
   1. 속성 1 필드에서 선택한 직접 이벤트에 따라 이벤트 필터 역할을 할 수 있는 리소스 ID를 선택합니다.
   2. 연산자를 선택합니다.
      • Equal
      • 경로 패턴: document(네이티브 모드) 및 entity(Datastore 모드) 리소스에 적용할 수 있습니다. 와일드 카드를 사용하여 패턴과 일치하는 변경사항에 응답합니다. 와일드 카드 *는 단일 세그먼트와 일치하고, 다중 세그먼트 와일드 카드 **는 패턴의 0개 이상의 세그먼트와 일치합니다. 예를 들면 다음과 같습니다.

        /users/* 또는 /users/{userId}	/users 컬렉션의 모든 문서와 일치합니다. /users/marie/messages/33e2IxYBD9enzS50SJ68과 같은 하위 컬렉션의 문서와 일치하지 않습니다.
        /users/**	/users 컬렉션의 모든 문서 및 /users/marie/messages/33e2IxYBD9enzS50SJ68과 같은 하위 컬렉션의 문서와 일치합니다.

        자세한 내용은 경로 패턴 이해를 참조하세요.

   3. 속성 값 1 필드에서 선택한 연산자에 따라 정확한 값을 입력하거나 경로 패턴을 적용합니다.
   4. 더 많은 속성 필터를 적용할 수 있으면 필터 추가를 클릭하고 적합한 값을 지정합니다.
10. 서비스 또는 워크플로를 호출할 서비스 계정을 선택합니다.

    또는 새 서비스 계정을 만들 수 있습니다.

    이는 트리거와 연결되어 있고 이전에 Eventarc에 필요한 특정 역할을 부여한 Identity and Access Management(IAM) 서비스 계정 이메일을 지정합니다.

11. 이벤트 대상 목록에서 Workflows을 선택합니다.
12. 워크플로를 선택합니다.
    

    이벤트를 전달할 워크플로의 이름입니다. 워크플로 실행 이벤트가 변환되어 런타임 인수로 워크플로에 전달됩니다.

    자세한 내용은 Workflows의 트리거 만들기를 참조하세요.

13. 만들기를 클릭합니다.

트리거가 생성된 후에는 이벤트 소스 필터를 수정할 수 없습니다. 대신 새 트리거를 만들고 이전 트리거를 삭제합니다. 자세한 내용은 트리거 관리를 참조하세요.

gcloud

필수 및 선택적 플래그와 함께 gcloud eventarc triggers create 명령어를 실행하여 트리거를 만들 수 있습니다.

플래그는 Firestore를 기본 모드에서 또는 Datastore 모드에서 실행하는지에 따라 달라집니다. 자세한 내용은 기본 모드와 Datastore 모드 중 선택을 참조하세요.

기본 모드

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-workflow=DESTINATION_WORKFLOW  \
    --destination-workflow-location=DESTINATION_WORKFLOW_LOCATION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="document=DOCUMENT" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account="MY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"

데이터 저장소 모드

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-workflow=DESTINATION_WORKFLOW  \
    --destination-workflow-location=DESTINATION_WORKFLOW_LOCATION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="entity=ENTITY" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account="MY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"

다음을 바꿉니다.

• TRIGGER: 트리거의 ID 또는 정규화된 식별자입니다.

• LOCATION: Eventarc 트리거 위치입니다. 또는 eventarc/location 속성을 설정할 수 있습니다(예: gcloud config set eventarc/location us-central1).

  Eventarc용 Cloud Firestore 트리거는 특정 위치에서만 사용 가능하며 트리거는 Cloud Firestore 데이터베이스와 동일한 위치에 있어야 합니다. 자세한 내용은 Eventarc 위치 및 Cloud Firestore 위치를 참조하세요.

• DESTINATION_WORKFLOW: 트리거에서 이벤트를 수신하는 배포된 워크플로의 ID입니다. 워크플로는 Workflows 지원 위치 중 하나에 있을 수 있으며 트리거와 동일한 위치에 있을 필요는 없습니다. 하지만 워크플로는 트리거와 동일한 프로젝트에 있어야 합니다.
• DESTINATION_WORKFLOW_LOCATION(선택사항): 대상 워크플로가 배포되는 위치입니다. 지정하지 않으면 워크플로가 트리거와 동일한 위치에 있다고 가정합니다.
• EVENT_FILTER_TYPE: 이벤트 식별자입니다. 메서드의 API 호출이 성공하면 이벤트가 생성됩니다. 장기 실행 작업의 경우 작업이 끝날 때와 작업이 성공적으로 완료된 경우에만 이벤트가 생성됩니다. 지원되는 이벤트 유형 목록은 Eventarc에서 지원되는 이벤트 유형을 참조하세요.

Cloud Firestore는 기본 모드에서만 다음 이벤트 유형을 지원합니다.

• google.cloud.firestore.document.v1.created: 문서를 처음으로 작성하면 이벤트가 전송됩니다.
• google.cloud.firestore.document.v1.created.withAuthContext: 문서를 처음으로 작성하면 이벤트가 인증 정보 속성과 함께 전송됩니다.
• google.cloud.firestore.document.v1.updated: 문서가 이미 존재하고 값이 변경되면 이벤트가 전송됩니다.
• google.cloud.firestore.document.v1.updated.withAuthContext: 문서가 이미 존재하고 값이 변경되면 이벤트가 인증 정보 속성과 함께 전송됩니다.
• google.cloud.firestore.document.v1.deleted: 문서가 삭제되면 이벤트가 전송됩니다.
• google.cloud.firestore.document.v1.deleted.withAuthContext: 문서가 삭제되면 이벤트가 인증 정보 속성과 함께 전송됩니다.
• google.cloud.firestore.document.v1.written: 문서가 생성, 업데이트 또는 삭제되면 이벤트가 전송됩니다.
• google.cloud.firestore.document.v1.written.withAuthContext: 문서가 생성, 업데이트 또는 삭제되면 이벤트가 인증 정보 속성과 함께 전송됩니다.

Cloud Firestore는 Datastore 모드에서만 다음 이벤트 유형을 지원합니다. Datastore 모드의 Firestore에서는 데이터 객체를 항목이라고 합니다.

• google.cloud.datastore.entity.v1.created: 항목이 처음 작성되면 이벤트가 전송됩니다.
• google.cloud.datastore.entity.v1.created.withAuthContext: 항목을 처음으로 작성하면 이벤트가 인증 정보 속성과 함께 전송됩니다.
• google.cloud.datastore.entity.v1.updated: 항목이 이미 존재하고 값이 변경되면 이벤트가 전송됩니다.
• google.cloud.datastore.entity.v1.updated.withAuthContext: 항목이 이미 존재하고 값이 변경되면 이벤트가 인증 정보 속성과 함께 전송됩니다.
• google.cloud.datastore.entity.v1.deleted: 항목이 삭제되면 이벤트가 전송됩니다.
• google.cloud.datastore.entity.v1.deleted.withAuthContext: 항목이 삭제되면 이벤트가 인증 정보 속성과 함께 전송됩니다.
• google.cloud.datastore.entity.v1.written: 항목이 생성, 업데이트 또는 삭제되면 이벤트가 전송됩니다.
• google.cloud.datastore.entity.v1.written.withAuthContext: 항목이 생성, 업데이트 또는 삭제되면 이벤트가 인증 정보 속성과 함께 전송됩니다.

• DATABASE: Firestore 데이터베이스입니다. 기본 데이터베이스 이름에는 (default)를 사용합니다.
• NAMESPACE(선택사항): Firestore 데이터베이스 네임스페이스입니다. Datastore 모드의 기본 네임스페이스에는 (default)를 사용합니다. 지정하지 않으면 어커런스에 와일드 카드 일치(*)가 수행됩니다.
• DOCUMENT(선택사항): 기본 모드에서만 실행되는 데이터베이스 인스턴스에 적용됩니다. 데이터가 해당 경로에서 생성, 업데이트 또는 삭제될 때 이벤트를 수신할 데이터베이스 경로입니다. 연산자는 다음 중 하나일 수 있습니다
  • Equal, 예: --event-filters="document=DOCUMENT"
  • 경로 패턴, 예: --event-filters-path-pattern="document=DOCUMENT".

    와일드 카드를 사용하여 패턴과 일치하는 문서의 변경사항에 응답합니다. 와일드 카드 *는 단일 세그먼트와 일치하고, 다중 세그먼트 와일드 카드 **는 패턴의 0개 이상의 세그먼트와 일치합니다. 예를 들면 다음과 같습니다.

    /users/* 또는 /users/{userId}	/users 컬렉션의 모든 문서와 일치합니다. /users/marie/messages/33e2IxYBD9enzS50SJ68과 같은 하위 컬렉션의 문서와 일치하지 않습니다.
    /users/**	/users 컬렉션의 모든 문서 및 /users/marie/messages/33e2IxYBD9enzS50SJ68과 같은 하위 컬렉션의 문서와 일치합니다.

    자세한 내용은 경로 패턴 이해를 참조하세요.
• ENTITY(선택사항): Datastore 모드에서만 실행되는 데이터베이스 인스턴스에 적용됩니다. 데이터가 해당 경로에서 생성, 업데이트 또는 삭제될 때 이벤트를 수신할 데이터베이스 경로입니다. 연산자는 다음 중 하나일 수 있습니다
  • Equal, 예: --event-filters="document=ENTITY"
  • 경로 패턴, 예: --event-filters-path-pattern="ENTITY=ENTITY"

    자세한 내용은 경로 패턴 이해를 참조하세요.

    종류 ID와 항목 ID의 문자를 이스케이프 처리해야 할 수도 있습니다. 문자를 이스케이프 처리하면 이벤트 필터가 ID를 올바르게 해석할 수 있습니다. 자세한 내용은 문자 이스케이프 처리를 참조하세요.

• EVENT_DATA_CONTENT_TYPE: 이벤트 페이로드 인코딩입니다. Firestore를 통한 직접 이벤트의 경우 application/protobuf여야 하고 이벤트 데이터는 바이트 배열입니다. Cloud Firestore 이벤트의 protobuf 메시지에 대한 자세한 내용은 일반적인 이벤트를 참조하세요. Workflows 표준 라이브러리 함수를 사용하여 바이트를 Base64 텍스트로 인코딩할 수 있습니다. 자세한 내용은 바이트 반환을 참조하세요.
• SERVICE_ACCOUNT_NAME: Workflows에 필요한 특정 역할을 부여하여 만든 IAM 서비스 계정의 이름입니다.
• PROJECT_ID: Google Cloud 프로젝트 ID입니다.

참고:

• Cloud Firestore의 직접 이벤트에서는 이벤트 페이로드 인코딩이 application/protobuf입니다.
• --event-filters="type=EVENT_FILTER_TYPE" 플래그는 필수 항목입니다. 다른 이벤트 필터가 설정되지 않으면 모든 리소스의 이벤트가 일치합니다.
• 생성 후에는 EVENT_FILTER_TYPE을 변경할 수 없습니다. EVENT_FILTER_TYPE을 변경하려면 새 트리거를 만들고 이전 트리거를 삭제합니다.
• 각 트리거에 여러 이벤트 필터를 넣거나(--event-filters=[ATTRIBUTE=VALUE,...] 플래그 하나에 쉼표로 구분하여 입력) 플래그를 반복하여 필터를 추가할 수 있습니다. 모든 필터와 일치하는 이벤트만 대상으로 전송됩니다. 와일드 카드와 정규 표현식은 지원되지 않습니다. 그러나 --event-filters-path-pattern 플래그를 사용하면 리소스 경로 패턴을 정의할 수 있습니다.
• --service-account 플래그는 트리거와 연결된 Identity and Access Management(IAM) 서비스 계정 이메일을 지정하는 데 사용됩니다.

예:

gcloud eventarc triggers create helloworld-trigger \
    --location=us-east1 \
    --destination-workflow=my-workflow \
    --destination-workflow-location=us-east1 \
    --event-filters="type=google.cloud.firestore.document.v1.updated" \
    --event-filters="database=my-database" \
    --event-filters-path-pattern="document=users/my-document-*" \
    --event-data-content-type="application/protobuf" \
    --service-account="${TRIGGER_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

이 명령어는 기본 모드에서 실행되는 my-database 데이터베이스 인스턴스에서 google.cloud.firestore.document.v1.updated로 식별된 이벤트의 helloworld-trigger 트리거를 만들고 users/my-document-와 일치하는 document 경로의 이벤트를 필터링합니다.

Terraform

Terraform을 사용하여 워크플로에 대한 트리거를 만들 수 있습니다. 자세한 내용은 Eventarc 및 Terraform을 사용하여 워크플로 트리거를 참조하세요.

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

트리거 나열

Google Cloud CLI를 사용하거나 Google Cloud 콘솔을 통해 Eventarc 트리거를 나열하여 트리거 생성을 확인할 수 있습니다.

콘솔

1. Google Cloud 콘솔에서 Eventarc 트리거 페이지로 이동합니다.

   트리거로 이동

   이 페이지에서는 모든 위치의 트리거를 나열하고 이름, 리전, 이벤트 제공자, 대상 등과 같은 세부정보를 포함합니다.

2. 트리거를 필터링하려면 다음 안내를 따르세요.

   1. 필터 또는 트리거 필터링 필드를 클릭합니다.
   2. 속성 목록에서 트리거를 필터링하는 옵션을 선택합니다.

   단일 속성을 선택하거나 OR 논리 연산자를 사용하여 속성을 추가할 수 있습니다.

3. 트리거를 정렬하려면 지원되는 열 제목 옆에 있는 정렬을 클릭합니다.

gcloud

다음 명령어를 실행하여 트리거를 나열합니다.

gcloud eventarc triggers list --location=-

이 명령어는 모든 위치의 트리거를 나열하고 이름, 유형, 대상, 상태와 같은 세부정보를 포함합니다.

다음 단계

• Eventarc 및 Cloud Firestore 사용 자세히 알아보기
• Eventarc 및 Terraform을 사용하여 워크플로 트리거
• Eventarc 자세히 알아보기
• 트리거 관리 방법 알아보기