BigQuery の通知を構成する

Cloud Build は、Slack や SMTP サーバーなどの選択したチャネルに通知を送信することで、ビルド更新を通知します。このページでは、BigQuery Notifier を使用して通知を構成する方法について説明します。

BigQuery Notifier は、データベースに格納するビルドのフィルタを指定する機能を提供します。たとえば、トリガー ID、タグ、または置換値でビルドをグループ化できます。また、BigQuery Notifier は、画像サイズや実行時間など、Build オブジェクトにすぐにアクセスできない計算済みフィールドを含む標準化された形式で、BigQuery にデータを書き込みます。ログエントリを BigQuery または別のエクスポート先にエクスポートする方法については、Google Cloud Console を使用したログのエクスポートをご覧ください。

準備

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

    Enable the APIs

BigQuery 通知を構成する

次のセクションでは、BigQuery Notifier を使用して 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. [別の役割を追加] をクリックします。

    5. 次のロールを追加します。

      • Artifact Registry 読み取り
      • BigQuery データ編集者
      • ストレージ オブジェクト閲覧者

      Artifact Registry 読み取りロールを使用すると、イメージのデータを取得できます。BigQuery データ編集者は、データへの読み取り / 書き込みアクセス権を付与します。 ストレージ オブジェクト閲覧者は、Cloud Storage オブジェクトに対する読み取りアクセス権を付与します。

    6. [保存] をクリックします。

  2. Notifier 構成ファイルを作成し、ビルドイベントに BigQuery Notifier とフィルタを構成します。

    次の Notifier 構成ファイルの例では、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://example-gcs-bucket/bq.json

    ここで

    • buildStatus は、ユーザー定義のパラメータです。このパラメータは、${build.status} の値、ビルドのステータスです。
    • project-id は、Google Cloud プロジェクトの ID です。
    • dataset-name は、データセットに付ける名前です。
    • table-name は、テーブルに付ける名前です。

    • uri フィールドは bq.json ファイルを参照します。このファイルは Cloud Storage でホストされる JSON テンプレートを参照し、BigQuery テーブルに挿入する情報を表します。

    テンプレート ファイルの例を表示するには、cloud-build-notifiers リポジトリの bq.json ファイルをご覧ください。

    Notifier 構成ファイルの table-name は、以下を参照できます。

    • 存在しないテーブル
    • スキーマを含まない空のテーブル

    • BigQuery Notifier のスキーマ仕様に一致するスキーマを持つ既存のテーブル

    ビルドトリガー ID を指定することでトリガーのビルドデータを関連付けることができるため、ビルドトリガー ID をフィルタとして指定することをおすすめします。リストに複数のトリガー ID を指定することもできます。build.build_trigger_id in ["example-id-123", "example-id-456"]。

    トリガー ID を取得するには、次のコマンドを実行します。ここで、trigger-name はトリガーの名前です。

    gcloud builds triggers は trigger-name を記述します

    このコマンドを実行すると、トリガー ID を含む、トリガーに関連付けられたフィールドが一覧表示されます。

    サンプルを確認するには、BigQuery Notifier の Notifier 構成ファイルをご覧ください。

    フィルタに使用できるその他のフィールドについては、ビルドリソースをご覧ください。フィルタリングに関するその他の例については、CEL を使用してビルドイベントをフィルタリングするをご覧ください。

  3. 通知機能構成ファイルを Cloud Storage バケットにアップロードします。

    1. Cloud Storage バケットがない場合は、次のコマンドを実行してバケットを作成します。ここで、bucket-name は命名要件に従って、バケットに付ける名前です。

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

    2. Notifier 構成ファイルをバケットにアップロードします。

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

      ここで

      • bucket-name はバケットの名前です。
      • config-file-name は、Notifier の構成ファイルの名前です。

  4. Notifier を 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 Notifier gs://bucket-name/config-file-name の構成ファイルへのパスです。

    • project-id は、Google Cloud プロジェクトの ID です。

    gcloud run deploy コマンドは、Artifact Registry からビルドされたイメージの最新バージョンを pull します。Cloud Build は 9 か月間、Notifier イメージをサポートします。9 か月を過ぎると、イメージのバージョンは削除されます。以前のイメージ バージョンを使用する場合は、gcloud run deploy コマンドの image 属性でイメージタグの完全なセマンティック バージョンを指定する必要があります。以前のイメージ バージョンとタグは、Artifact Registry にあります。

  5. プロジェクトに認証トークンを作成する Pub/Sub 権限を付与します。

     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 サブスクリプション ID を表すサービス アカウントを作成します。

    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-pubsub-invoker サービスアカウントに Cloud Run 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 トピックを作成して、Notifier のビルド更新メッセージを受信します。

    gcloud pubsub topics create cloud-builds

  9. Notifier に Pub/Sub push サブスクライバーを作成します。

     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 によって生成された、新しいサービスの URL です。
    • project-id は、Google Cloud プロジェクトの ID です。

これで Cloud Build プロジェクトの通知が設定されました。

次回ビルドを呼び出すと、BigQuery Notifier に構成したフィルタと一致する最新のデータでテーブルが更新されます。

ビルドデータの表示

BigQuery でビルドデータを表示する手順は、次のとおりです。

  1. [BigQuery] コンソール ページを開きます。

    [BigQuery] ページを開く

  2. [リソース] で、BigQuery Notifier の構成に使用するプロジェクト 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. [クエリエディタ] で SQL クエリを作成します。

クエリを使用してビルドデータにアクセスする

次のサンプルクエリは、BigQuery Notifier の構成に従って、ビルドイベントのビルドデータにアクセスする方法を示します。

全般的なビルド履歴

SELECT * FROM `projectID.datasetName.tableName`

ステータス別にグループ化されたビルド数

SELECT STATUS, COUNT(*)
FROM `projectID.datasetName.tableName`
GROUP BY STATUS

今週の 1 日あたりのデプロイの頻度

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 を使用して、トリガー ID、イメージリスト、置換変数などのビルドイベントと関連するフィールドにアクセスします。filter 文字列を使用すると、Build リソースに表示されているフィールドを使用してビルド構成ファイル内のビルドイベントをフィルタリングできます。フィールドに関連付けられた正確な構文を見つけるには、cloudbuild.proto ファイルをご覧ください。

トリガー ID によるフィルタリング

トリガー ID でフィルタリングするには、build.build_trigger_id を使用してトリガー ID の値をfilter フィールドに指定します。ここで、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 フィールドにより、1 つのタグが v1 に指定されたタグがちょうど 2 つあるビルドイベントがフィルタリングされます。

filter: size(build.tags) == 2 && "v1" in build.tags

イメージによるフィルタリング

イメージでフィルタリングするには、build.images を使用して filter フィールドにイメージの値を指定します。ここで image-name は、us-east1-docker.pkg.dev/my-project/docker-repo/image-one などの Artifact Registry に表示されるイメージの完全な名前です。

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 を使用して、ビルドが 5 分以上実行されるビルドイベントをフィルタリングします。

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 であり、正規表現 v{DIGIT}.{DIGIT}.{3 DIGITS}) と一致する値を持つビルド置換変数 TAG_NAME のあるビルドでフィルタリングします。

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")`

デフォルトの置換値のリストについては、デフォルトの置換の使用をご覧ください。

次のステップ