将事件发布到 Cloud Run 作业

将事件发布到 Cloud Run 作业

高级

本快速入门介绍如何在您的 Google Cloud 项目中创建 Eventarc Advanced 总线和注册，以发布和接收事件消息。

• 总线充当中央路由器，接收来自事件来源或由提供方发布的消息。

• 注册通过处理流水线将总线接收的消息路由到一个或多个 目的地。

在本快速入门中，您将执行以下操作：

1. 从源代码部署 Cloud Run 作业。

2. 创建 Eventarc Advanced 总线。

3. 创建 Eventarc Advanced 注册。

4. 向总线发布事件消息。

5. 确认 Cloud Run 作业已成功执行。

您可以使用 gcloud CLI 来完成本快速入门。

准备工作

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

登录您的 Google Cloud 账号。如果您是 Google Cloud的新用户， 请创建账号，以评估我们的产品在 实际场景中的表现。新客户还可以获得 300 美元的免费抵用金，用于 运行、测试和部署工作负载。

安装 Google Cloud CLI。

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

创建或选择 Google Cloud 项目。

选择或创建项目所需角色

• 选择项目：选择项目不需要特定的 IAM 角色，您可以选择您已被 授予角色的任何项目。
• 创建项目：如需创建项目，您需要具有 Project Creator 角色 (roles/resourcemanager.projectCreator)，该角色包含 resourcemanager.projects.create 权限。了解如何授予 角色。

注意：如果您不打算保留在此过程中创建的 资源，请创建项目，而不是 选择现有项目。完成这些步骤后，您可以 删除项目，移除与该项目关联的所有资源。

• 创建 Google Cloud 项目：

  gcloud projects create PROJECT_ID

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

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

  gcloud config set project PROJECT_ID

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

验证是否已为您的 Google Cloud 项目启用结算功能。

启用 Artifact Registry、Cloud Build、Cloud Run 和 Eventarc API：

启用 API 所需的角色

如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予 角色。

gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com 

安装 Google Cloud CLI。

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

创建或选择 Google Cloud 项目。

选择或创建项目所需角色

• 选择项目：选择项目不需要特定的 IAM 角色，您可以选择您已被 授予角色的任何项目。
• 创建项目：如需创建项目，您需要具有 Project Creator 角色 (roles/resourcemanager.projectCreator)，该角色包含 resourcemanager.projects.create 权限。了解如何授予 角色。

注意：如果您不打算保留在此过程中创建的 资源，请创建项目，而不是 选择现有项目。完成这些步骤后，您可以 删除项目，移除与该项目关联的所有资源。

• 创建 Google Cloud 项目：

  gcloud projects create PROJECT_ID

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

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

  gcloud config set project PROJECT_ID

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

验证是否已为您的 Google Cloud 项目启用结算功能。

启用 Artifact Registry、Cloud Build、Cloud Run 和 Eventarc API：

启用 API 所需的角色

如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予 角色。

gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com 

1. 更新 gcloud 组件：

   gcloud components update

2. 使用您的账号登录：

   gcloud auth login

3. 设置本快速入门中使用的配置变量：

   REGION=REGION

   将 REGION 替换为总线的 受支持位置，例如 us-central1。

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

   如果您不是项目创建者，则必须向主账号授予项目的必需权限。 例如，主账号可以是 Google 账号（针对最终用户）或服务帐号（针对应用和计算工作负载）。

   所需权限

   如需获得完成本快速入门所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

   • Cloud Run Developer (roles/run.developer)
   • Eventarc Developer (roles/eventarc.developer)
   • Eventarc Message Bus Admin (roles/eventarc.messageBusAdmin)
   • 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)

   如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

5. 如需向 Eventarc Advanced 授予执行 Cloud Run 作业所需的权限，请让您的管理员向服务帐号授予项目的 Cloud Run Invoker (roles/run.invoker) IAM 角色：
   注意：如需执行会替换作业配置的作业（例如，通过 定义消息绑定），您必须授予 Cloud Run Developer (roles/run.developer) 或 Cloud Run Jobs Executor With Overrides (roles/run.jobsExecutorWithOverrides) IAM 角色。Google Cloud 如需了解详情，请参阅 替换特定执行的作业 配置。
   1. 创建一个服务帐号。为了进行测试，您将此服务账号附加到 Eventarc Advanced 流水线以表示该流水线的身份。

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      将 SERVICE_ACCOUNT_NAME 替换为您的服务帐号的名称。
   2. 向服务帐号授予 roles/run.invoker IAM 角色：

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/run.invoker

从源代码部署 Cloud Run 作业

将 Cloud Run 作业 部署为事件 目的地。与侦听和处理请求的 Cloud Run 服务不同，Cloud Run 作业仅运行其任务并在完成后退出。作业不会监听或处理请求。

系统支持其他事件目的地，例如 Pub/Sub 主题、Workflows 或其他 HTTP 端点。如需了解详情，请参阅 事件提供方和目的地。

使用 gcloud run jobs deploy命令从 Python 源代码创建作业。您的代码会自动打包到容器映像中，上传到 Artifact Registry，然后部署到 Cloud Run。

1. 创建一个名为 jobs 的目录并导航到该目录：

   mkdir jobs
   cd jobs
   

2. 创建一个 main.py 文件，并将以下示例代码复制到该文件中：

   import os
   
   TASK_INDEX = os.getenv("CLOUD_RUN_TASK_INDEX", 0)
   
   def main():
       """
       This job prints "Hello world"
       """
       print(f"Starting task #{TASK_INDEX}...")
       print("Hello world")
       print(f"Completed task #{TASK_INDEX}.")
   
   # Start script
   if __name__ == "__main__":
       main()
   

3. 创建一个名为 Procfile 的文本文件（不带文件扩展名），并将以下文本复制到该文件中：

   web: python3 main.py
   

4. 部署作业：

   gcloud run jobs deploy JOB_NAME \
       --source . \
       --tasks 1 \
       --region=$REGION

   将 JOB_NAME 替换为 Cloud Run 作业的唯一名称，例如 my-job。

创建 Eventarc Advanced 总线

总线接收来自消息来源或由提供方发布的事件消息，并充当消息路由器。

如需了解详情，请参阅 创建总线以路由消息。

注意 ：每个项目在每个 Google Cloud 受支持的区域中只能创建一个总线。

使用 gcloud eventarc message-buses create 命令在项目中创建 Eventarc Advanced 总线：

gcloud eventarc message-buses create BUS_NAME \
    --location=$REGION

将 BUS_NAME 替换为总线的 ID 或完全限定名称，例如 my-bus。

创建 Eventarc Advanced 注册

注册决定哪些消息会路由到目的地。它还会指定用于为事件消息配置目的地的流水线。 在本例中，目标目的地是 Cloud Run 作业。

如需了解详情，请参阅 创建注册以接收事件。

使用 gcloud CLI 时，您首先创建流水线，然后创建注册：

**注意**： 创建流水线可能需要 10 多分钟时间。

1. 使用 gcloud eventarc pipelines create 命令创建流水线：

   gcloud eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='JOB_URI',http_endpoint_message_binding_template='{"body": ""}',oauth_token_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --input-payload-format-json= \
       --location=$REGION

   替换以下内容：

   • PIPELINE_NAME：流水线的 ID 或完全限定名称，例如 my-pipeline。

   • JOB_URI：Cloud Run 作业的 URI，格式如下：

     https://REGION-run.googleapis.com/apis/run.googleapis.com/v1/namespaces/PROJECT_NUMBER/jobs/JOB_NAME:run

     您可以通过运行以下命令检索项目编号：

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

   请注意以下几点：

   • http_endpoint_message_binding_template 键会将事件转换为 Cloud Run Admin API 预期的格式。 定义消息绑定时，您必须配置输入格式才能访问载荷，例如：{"body": ""}。
   • oauth_token_authentication_service_account 键指定服务账号电子邮件地址。此电子邮件地址用于生成 OAuth 令牌 ，该令牌通常仅在调用托管在 *.googleapis.com上的 Google API 时使用。

2. 使用 gcloud eventarc enrollments create 命令创建注册：

   gcloud eventarc enrollments create ENROLLMENT_NAME \
       --cel-match=MATCH_EXPRESSION \
       --destination-pipeline=PIPELINE_NAME \
       --message-bus=BUS_NAME \
       --message-bus-project=PROJECT_ID \
       --location=$REGION

   替换以下内容：

   • ENROLLMENT_NAME：注册的 ID 或完全限定名称，例如 my-enrollment。

   • MATCH_EXPRESSION：此注册的匹配表达式（使用 CEL）- 例如：

     "message.type == 'hello-world-type'"
     

向总线发布事件消息

如需直接向总线发布消息，请使用 gcloud eventarc message-buses publish 命令或向 Eventarc Publishing REST API发送请求。 如需了解详情，请参阅 直接发布事件。

消息必须采用 CloudEvents 格式，这是一种以通用方式描述事件数据的规范。data 元素是事件的载荷。任何格式正确的 JSON 都可以放在此字段中。如需详细了解 CloudEvents 上下文属性，请参阅 事件格式。

以下示例展示了如何直接向 Eventarc Advanced 总线发布事件：

示例 1

使用 gcloud CLI 以及 --event-data 和其他事件属性标志向总线发布事件：

gcloud eventarc message-buses publish BUS_NAME \
    --event-data='{"key": "hello-world-data"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

示例 2

使用 gcloud CLI 和 --json-message 标志以 JSON 消息的形式向总线发布事件：

gcloud eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"key": "hello-world-data"}}'

发布事件后，您应该会收到“事件发布成功”消息。

确认 Cloud Run 作业已成功执行

向 Eventarc Advanced 总线发布事件后，请检查 Cloud Run 作业的日志，以验证 Cloud Run 作业是否已成功执行并打印了“Hello world”。 作业可能需要几分钟才能运行并完成。

1. 过滤日志条目并使用 gcloud logging read 命令返回输出：

   gcloud logging read 'textPayload: "Hello world"'
   

2. 查找如下日志条目：

   insertId: 693c8dd0000cb2976d7966b8
   ...
   labels:
       job_name: JOB_NAME
       location: REGION
       project_id: PROJECT_ID
   type: cloud_run_job
   textPayload: Hello world
   timestamp: '2025-12-12T21:49:04.832151Z'
   

   注意： 如果您没有看到日志条目，请等待几分钟，然后重试 gcloud logging read 命令。

3. 您还可以使用gcloud run jobs describe命令确认 Cloud Run 作业已成功执行 ：

   gcloud run jobs describe JOB_NAME \
       --region=$REGION
   

   您应该会收到类似如下所示的输出：

   ✔ Job JOB_NAME in region us-central1
   Executed 1 time
   ...
   

您已成功创建 Eventarc Advanced 总线和注册，向总线发布事件消息，并在事件接收器的日志中验证了预期结果。

清理

为避免在本快速入门完成后继续计费，请删除您创建的资源：

1. 删除 Cloud Run 作业。

2. 删除 Eventarc Advanced 资源：

   1. 删除注册。

   2. 删除流水线。

   3. 删除总线。

或者，删除 Google Cloud 项目以避免产生费用。 删除项目会停止对该项目内使用的所有资源计费。 Google Cloud

注意：删除项目会产生以下影响：

• 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
• 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。

如果您打算探索多个架构、教程或快速入门，则重复使用项目 可以帮助您避免超出项目配额限制。

删除项目： Google Cloud

gcloud projects delete PROJECT_ID

后续步骤

• 发布来自 Google 来源的事件
• 直接发布事件
• 转换已接收事件
• 设置已接收事件的格式
• 问题排查