設定 BigQuery 通知

Cloud Build 可透過特定管道 (例如 Slack 或 SMTP 伺服器) 傳送通知，通知您建構作業的最新進度。本頁面說明如何使用 BigQuery 通知器設定通知。

BigQuery 通知器可讓您為要儲存在資料庫中的版本指定篩選器。舉例來說，您可以依觸發 ID、標記或替換值將版本分組。BigQuery 通知器也會以標準格式將資料寫入 BigQuery，其中包含在 Build 物件上無法立即存取的計算欄位，例如圖片大小或執行時間。如要瞭解如何將記錄項目匯出至 BigQuery 或其他目的地，請參閱「使用 Google Cloud 控制台匯出記錄」。

事前準備

  • Enable the Cloud Build, Cloud Run, Pub/Sub, and BigQuery APIs.

    Enable the APIs

設定 BigQuery 通知

以下章節將說明如何使用 BigQuery 通知器手動設定 HTTP 通知。如果您想改為自動化設定，請參閱「自動化處理通知設定」。

如要設定 BigQuery 通知，請按照下列步驟操作：

  1. 請授予 Cloud Run 服務帳戶權限，以便建立及寫入 BigQuery 資料表、擷取與建構相關的 Artifact Registry 資料，以及存取 Cloud Storage 值區的讀取和寫入權限：

    1. 前往 Google Cloud 控制台的「IAM」頁面：

      開啟 IAM 頁面

    2. 找出與專案相關聯的 Compute Engine 預設服務帳戶：

      Compute Engine 預設服務帳戶的畫面會類似下圖：

      project-number-compute@developer.gserviceaccount.com

    3. 按一下包含 Compute Engine 預設服務帳戶的資料列中的鉛筆圖示。您會看到「編輯存取權」分頁。

    4. 按一下 [Add another role] (新增其他角色)。

    5. 新增下列角色：

      • Artifact Registry Reader
      • BigQuery 資料編輯器
      • Storage 物件檢視者

      您可以使用 Artifact Registry Reader 角色擷取映像檔的資料。BigQuery 資料編輯器可讓您讀取及寫入資料。Storage 物件檢視器可讓您讀取 Cloud Storage 物件。

    6. 按一下 [儲存]。

  2. 編寫通知器設定檔，設定 BigQuery 通知器並篩選建構事件：

    在以下示例通知器設定檔中，filter 欄位會使用 Common Expression Language 和變數 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 通知器的通知器設定檔。

    如要瞭解可用於篩選的其他欄位，請參閱「Build」資源。如需其他篩選範例，請參閱「使用 CEL 篩選建構事件」。

  3. 將通知器設定檔上傳至 Cloud Storage 值區：

    1. 如果您沒有 Cloud Storage 值區，請執行下列指令來建立值區，其中 bucket-name 是您要給值區的名稱，必須符合命名規定。

      gcloud storage buckets create gs://bucket-name/

    2. 將通知器設定檔上傳至值區：

      gcloud storage cp config-file-name gs://bucket-name/config-file-name

      其中：

      • bucket-name 是值區的名稱。
      • config-file-name 是通知器設定檔的名稱。

  4. 將通知器部署至 Cloud Run：

     gcloud run deploy service-name \
   --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/slack:latest \
   --no-allow-unauthenticated \
   --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id

    其中：

    • service-name 是您要部署映像檔的 Cloud Run 服務名稱。
    • config-path 是 Slack 通知器 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 中找到先前的圖片版本和標記。

  5. 授予 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 專案編號。

  6. 建立服務帳戶，代表您的 Pub/Sub 訂閱身分：

    gcloud iam service-accounts create cloud-run-pubsub-invoker \
  --display-name "Cloud Run Pub/Sub Invoker"

    您可以使用 cloud-run-pubsub-invoker，或使用不同於 Google Cloud 專案中其他服務帳戶的名稱。

  7. 將 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。

  8. 建立 cloud-builds 主題，以便接收通知器的建構更新訊息：

    gcloud pubsub topics create cloud-builds

    您也可以在建構設定檔中定義自訂主題名稱，讓訊息改為傳送至自訂主題。在這種情況下，您會建立具有相同自訂主題名稱的主題：

    gcloud pubsub topics create topic-name

    詳情請參閱接收建構作業通知的 Pub/Sub 主題。

  9. 為通知器建立 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 中查看建構資料，請按照下列步驟操作：

  1. 開啟 BigQuery 控制台頁面：

    開啟 BigQuery 頁面

  2. 在「資源」下方，按一下用來設定 BigQuery 通知器的專案 ID。

  3. 按一下資料集名稱。

  4. 按一下資料表名稱。

您現在可以查看與資料表相關的資訊，包括結構定義，以及表格中列出的建構資料預覽。

存取建構資料

您可以使用 bq 指令列工具或 BigQuery 主控台查詢資料表中的資料。

CLI

如要使用 bq 指令列工具查詢資料表中的資料，請在終端機中執行下列指令，其中 sql-query 是查詢：

bq query sql-query

如果您打算使用本頁的查詢範例，請務必在指令中指定 --nouse_legacy_sql 旗標。bq 指令列工具使用舊版 SQL，而範例查詢則不使用。在終端機中執行下列指令，即可不使用舊版 SQL 查詢資料：

bq query sql-query --nouse_legacy_sql

主控台

如要透過 BigQuery 控制台查詢資料表中的資料，請按照下列步驟操作：

  1. 開啟 BigQuery 控制台頁面：

    開啟 BigQuery 頁面

  2. 在「資源」下方，按一下要查詢的資料表名稱。

  3. 在「Query editor」(查詢編輯器) 中編寫 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 字串，透過 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」資源參考資料中的「狀態」。

依標記篩選

如要依標記篩選，請使用 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}$")

如要查看預設替換值清單，請參閱「使用預設替換值」。

後續步驟