Cloud Build 可將通知傳送至特定管道 (例如 Slack 或 SMTP 伺服器)，讓您掌握建構作業的最新動態。本頁面說明如何使用 BigQuery Notifier 設定通知。
透過 BigQuery 通知器，您可以指定要儲存在資料庫中的建構版本篩選條件。舉例來說，您可以依據觸發 ID、標記或替代值將建構版本分組。BigQuery 通知程式也會以標準化格式將資料寫入 BigQuery，包括無法立即在建構物件上存取的計算欄位，例如圖片大小或執行時間。如要瞭解如何將記錄項目匯出至 BigQuery 或其他目的地，請參閱「使用 Google Cloud 控制台匯出記錄」。
事前準備
啟用 Cloud Build、Cloud Run、Pub/Sub 和 BigQuery API。
啟用 API 時所需的角色
如要啟用 API，您需要服務使用情形管理員 IAM 角色 (
roles/serviceusage.serviceUsageAdmin)，其中包含serviceusage.services.enable權限。瞭解如何授予角色。
- 安裝 Google Cloud CLI。
設定 BigQuery 通知
下一節說明如何使用 BigQuery Notifier 手動設定 HTTP 通知。如要自動化處理設定，請參閱「自動化處理通知設定」。
如要設定 BigQuery 通知，請按照下列步驟操作：
授予 Cloud Run 服務帳戶建立及寫入 BigQuery 資料表的權限、擷取與建構作業相關聯的 Artifact Registry 資料的權限，以及 Cloud Storage 值區的讀取和寫入權限：
前往 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是值區名稱。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是值區名稱。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 權限，在專案中建立驗證權杖： Google Cloud
gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \ --role=roles/iam.serviceAccountTokenCreator其中：
project-id是 Google Cloud 專案 ID。project-number是您的 Google Cloud 專案編號。
建立服務帳戶，代表您的 Pub/Sub 訂閱身分：
gcloud iam service-accounts create cloud-run-pubsub-invoker \ --display-name "Cloud Run Pub/Sub Invoker"您可以使用
cloud-run-pubsub-invoker，或將其改成不同於專案中其他服務帳戶的名稱。 Google Cloud將 Cloud Run
Invoker權限授予cloud-run-pubsub-invoker服務帳戶：gcloud run services add-iam-policy-binding service-name \ --member=serviceAccount:cloud-run-pubsub-invoker@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=cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com其中：
subscriber-id是您要為訂閱項目指定的名稱。service-url是 Cloud Run 為新服務產生的網址。project-id是 Google Cloud 專案 ID。
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 Notifier README。如要進一步瞭解如何使用 BigQuery 查詢資料，請參閱「查詢及查看資料」一文。
使用 CEL 篩選建構事件
Cloud Build 會在 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 點的建構事件：
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")
依取代項目篩選
如要依替代項目篩選，請在 filter 欄位中指定替代變數，並使用 build.substitutions。在下列範例中，「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 建構設定檔。