Cloud Build 可將建構作業更新通知傳送至特定管道 (例如 Slack 或 SMTP 伺服器)，本頁說明如何使用 BigQuery 通知程式設定通知。
您可以透過 BigQuery 通知器，指定要儲存在資料庫中的建構版本篩選條件。舉例來說，您可以依據觸發 ID、標記或替代值將建構版本分組。BigQuery 通知程式也會以標準化格式將資料寫入 BigQuery，包括無法立即在建構物件上存取的計算欄位，例如圖片大小或執行時間。如要瞭解如何將記錄檔項目匯出至 BigQuery 或其他目的地，請參閱「使用 Google Cloud 控制台匯出記錄檔」。
事前準備
如果尚未啟用 Cloud Build、Cloud Run、Pub/Sub 和 BigQuery API，請啟用這些 API。
啟用 API 時所需的角色
如要啟用 API，您必須具備
serviceusage.services.enable權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
- 安裝 Google Cloud CLI。
設定 BigQuery 通知
以下章節說明如何使用 BigQuery 通知程式手動設定 HTTP 通知。如要自動設定，請參閱「自動設定通知」。
如要設定 BigQuery 通知，請按照下列步驟操作：
授予 Cloud Run 服務帳戶建立及寫入 BigQuery 資料表的權限、擷取與建構作業相關的 Artifact Registry 資料的權限，以及 Cloud Storage bucket 的讀取和寫入權限：
前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面：
找出與專案相關聯的 Compute Engine 預設服務帳戶：
您的 Compute Engine 預設服務帳戶會類似於下列項目：
PROJECT_NUMBER-compute@developer.gserviceaccount.com在包含「Compute Engine 預設服務帳戶」的資料列中，按一下「鉛筆」圖示。 你會看到「編輯權限」分頁。
按一下 [Add another role] (新增其他角色)。
新增下列角色：
- Artifact Registry 讀取者
- BigQuery 資料編輯者
- Storage 物件檢視者
Artifact Registry Reader 角色可讓您擷取圖片資料。「BigQuery 資料編輯者」可讓您讀取及寫入資料。 儲存空間物件檢視者可讓您讀取 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是 bucket 名稱。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：
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 bucket：
如果沒有 Cloud Storage bucket，請執行下列指令建立 bucket，其中 BUCKET_NAME 是您要為 bucket 命名的名稱，須符合命名規定。
gcloud storage buckets create gs://BUCKET_NAME/將通知程式設定檔上傳至 bucket：
gcloud storage cp CONFIG_FILE_NAME gs://BUCKET_NAME/CONFIG_FILE_NAME其中：
BUCKET_NAME是 bucket 名稱。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 支援通知程式映像檔九個月。九個月後，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是服務帳戶的顯示名稱。
將在Google Cloud 專案中建立驗證權杖所需的權限，授予 Pub/Sub 訂閱項目身分識別服務帳戶。
gcloud iam service-accounts add-iam-policy-binding \ SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iiam.gserviceaccount.com \ --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \ --role=roles/iam.serviceAccountTokenCreator其中：
PROJECT_ID是 Google Cloud 專案的 ID。PROJECT_NUMBER是您的 Google Cloud 專案編號。
將 Cloud Run
Invoker角色授予 SUB_IDENTITY_SERVICE_ACCOUNT 服務帳戶：gcloud run services add-iam-policy-binding SERVICE_NAME \ --member=serviceAccount:SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com \ --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.iam.gserviceaccount.com
其中：
+ 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 控制台頁面：
在「Resources」(資源) 下方，按一下要查詢的資料表名稱。
在查詢編輯器中編寫 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 Notifier README。如要進一步瞭解如何使用 BigQuery 查詢資料，請參閱「查詢及查看資料」一文。
使用 CEL 篩選建構事件
Cloud Build 會在 Build 資源中列出的欄位上，使用含有變數 build 的 CEL，存取與建構事件相關聯的欄位，例如觸發條件 ID、映像檔清單或替代值。您可以使用 filter 字串，透過「Build」(建構) 資源中列出的任何欄位，篩選建構設定檔中的建構事件。如要瞭解與欄位相關的確切語法，請參閱 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 點：
filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")
您也可以依時間比較篩選建構事件。在下列範例中，filter 欄位會使用 timestamp 篩選建構事件，開始時間介於 2020 年 7 月 20 日上午 6 點至 2020 年 7 月 30 日上午 6 點之間。
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 建構設定檔。