使用 Eventarc 触发 Cloud Storage 中的函数

本教程介绍如何在 Cloud Run 中部署事件驱动函数，并使用 Eventarc 通过 Google Cloud CLI 触发该函数以响应 Cloud Storage 事件。

通过为 Eventarc 触发器指定过滤条件，您可以配置事件的路由，包括事件来源和事件目标。对于本教程中的示例，对 Cloud Storage 存储桶的更新会触发事件，系统会以 HTTP 请求的形式向函数发送请求。

目标

在此教程中，您将学习以下操作：

创建 Cloud Storage 存储桶作为事件来源。
部署事件驱动的函数。
创建 Eventarc 触发器。
通过将文件上传到 Cloud Storage 来触发函数。

费用

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

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

准备工作

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

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

To initialize the gcloud CLI, run the following command:

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Make sure that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

To initialize the gcloud CLI, run the following command:

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Make sure that billing is enabled for your Google Cloud project.

如果您没有使用 Cloud Shell，请更新 Google Cloud CLI 组件并使用您的账号登录：
```
gcloud components update
gcloud auth login
```

启用 API：

gcloud services enable artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    eventarc.googleapis.com \
    run.googleapis.com \
    storage.googleapis.com

设置本教程中要使用的配置变量：

export REGION=us-central1
gcloud config set run/region ${REGION}
gcloud config set run/platform managed
gcloud config set eventarc/location ${REGION}

如果您通过网域限制组织政策来限制项目的未经身份验证的调用，则您需要按照测试专用服务中的说明访问已部署的服务。

设置所需角色

如果您是项目创建者，则会被授予基本 Owner 角色 (roles/owner)。默认情况下，此 Identity and Access Management (IAM) 角色可提供完全访问大多数 Google Cloud 资源所需的权限，您可以跳过此步骤。

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

如需获得完成本教程所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：
- Cloud Build Editor (roles/cloudbuild.builds.editor)
- Cloud Run Admin (roles/run.admin)
- Cloud Run Source Developer (roles/run.sourceDeveloper)
- Eventarc Admin (roles/eventarc.admin)
- Logs View Accessor (roles/logging.viewAccessor)
- Project IAM Admin (roles/resourcemanager.projectIamAdmin)
- Service Account Admin (roles/iam.serviceAccountAdmin)
- Service Account User (roles/iam.serviceAccountUser)
- Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
- Storage Admin (roles/storage.admin)
如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。
记下 Compute Engine 默认服务账号，因为您将把它附加到 Eventarc 触发器以代表触发器的身份信息进行测试。启用或使用包含 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 组织政策限制条件可以防止将 Editor 角色自动授予默认服务账号。如果您的组织是在 2024 年 5 月 3 日之后创建的，则默认情况下会强制执行此限制条件。

我们强烈建议您实施此限制条件，以停用自动角色授予功能。如果您停用自动角色授予功能，则必须决定向默认服务账号授予哪些角色，然后自行授予这些角色。

如果默认服务账号已具有 Editor 角色，我们建议您将 Editor 角色替换为权限较少的角色。如需安全地修改服务账号的角色，请使用 Policy Simulator 查看更改的影响，然后授予和撤消相应的角色。
默认情况下，只有 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.

将项目的 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

在为来自 Cloud Storage 的直接事件创建触发器之前，请向 Cloud Storage 服务代理授予 Pub/Sub Publisher 角色 (roles/pubsub.publisher)：

SERVICE_ACCOUNT="$(gcloud storage service-agent --project=PROJECT_ID)"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:${SERVICE_ACCOUNT}" \
    --role='roles/pubsub.publisher'

如果您在 2021 年 4 月 8 日或之前启用了 Cloud Pub/Sub 服务代理，以支持经过身份验证的 Pub/Sub 推送请求，请向该服务代理授予 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
```

创建 Cloud Storage 存储桶

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

gcloud storage buckets create -l us-central1 gs://PROJECT_ID-bucket/

编写事件驱动型函数

如需编写事件驱动型函数，请按照以下步骤操作：

Node.js

创建名为 helloGCS 的新目录，并转到此目录中：
```
   mkdir helloGCS
   cd helloGCS
```

在 helloGCS 目录中创建一个 package.json 文件以指定 Node.js 依赖项：

{
  "name": "nodejs-docs-samples-functions-v2-storage",
  "version": "0.0.1",
  "private": true,
  "license": "Apache-2.0",
  "author": "Google LLC",
  "repository": {
    "type": "git",
    "url": "https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"
  },
  "engines": {
    "node": ">=16.0.0"
  },
  "scripts": {
    "test": "c8 mocha -p -j 2 test/*.test.js --timeout=60000"
  },
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  },
  "devDependencies": {
    "c8": "^10.0.0",
    "mocha": "^10.0.0",
    "sinon": "^18.0.0",
    "supertest": "^7.0.0"
  }
}

使用以下 Node.js 示例在 helloGCS 目录中创建一个 index.js 文件：

const functions = require('@google-cloud/functions-framework');

// Register a CloudEvent callback with the Functions Framework that will
// be triggered by Cloud Storage.
functions.cloudEvent('helloGCS', cloudEvent => {
  console.log(`Event ID: ${cloudEvent.id}`);
  console.log(`Event Type: ${cloudEvent.type}`);

  const file = cloudEvent.data;
  console.log(`Bucket: ${file.bucket}`);
  console.log(`File: ${file.name}`);
  console.log(`Metageneration: ${file.metageneration}`);
  console.log(`Created: ${file.timeCreated}`);
  console.log(`Updated: ${file.updated}`);
});

Python

创建名为 helloGCS 的新目录，并转到此目录中：
```
   mkdir helloGCS
   cd helloGCS
```
在 helloGCS 目录中创建一个 requirements.txt 文件，以指定 Python 依赖项：
```
functions-framework==3.5.0
cloudevents==1.11.0
```
这会添加示例所需的软件包。

使用以下 Python 示例在 helloGCS 目录中创建一个 main.py 文件：

from cloudevents.http import CloudEvent

import functions_framework


# Triggered by a change in a storage bucket
@functions_framework.cloud_event
def hello_gcs(cloud_event: CloudEvent) -> tuple:
    """This function is triggered by a change in a storage bucket.

    Args:
        cloud_event: The CloudEvent that triggered this function.
    Returns:
        The event ID, event type, bucket, name, metageneration, and timeCreated.
    """
    data = cloud_event.data

    event_id = cloud_event["id"]
    event_type = cloud_event["type"]

    bucket = data["bucket"]
    name = data["name"]
    metageneration = data["metageneration"]
    timeCreated = data["timeCreated"]
    updated = data["updated"]

    print(f"Event ID: {event_id}")
    print(f"Event type: {event_type}")
    print(f"Bucket: {bucket}")
    print(f"File: {name}")
    print(f"Metageneration: {metageneration}")
    print(f"Created: {timeCreated}")
    print(f"Updated: {updated}")

    return event_id, event_type, bucket, name, metageneration, timeCreated, updated

部署事件驱动的函数

通过在包含示例代码的目录中运行以下命令来部署名为 helloworld-events 的函数：

Node.js

gcloud beta run deploy helloworld-events \
      --source . \
      --function helloGCS \
      --base-image nodejs20 \
      --region us-central1 \

Python

gcloud beta run deploy helloworld-events \
      --source . \
      --function hello_gcs \
      --base-image python312 \
      --region us-central1 \

部署完成后，Google Cloud CLI 会显示一个运行 helloworld-events 服务的网址。

创建 Eventarc 触发器

Eventarc 触发器会将 Cloud Storage 存储桶中的事件发送到 helloworld-events Cloud Run 服务。

创建一个过滤 Cloud Storage 事件的触发器：
```
gcloud eventarc triggers create TRIGGER_NAME  \
    --location=${REGION} \
    --destination-run-service=helloworld-events  \
    --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 替换为触发器的名称。
- 将 PROJECT_ID 替换为 Google Cloud 项目 ID。
- 将 PROJECT_NUMBER 替换为您的 Google Cloud 项目编号。
请注意，首次在 Google Cloud 项目中创建 Eventarc 触发器时，预配 Eventarc 服务代理可能会有延迟。通常，您可以尝试再次创建触发器，以解决此问题。如需了解详情，请参阅权限遭拒错误。

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

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

输出应类似如下所示：

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

生成并查看事件

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

将文本文件上传到 Cloud Storage 以生成事件：
```
 echo "Hello World" > random.txt
 gcloud storage cp random.txt gs://PROJECT_ID-bucket/random.txt
```
上传操作会生成事件，而 Cloud Run 函数会记录事件的消息。
如需查看日志条目，请执行以下操作：
1. 过滤日志条目并以 JSON 格式返回输出：
```
gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json
```
2. 查找类似如下的日志条目：
```
[
  {
   ....
    "resource": {
      "labels": {
        ....
        "location": "us-central1",
        .....
        "service_name": "helloworld-events"
      },
    },
    "textPayload": "File: random.txt",
     .....
  }
]
```
  注意：如果您没有看到日志条目，请等待几分钟，然后重试 gcloud logging read 命令。触发器创建后可能最长需要两分钟才能开始过滤事件。
  
  您可能需要等待一些时间才能看到日志。如果您没有立即看到日志，请稍等片刻，然后再检查一次。

您看到日志条目后，即表示您已成功部署了在文本文件上传到 Cloud Storage 时触发的事件驱动函数。

清理

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

删除项目

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

要删除项目，请执行以下操作：

In the Google Cloud console, go to the Manage resources page.
Go to Manage resources
In the project list, select the project that you want to delete, and then click Delete.
In the dialog, type the project ID, and then click Shut down to delete the project.

删除教程资源

删除您在本教程中部署的 Cloud Run 服务：
```
gcloud run services delete SERVICE_NAME
```
其中，SERVICE_NAME 是您选择的服务名称。

您还可以从 Google Cloud 控制台中删除 Cloud Run 服务。
移除您在教程设置过程中添加的任何 gcloud CLI 默认配置。

例如：

gcloud config unset run/region

或

gcloud config unset project
删除在本教程中创建的其他 Google Cloud 资源：
- 删除 Eventarc 触发器：
```
gcloud eventarc triggers delete TRIGGER_NAME
```
  将 TRIGGER_NAME 替换为您的触发器的名称。

使用 Eventarc 触发 Cloud Storage 中的函数

目标

费用

准备工作

设置所需角色

所需权限

创建 Cloud Storage 存储桶

编写事件驱动型函数

Node.js

Python

部署事件驱动的函数

Node.js

Python

创建 Eventarc 触发器

生成并查看事件

清理

删除项目

删除教程资源

后续步骤