使用 Eventarc 接收来自 Cloud Storage 的事件


本教程介绍如何使用经过身份验证的 Cloud Run 服务部署容器化应用,该服务通过 Eventarc 接收事件。

通过为 Eventarc 触发器指定过滤条件,您可以配置事件的路由,包括事件来源和事件目标。在此示例中,对 Cloud Storage 存储桶的更新会触发事件,系统会以 HTTP 请求的形式向 Cloud Run 服务发送请求。

目标

在此教程中,您将学习以下操作:

  1. 创建 Cloud Storage 存储桶作为事件来源。

  2. 将事件接收器服务部署到 Cloud Run(需要使用经过身份验证的调用)。

  3. 创建一个将 Cloud Storage 存储桶中的事件路由到 Cloud Run 服务的 Eventarc 触发器。

  4. 通过将文件上传到 Cloud Storage 存储桶来生成事件,并在 Cloud Run 日志中查看该事件。

费用

在本文档中,您将使用 Google Cloud 的以下收费组件:

您可使用价格计算器根据您的预计使用情况来估算费用。 Google Cloud 新用户可能有资格申请免费试用

须知事项

您的组织定义的安全限制条件可能会导致您无法完成以下步骤。如需了解相关问题排查信息,请参阅在受限的 Google Cloud 环境中开发应用

  1. 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手,请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金,用于运行、测试和部署工作负载。
  2. 安装 Google Cloud CLI。
  3. 如需初始化 gcloud CLI,请运行以下命令:

    gcloud init
  4. 创建或选择 Google Cloud 项目

    • 创建 Google Cloud 项目:

      gcloud projects create PROJECT_ID

      PROJECT_ID 替换为您要创建的 Google Cloud 项目的名称。

    • 选择您创建的 Google Cloud 项目:

      gcloud config set project PROJECT_ID

      PROJECT_ID 替换为您的 Google Cloud 项目 名称。

  5. 确保您的 Google Cloud 项目已启用结算功能

  6. 安装 Google Cloud CLI。
  7. 如需初始化 gcloud CLI,请运行以下命令:

    gcloud init
  8. 创建或选择 Google Cloud 项目

    • 创建 Google Cloud 项目:

      gcloud projects create PROJECT_ID

      PROJECT_ID 替换为您要创建的 Google Cloud 项目的名称。

    • 选择您创建的 Google Cloud 项目:

      gcloud config set project PROJECT_ID

      PROJECT_ID 替换为您的 Google Cloud 项目 名称。

  9. 确保您的 Google Cloud 项目已启用结算功能

  10. 如果您没有使用 Cloud Shell,请更新 Google Cloud CLI 组件并使用您的账号登录:
    gcloud components update
    gcloud auth login
  11. 启用 API:
    gcloud services enable artifactregistry.googleapis.com \
        cloudbuild.googleapis.com \
        eventarc.googleapis.com \
        run.googleapis.com \
        storage.googleapis.com
  12. 设置本教程中使用的配置变量:
    export REGION=us-central1
    gcloud config set run/region ${REGION}
    gcloud config set run/platform managed
    gcloud config set eventarc/location ${REGION}
  13. 如果您是项目创建者,则会被授予基本 Owner 角色 (roles/owner)。默认情况下,此 Identity and Access Management (IAM) 角色可提供完全访问大多数 Google Cloud 资源所需的权限,您可以跳过此步骤。

    如果您不是项目创建者,则必须向主账号授予项目的必需权限。例如,主账号可以是 Google 账号(针对最终用户)或服务账号(针对应用和计算工作负载)。如需了解详情,请参阅事件目标位置的角色和权限页面。

    请注意,默认情况下,Cloud Build 权限包含上传和下载 Artifact Registry 工件的权限

    所需权限

    如需获得完成本教程所需的权限,请让您的管理员为您授予项目的以下 IAM 角色:

    如需详细了解如何授予角色,请参阅管理访问权限

    您也可以通过自定义角色或其他预定义角色来获取所需的权限。

  14. 启用或使用包含 Compute Engine 的 Google Cloud 服务后,系统会自动创建 Compute Engine 默认服务账号

    为了进行测试,您可以将此服务账号附加到 Eventarc 触发器以表示该触发器的身份。请记下创建触发器时要使用的电子邮件地址格式:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com
    

    PROJECT_NUMBER 替换为您的 Google Cloud 项目编号。您可以在 Google Cloud 控制台的欢迎页面上或者通过运行以下命令找到项目编号:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    系统会自动向 Compute Engine 服务账号授予项目的基本 Editor 角色 (roles/editor)。但是,如果自动角色授予功能已停用,请参阅适用的角色和权限说明以创建新的服务账号并为其授予所需的角色。

  15. 默认情况下,只有 Project Owner、Project Editor 以及 Cloud Run Admin 和 Invoker 才能调用 Cloud Run 服务。您可以按服务控制访问权限;但是,出于测试目的,请向 Compute Engine 服务账号授予 Google Cloud 项目的 Cloud Run Invoker 角色 (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 Invoker 角色的情况下为经过身份验证的 Cloud Run 服务创建触发器,则触发器会成功创建且处于活动状态。但是,触发器将无法按预期运行,并且日志中会显示类似于以下内容的消息:

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  16. 将项目的 Eventarc Event Receiver 角色 (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
  17. 如果您在 2021 年 4 月 8 日或之前启用了 Cloud Pub/Sub 服务代理,以支持经过身份验证的 Pub/Sub 推送请求,请向 Google 管理的服务账号授予 Service Account Token Creator 角色 (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

创建 Artifact Registry 标准制品库

创建 Artifact Registry 标准制品库以存储您的容器映像:

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

REPOSITORY 替换为制品库的唯一名称。

创建 Cloud Storage 存储桶

创建 Cloud Storage 存储桶以用作事件来源:

gsutil mb -l us-central1 gs://PROJECT_ID-bucket/

创建事件来源后,您可以在 Cloud Run 上部署事件接收器服务。

将事件接收器部署到 Cloud Run

部署接收和记录事件的 Cloud Run 服务。

  1. 克隆 GitHub 代码库:

    Node.js

    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

    或者,您也可以下载该示例的 zip 文件并将其解压缩。

    Python

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

    或者,您也可以下载该示例的 zip 文件并将其解压缩。

    Go

    git clone https://github.com/GoogleCloudPlatform/golang-samples.git

    或者,您也可以下载该示例的 zip 文件并将其解压缩。

    Java

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

    或者,您也可以下载该示例的 zip 文件并将其解压缩。

    C#

    git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git

    或者,您也可以下载该示例的 zip 文件并将其解压缩。

  2. 切换到包含 Cloud Run 示例代码的目录:

    Node.js

    cd nodejs-docs-samples/eventarc/audit-storage/

    Python

    cd python-docs-samples/eventarc/audit-storage/

    Go

    cd golang-samples/eventarc/audit_storage/

    Java

    cd java-docs-samples/eventarc/audit-storage/

    C#

    cd dotnet-docs-samples/eventarc/audit-storage/
  3. 为 Cloud Run 服务构建容器:

    export PROJECT_ID=$(gcloud config get-value project)
    export SERVICE_NAME=helloworld-events
    gcloud builds submit --tag $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1
  4. 将容器映像部署到 Cloud Run:

    gcloud run deploy ${SERVICE_NAME} \
        --image $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1
  5. 在出现“Allow unauthenticated invocations to helloworld-events (y/N)?”(是否允许对 helloworld 事件进行未经身份验证的调用 (y/N)?)提示时,请回复 n(表示“否”)。

当您看到 Cloud Run 服务网址时,表示部署完成。

创建 Eventarc 触发器

Eventarc 触发器会将 Cloud Storage 存储桶中的事件发送到 helloworld-events Cloud Run 服务。 该服务需要进行身份验证,并且事件必须由拥有包含必需 IAM 角色和权限的服务账号的调用方触发,才能使用资源。

  1. 创建一个过滤 Cloud Storage 事件的触发器:

    gcloud eventarc triggers create ${SERVICE_NAME} \
        --destination-run-service=${SERVICE_NAME} \
        --destination-run-region=${REGION} \
        --location=${REGION} \
        --event-filters="type=google.cloud.storage.object.v1.finalized" \
        --event-filters="bucket=PROJECT_ID-bucket" \
        --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    这将创建一个名为 helloworld-events 的触发器。

    请注意,首次在 Google Cloud 项目中创建 Eventarc 触发器时,预配 Eventarc 服务代理可能会有延迟。通常,您可以尝试再次创建触发器,以解决此问题。如需了解详情,请参阅权限遭拒错误

  2. 确认触发器已成功创建。请注意,尽管触发器会立即创建,但它最长可能需要两分钟才能完全正常运行。

    gcloud eventarc triggers list --location=${REGION}

    输出应类似如下所示:

    NAME: helloworld-events
    TYPE: google.cloud.storage.object.v1.finalized
    DESTINATION: Cloud Run service: helloworld-events
    ACTIVE: Yes
    

生成并查看事件

将文本文件上传到 Cloud Storage 存储桶以生成路由到 Cloud Run 服务的事件。Cloud Run 服务会在服务日志中记录事件。

  1. 要生成事件,请执行以下操作:

    将文本文件上传到 Cloud Storage:

     echo "Hello World" > random.txt
     gsutil cp random.txt gs://PROJECT_ID-bucket/random.txt
    

    上传操作会生成事件,而 Cloud Run 服务会记录事件的消息。

  2. 如需查看日志条目,请执行以下操作:

    1. 过滤日志条目并以 JSON 格式返回输出:

      gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json
      
    2. 查找类似如下的日志条目:

      "textPayload": "Detected change in Cloud Storage bucket: objects/random.txt"
      

您可能需要等待一些时间才能看到日志。如果您没有立即看到日志,请稍等片刻,然后再检查一次。

您已成功将事件接收器服务部署到 Cloud Run,创建 Eventarc 触发器,在 Cloud Storage 中生成事件并在 Cloud Run 日志中查看该事件。

清理

如果您为本教程创建了一个新项目,请删除项目。 如果您使用的是现有项目,希望保留此项目且不保留本教程中添加的任何更改,请删除为教程创建的资源

删除项目

为了避免产生费用,最简单的方法是删除您为本教程创建的项目。

要删除项目,请执行以下操作:

  1. 在 Google Cloud 控制台中,进入管理资源页面。

    转到“管理资源”

  2. 在项目列表中,选择要删除的项目,然后点击删除
  3. 在对话框中输入项目 ID,然后点击关闭以删除项目。

删除教程资源

  1. 删除您在本教程中部署的 Cloud Run 服务:

    gcloud run services delete SERVICE_NAME

    其中,SERVICE_NAME 是您选择的服务名称。

    您还可以从 Google Cloud 控制台中删除 Cloud Run 服务。

  2. 移除您在教程设置过程中添加的任何 gcloud CLI 默认配置。

    例如:

    gcloud config unset run/region

    gcloud config unset project

  3. 删除在本教程中创建的其他 Google Cloud 资源:

    • 删除 Eventarc 触发器:
      gcloud eventarc triggers delete TRIGGER_NAME
      
      TRIGGER_NAME 替换为您的触发器的名称。

后续步骤