将事件发布到 BigQuery 表

将事件发布到 BigQuery 表

高级

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

• 借助总线，您可以集中管理系统中的消息流，并将其用作路由器。它会从消息来源或提供方接收事件消息，并根据注册信息评估这些消息。

• 注册会标识对特定总线的订阅，并定义消息的匹配条件，从而使消息能够相应地路由到一个或多个目的地。

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

1. 创建 BigQuery 表格。

2. 创建 Eventarc Advanced 总线。

3. 创建 Eventarc Advanced 注册。

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

5. 查看 BigQuery 表中的事件数据。

您可以使用 gcloud CLI 和 bq 命令行工具完成本快速入门。

准备工作

您的组织定义的安全限制条件可能会导致您无法完成以下步骤。如需了解相关问题排查信息，请参阅在受限的 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.

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

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

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Eventarc APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable bigquery.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com

Install the Google Cloud CLI.

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

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

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Eventarc APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable bigquery.googleapis.com eventarc.googleapis.com eventarcpublishing.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 角色：

   • BigQuery Data Editor (roles/bigquery.dataEditor)
   • 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 授予更新 BigQuery 表属性所需的权限，请让您的管理员向您的 Google Cloud 项目中的服务账号授予 BigQuery Data Editor (roles/bigquery.dataEditor) IAM 角色：
   1. 创建一个服务账号。为了进行测试，您会将此服务账号附加到 Eventarc Advanced 流水线，以表示该流水线的身份。

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

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

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

创建 BigQuery 表

创建 BigQuery 表作为您的事件目标位置。系统还支持其他事件目标位置，例如 Pub/Sub 主题、Workflows 或其他 HTTP 端点。如需了解详情，请参阅事件提供方和目的地。

在创建 BigQuery 表之前，请先创建一个数据集（作为表的顶级容器）和一个表架构。

1. 如需创建新数据集，请使用带有 --dataset 标志的 bq mk 命令。

   bq --location=$REGION mk --dataset DATASET_ID

   将 DATASET_ID 替换为 BigQuery 数据集的唯一名称，例如 my_dataset。

2. 在终端中，创建一个名为 my-schema.json 的新文件。

3. 将以下架构复制并粘贴到新文件中，然后保存该文件。

   [
       {
           "name": "name",
           "type": "STRING",
           "mode": "REQUIRED"
       },
       {
           "name": "age",
           "type": "INTEGER",
           "mode": "NULLABLE"
       }
   ]

4. 如需创建表，请将 bq mk 命令与 --table 标志搭配使用。

   bq mk --table PROJECT_ID:DATASET_ID.TABLE_ID my-schema.json

   将 TABLE_ID 替换为 BigQuery 表的唯一名称，例如 my-table。

创建 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 注册

注册可确定哪些消息会路由到目的地，还会指定用于为事件消息配置目的地的流水线。在这种情况下，目标目的地是 BigQuery API 端点。

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

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

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

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

   gcloud eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID/insertAll',http_endpoint_message_binding_template='{"headers": headers.merge({"content-type":"application/json"}), "body": {"rows":[{"json":message.data}]}}',oauth_token_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --input-payload-format-json= \
       --location=$REGION

   将 PIPELINE_NAME 替换为流水线的 ID 或完全限定的名称，例如 my-pipeline。

   请注意以下几点：

   • http_endpoint_message_binding_template 键会将事件转换为 API 预期的格式。定义消息绑定时，您必须配置输入格式才能访问载荷。
   • oauth_token_authentication_service_account 键用于指定服务账号电子邮件地址。此电子邮件地址用于生成 OAuth 令牌，通常，只有在调用 *.googleapis.com 上托管的 Google API 时，才应使用该令牌。
   • input-payload-format-json 标志用于指定流水线的输入载荷格式为 JSON；任何不符合此格式的消息都会被视为持久性错误。

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 元素是事件的载荷，最终必须与 BigQuery 表的架构相匹配。此字段中可以包含任何格式正确的 JSON。如需详细了解 CloudEvents 上下文属性，请参阅事件格式。

以下是将事件直接发布到 Eventarc Advanced 总线的示例：

示例 1

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

gcloud eventarc message-buses publish BUS_NAME \
    --event-data='{"name": "my-name", "age": "20"}' \
    --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":
 {"name": "my-name", "age": "20"}}'

发布活动后，您应该会收到“活动已成功发布”消息。

查看 BigQuery 表中的事件数据

将事件发布到 Eventarc Advanced 总线后，您可以使用 bq query 命令确认 BigQuery 表中是否添加了新行。

bq query \
    --use_legacy_sql=false \
    'SELECT
      *
    FROM
      `PROJECT_ID.DATASET_ID.TABLE_ID`
    LIMIT
      10;'

您已成功创建 Eventarc Advanced 总线和注册，向总线发布事件消息，并通过查询 BigQuery 表验证了预期结果。

清理

完成此快速入门中描述的任务后，您可以通过删除所创建的资源来避免继续计费：

1. 删除 BigQuery 表。

2. 删除 BigQuery 数据集。

3. 删除 Eventarc Advanced 资源：

   1. 删除注册信息。

   2. 删除流水线。

   3. 删除总线。

或者，您也可以删除 Google Cloud 项目，以避免产生费用。删除 Google Cloud 项目后，系统即会停止对该项目中使用的所有资源计费。

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

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

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

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

后续步骤

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