設定 HTTP 通知

Cloud Build 可以將通知傳送至所選管道 (例如 Slack 或 SMTP 伺服器)，以便通知您建構作業更新。本頁面說明如何使用 HTTP 通知器設定通知。

事前準備

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

  Enable the APIs

• 安裝 Google Cloud CLI。

設定 HTTP 通知

下一個章節將說明如何使用 HTTP 通知器手動設定 HTTP 通知，以便將 POST 要求傳送至指定的收件者網址。如果您想改為自動化設定，請參閱「自動化處理通知設定」。

如何設定 HTTP 通知：

如要使用 HTTP 通知器將 POST 要求傳送至指定的收件者網址，請按照下列步驟操作：

1. 授予 Cloud Run 服務帳戶讀取 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. 新增下列角色：

      • Storage 物件檢視者

   6. 按一下 [儲存]。

2. 撰寫通知器設定檔，設定 HTTP 通知器和建構事件篩選器：

   在以下通知器設定檔範例中，filter 欄位會使用 Common Expression Language 搭配可用的變數 build，藉此篩選具有 SUCCESS 狀態的建構事件：

   apiVersion: cloud-build-notifiers/v1
   kind: HTTPNotifier
   metadata:
     name: example-http-notifier
   spec:
     notification:
       filter: build.status == Build.Status.SUCCESS
       params:
         buildStatus: $(build.status)
       delivery:
         # The `http(s)://` protocol prefix is required.
         url: url
       template:
         type: golang
         uri: gs://bucket_name/http.json
   

   其中：

   • buildStatus 是使用者定義的參數。這個參數會採用 $(build.status) 的值，也就是建構作業的狀態。
   • url 是本例中用來指定要求網址的設定變數。
   • bucket-name 是值區的名稱。
   • url 是您要指定為收件伺服器的網址。

   • uri 欄位參照 http.json 檔案。此檔案是指代在 Cloud Storage 上代管的 JSON 範本，並代表 webhook 端點的 JSON 酬載。

     如需範本檔案的示例，請參閱 cloud-build-notifiers 存放區中的 http.json 檔案。

   如需範例，請參閱 HTTP 通知器的通知器設定檔。

   如要瞭解可用於篩選的其他欄位，請參閱「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 專案的通知。下次您叫用版本時，如果版本符合您設定的篩選器，位於指定網址的接收端 HTTP 伺服器將會收到與 Build 資源相符的 JSON 酬載。

使用 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}$")

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

後續步驟

• 瞭解 Cloud Build 通知程式。
• 瞭解如何訂閱版本通知。
• 瞭解如何撰寫 Cloud Build 建構設定檔。