Cloud Build 可以通过向特定渠道（例如 Slack 或 SMTP 服务器）发送通知来通知您构建更新。本页介绍如何使用 BigQuery 通知程序 配置通知。
BigQuery 通知程序允许您指定要存储在数据库中的构建的过滤条件。例如，您可以按触发器 ID、标记或 替换值对 构建进行分组。此外，BigQuery 通知程序还会以标准化格式将数据写入 BigQuery，包括无法在构建对象上立即访问的计算字段，例如图片大小或执行时长。如需了解如何将日志条目导出到 BigQuery 或其他目标位置，请参阅使用 Google Cloud 控制台导出日志。
准备工作
启用 Cloud Build、Cloud Run、Pub/Sub 和 BigQuery API。
启用 API 所需的角色
如需启用 API，您需要拥有
serviceusage.services.enable权限。如果您创建了项目，则可能已通过所有者角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获取此权限。了解如何授予角色。
- 安装 Google Cloud CLI。
配置 BigQuery 通知
以下部分介绍如何使用 BigQuery 通知程序来手动配置 HTTP 通知。 如果您希望改为自动配置，请参阅自动配置通知。
如需配置 BigQuery 通知，请执行以下操作：
向 Cloud Run 服务帐号授予创建和写入 BigQuery 表的权限，获取与构建相关的 Artifact Registry 数据的权限，以及 Cloud Storage 存储分区的读写权限：
前往 Google Cloud 控制台中的 IAM 页面：
找到与您的项目关联的 Compute Engine 默认服务账号：
您的 Compute Engine 默认服务账号 将如下所示：
PROJECT_NUMBER-compute@点击您的 Compute Engine 默认服务账号 所在行中的铅笔图标。 您将看到编辑权限 标签页。
点击添加其他角色 。
添加以下角色：
- Artifact Registry Reader
- BigQuery Data Editor
- Storage Object Viewer
借助 Artifact Registry Reader 角色，您可以针对映像提取数据。 BigQuery Data Editor 为您提供数据的读写访问权限。Storage Object Viewer 为您提供 Cloud Storage 对象的读取权限。
点击保存。
编写通知程序配置文件以配置您的 BigQuery 通知程序并过滤构建事件：
在以下示例通知程序配置文件中，
filter字段使用通用表达式语言和变量build来过滤具有指定触发器 ID 的构建事件：apiVersion: cloud-build-notifiers/v1 kind: BigQueryNotifier metadata: name: example-bigquery-notifier spec: notification: filter: build.build_trigger_id == "123e4567-e89b-12d3-a456-426614174000" params: buildStatus: $(build.status) delivery: table: projects/PROJECT_ID/datasets/DATASET_NAME/tables/TABLE_NAME template: type: golang uri: gs://BUCKET_NAME/bq.json其中：
buildStatus是用户定义的参数。此参数采用 ${build.status} 的值，即构建的状态。BUCKET_NAME是您的存储桶的名称。PROJECT_ID是您的 Google Cloud 项目的 ID。DATASET_NAME是您要为数据集指定的名称。TABLE_NAME是您要为表指定的名称。uri字段引用bq.json文件。此文件引用 Cloud Storage 上托管的 JSON 模板，并表示要插入到 BigQuery 表中的信息。
如需查看模板文件的示例，请参阅 cloud-build-notifiers-repository 中的
bq.json文件。通知程序配置文件中的 TABLE_NAME 可以 参考：
- 不存在的表
- 没有架构的空表
具有与 BigQuery 通知程序中的架构规范匹配的架构的现有表
建议您将构建触发器 ID 指定为过滤条件，因为通过指定构建触发器 ID，您可以关联触发器的构建数据。 您还可以在列表中指定多个触发器 ID：
build.build_trigger_id in ["example-id-123", "example-id-456"]。要获取触发器 ID，请运行以下命令，其中 TRIGGER_NAME 是触发器的名称：
gcloud builds triggers describe TRIGGER_NAME
该命令将列出与触发器关联的字段，包括触发器 ID。
如需查看此示例，请参阅 BigQuery 通知程序的通知程序配置文件。
如需了解可用于过滤的其他字段，请参阅构建资源。如需了解其他过滤示例，请参阅使用 CEL 过滤构建事件。
将通知程序配置文件上传到 Cloud Storage 存储桶
如果没有 Cloud Storage 存储桶，请运行以下命令创建一个存储桶，其中 BUCKET_NAME 是您想要为存储桶指定的名称（须遵循 命名要求部分）。
gcloud storage buckets create gs://BUCKET_NAME/将通知程序配置文件上传到您的存储桶：
gcloud storage cp CONFIG_FILE_NAME gs://BUCKET_NAME/CONFIG_FILE_NAME其中：
BUCKET_NAME是您的存储分区的名称。CONFIG_FILE_NAME是通知程序配置文件的名称。
将通知程序部署到 Cloud Run：
gcloud run deploy SERVICE_NAME \ --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/bigquery:latest \ --no-allow-unauthenticated \ --update-env-vars=CONFIG_PATH=CONFIG_PATH,PROJECT_ID=PROJECT_ID其中：
SERVICE_NAME是您要将映像部署到的 Cloud Run 服务的名称。CONFIG_PATH是 BigQuery 通知程序的通知程序配置文件的路径，gs://BUCKET_NAME/CONFIG_FILE_NAME。PROJECT_ID是您的 Google Cloud 项目的 ID。
gcloud run deploy命令会从 Cloud Build 拥有的 Artifact Registry 拉取最新版本的托管 映像。Cloud Build 支持通知程序映像 9 个月。9 个月后，Cloud Build 会删除映像版本。如果您想使用旧的映像版本，则需要在gcloud run deploy命令的image属性中指定映像标记的完整语义版本。您可以在 Artifact Registry 中找到以前的映像版本和标记。创建一个服务帐号以表示您的 Pub/Sub 订阅身份：
gcloud iam service-accounts create SUB_IDENTITY_SERVICE_ACCOUNT \ --display-name "SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME"其中：
SUB_IDENTITY_SERVICE_ACCOUNT是服务帐号的名称。SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME是服务帐号的显示名称。
向 Pub/Sub 订阅身份服务帐号 授予在您的 Google Cloud 项目中创建身份验证令牌所需的权限。
gcloud iam service-accounts add-iam-policy-binding \ SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.i \ --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub. \ --role=roles/iam.serviceAccountTokenCreator其中：
PROJECT_ID是您的 Google Cloud 项目的 ID。PROJECT_NUMBER是您的 Google Cloud 项目编号。
向 SUB_IDENTITY_SERVICE_ACCOUNT 服务帐号授予 Cloud Run
Invoker角色：gcloud run services add-iam-policy-binding SERVICE_NAME \ --member=serviceAccount:SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID. \ --role=roles/run.invoker其中：
SERVICE_NAME是您要将映像部署到的 Cloud Run 服务的名称。PROJECT_ID是您的 Google Cloud 项目的 ID。
创建
cloud-builds主题以接收通知程序的构建更新消息：gcloud pubsub topics create cloud-builds您还可以在构建配置文件中定义自定义主题名称 ，以便将消息发送到自定义主题。在这种情况下，您 将创建一个具有相同自定义主题名称的主题：
gcloud pubsub topics create topic-name如需了解详情，请参阅 构建通知的 Pub/Sub 主题。
为通知程序创建 Pub/Sub 推送订阅者：
gcloud pubsub subscriptions create subscriber-id \
--topic=cloud-builds \
--push-endpoint=SERVICE_URL \
--push-auth-service-account=SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.
其中：
+ SUBSCRIBER_ID 是您要为订阅指定的名称。
+ SERVICE_URL 是 Cloud Run
为新服务生成的网址。
+ PROJECT_ID 是您的 Google Cloud 项目的 ID。
Note: By default, [subscriptions expire after 31 days of inactivity](/pubsub/docs/subscription-overview#lifecycle).
You can adjust or disable the expiration period by including the
[`--expiration-period` flag](/sdk/gcloud/reference/pubsub/subscriptions/create#--expiration-period)
when creating the subscription.
您的 Cloud Build 项目的通知现已设置完毕。
下次您调用构建时，系统将使用与配置给 BigQuery 通知程序的过滤条件匹配的最新数据来更新表。
查看构建数据
如需在 BigQuery 中查看构建数据，请执行以下操作：
打开 BigQuery 控制台页面：
在资源下，点击用于配置 BigQuery 通知程序的项目 ID。
点击您的数据集名称。
点击您的表名称。
现在，您可以看到与您的表相关的信息，包括数据架构和表中列出的版本数据预览。
访问构建数据
您可以使用 bq 命令行工具或 BigQuery 控制台查询表中的数据。
CLI
如需使用 bq 命令行工具查询表中的数据，请在终端中运行以下命令，其中 SQL_QUERY 是查询：
bq query SQL_QUERY
如果您打算在此页面上使用查询示例，请确保在命令中指定--nouse_legacy_sql
标志。bq
命令行工具使用旧版 SQL，而示例查询不使用。在终端中运行以下命令，以查询不含旧版 SQL 的数据：
bq query SQL_QUERY --nouse_legacy_sql
控制台
如需使用 BigQuery 控制台查询表中的数据，请执行以下操作：
打开 BigQuery 控制台页面：
在资源下，点击要查询的表名称。
在查询编辑器 中编写 SQL 查询。
使用查询访问构建数据
以下示例查询展示了如何按照 BigQuery 通知程序的配置访问构建事件的构建数据：
总体构建记录
SELECT * FROM `projectID.datasetName.tableName`
按状态分组的构建计数
SELECT STATUS, COUNT(*)
FROM `projectID.datasetName.tableName`
GROUP BY STATUS
本周的每日部署频率
SELECT DAY, COUNT(STATUS) AS Deployments
FROM (SELECT DATETIME_TRUNC(CreateTime, WEEK) AS WEEK,
DATETIME_TRUNC(CreateTime, DAY) AS DAY,
STATUS
FROM `projectID.datasetName.tableName`
WHERE STATUS="SUCCESS")
WHERE WEEK = DATETIME_TRUNC(CURRENT_DATETIME(), WEEK)
GROUP BY DAY
如需查看更多示例查询，请参阅 GitHub 上的 cloud-build-notifiers 代码库中的 Cloud Build BigQuery 通知程序 README。如需详细了解如何使用 BigQuery 查询数据，请参阅查询和查看数据。
使用 CEL 过滤构建事件
Cloud Build 在构建资源中列出的字段上搭配使用 CEL 与变量 build，以便访问与构建事件关联的字段，例如触发器 ID、图片列表或替换值。您可以使用 filter
字符串，通过构建资源中列出的任何字段，来过滤通构建配置文件中的构建事件。如需查找与您的字段关联的具体语法，请参阅
cloudbuild.proto
文件。
按触发器 ID 过滤
要按触发器 ID 过滤，请使用 build.build_trigger_id 在 filter 字段中指定触发器 ID 的值，其中 trigger-id 是字符串形式的触发器 ID：
filter: build.build_trigger_id == trigger-id
按状态过滤
要按状态过滤，请使用 build.status 在 filter 字段中指定要过滤的构建状态。
以下示例展示了如何使用 filter 字段过滤状态为 SUCCESS 的构建事件：
filter: build.status == Build.Status.SUCCESS
您也可以过滤具有不同状态的构建。以下示例展示了如何使用 filter 字段过滤状态为 SUCCESS、FAILURE 或 TIMEOUT 的构建事件：
filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]
要查看您可以作为过滤依据的其他状态值，请参阅“构建资源参考”下的状态。
按标记过滤
要按标记过滤，请使用 build.tags 在 filter 字段中指定标记的值，其中 tag-name 是标记的名称：
filter: tag-name in build.tags
您可以使用 size 根据构建事件中指定的标记数量进行过滤。在以下示例中，filter 字段会过滤仅指定了两个标记且其中一个标记指定为 v1 的构建事件：
filter: size(build.tags) == 2 && "v1" in build.tags
按图片过滤
要按映像过滤，请使用 build.images 在 filter 字段中指定映像的值，其中 image-name 是 Artifact Registry 中列出的映像的全名，例如 us-east1-docker.pkg.dev/my-project/docker-repo/image-one：
filter: image-name in build.images
在以下示例中，filter 会过滤将 us-east1-docker.pkg.dev/my-project/docker-repo/image-one 或
us-east1-docker.pkg.dev/my-project/docker-repo/image-two 指定为映像名称的构建事件：
filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images
按时间过滤
您可以在 filter 字段中指定以下某个选项，以根据构建的创建时间、开始时间或结束时间过滤构建事件：build.create_time、build.start_time 或 build.finish_time。
在以下示例中，filter 字段会使用 timestamp 来过滤创建构建的请求时间为 2020 年 7 月 20 日上午 6:00 的构建事件。
filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")
您还可以按时间比较过滤构建事件。在以下示例中，filter 字段会使用 timestamp 过滤开始时间介于 2020 年 7 月 20 日上午 6:00 到 2020 年 7 月 30 日上午 6:00 之间的构建事件。
filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")
如需详细了解 CEL 中的时区表示方式，请参阅时区的语言定义。
要按构建的持续时间进行过滤，您可以使用 duration 比较时间戳。
在以下示例中，filter 字段会使用 duration 过滤包含至少运行了五分钟的构建的构建事件：
filter: build.finish_time - build.start_time >= duration("5m")
按替换过滤
您可以使用 build.substitutions 在 filter 字段中指定替换变量，从而按替换进行过滤。在以下示例中，filter 字段会列出包含替代变量 substitution-variable 的构建，并检查 substitution-variable 是否与指定的 substitution-value 匹配：
filter: build.substitutions[substitution-variable] == substitution-value
其中：
substitution-variable是替代变量的名称。substitution-value是替代变量值的名称。
您还可以按默认替换变量值进行过滤。在下面的示例中，filter 字段列出分支名称为 master 的构建，以及代码库名称为 github.com/user/my-example-repo 的构建。默认替换变量 BRANCH_NAME 和 REPO_NAME 将作为密钥传递给 build.substitutions：
filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"
如果要使用正则表达式过滤字符串，则可以使用内置的 matches 函数。在以下示例中，filter 字段过滤状态为 FAILURE 或 TIMEOUT 的构建，并且有一个构建替代变量 TAG_NAME，以及一个与正则表达式 v{DIGIT}.{DIGIT}.{3 DIGITS}) 匹配的值。
filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")
要查看默认替换值的列表，请参阅使用默认替换。
后续步骤
- 了解 Cloud Build 通知程序。
- 了解如何订阅构建通知。
- 了解如何编写 Cloud Build build 配置文件。