Mengonfigurasi notifikasi BigQuery

Cloud Build dapat memberi tahu Anda tentang update build dengan mengirimkan notifikasi ke saluran tertentu, seperti Slack atau server SMTP Anda. Halaman ini menjelaskan cara mengonfigurasi notifikasi menggunakan notifikasi BigQuery.

Notifikasi BigQuery memungkinkan Anda menentukan filter untuk build yang ingin disimpan di database. Misalnya, Anda dapat mengelompokkan build menurut ID pemicu, tag, atau nilai substitusi. Notifikasi BigQuery juga menulis data ke BigQuery dalam format standar yang mencakup kolom komputasi yang tidak dapat langsung diakses di objek Build, seperti ukuran gambar atau durasi eksekusi. Jika Anda ingin mempelajari cara mengekspor entri log ke BigQuery atau tujuan lain, lihat Mengekspor log dengan Google Cloud konsol.

Sebelum memulai

  • Aktifkan Cloud Build, Cloud Run, Pub/Sub, dan BigQuery API.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

    Aktifkan API

Mengonfigurasi notifikasi BigQuery

Bagian berikut menjelaskan cara mengonfigurasi notifikasi HTTP secara manual menggunakan notifikasi BigQuery. Jika Anda ingin mengotomatiskan konfigurasi, lihat Mengotomatiskan konfigurasi untuk notifikasi.

Untuk mengonfigurasi notifikasi BigQuery:

  1. Beri akun layanan Cloud Run Anda izin untuk membuat dan menulis tabel BigQuery, izin untuk mengambil data Artifact Registry yang terkait dengan build Anda, serta akses baca dan tulis ke bucket Cloud Storage:

    1. Buka halaman IAM di Google Cloud konsol:

      Buka halaman IAM

    2. Temukan akun layanan default Compute Engine yang terkait dengan project Anda:

      Akun layanan default Compute Engine Anda akan terlihat mirip dengan berikut ini:

      project-number-compute@developer.gserviceaccount.com

    3. Klik ikon pensil di baris yang berisi akun layanan default Compute Engine Anda. Anda akan melihat tab Edit access.

    4. Klik Add another role.

    5. Tambahkan peran berikut:

      • Artifact Registry Reader
      • BigQuery Data Editor
      • Storage Object Viewer

      Peran Artifact Registry Reader memungkinkan Anda mengambil data untuk gambar. Peran BigQuery Data Editor memberi Anda akses baca dan tulis ke data Anda. Peran Storage Object Viewer memberi Anda akses baca ke objek Cloud Storage.

    6. Klik Simpan.

  2. Tulis file konfigurasi notifikasi untuk mengonfigurasi notifikasi BigQuery dan memfilter peristiwa build:

    Dalam contoh file konfigurasi notifikasi berikut, kolom filter menggunakan Common Expression Language dengan variabel, build, untuk memfilter peristiwa build dengan ID pemicu yang ditentukan:

    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

    Dengan:

    • buildStatus adalah parameter yang ditentukan pengguna. Parameter ini mengambil nilai ${build.status}, status build.
    • bucket-name adalah nama bucket Anda.
    • project-id adalah ID Google Cloud project Anda.
    • dataset-name adalah nama yang ingin Anda berikan ke set data Anda.
    • table-name adalah nama yang ingin Anda berikan ke tabel Anda.

    • Kolom uri mereferensikan file bq.json. File ini merujuk ke template JSON yang dihosting di Cloud Storage dan mewakili informasi yang akan dimasukkan ke dalam tabel BigQuery Anda.

    Untuk melihat contoh file template, lihat file bq.json di cloud-build-notifiers-repository.

    table-name di file konfigurasi notifikasi Anda dapat merujuk ke:

    • tabel yang tidak ada
    • tabel kosong tanpa skema

    • tabel yang ada dengan skema yang cocok dengan spesifikasi skema di notifikasi BigQuery

    Sebaiknya tentukan ID pemicu build sebagai filter Anda karena menentukan ID pemicu build memungkinkan Anda mengorelasikan data build untuk pemicu Anda. Anda juga dapat menentukan beberapa ID pemicu dalam daftar: build.build_trigger_id in ["example-id-123", "example-id-456"].

    Untuk mendapatkan ID pemicu, jalankan perintah berikut, dengan trigger-name adalah nama pemicu Anda:

    gcloud builds triggers describe trigger-name

    Perintah ini akan mencantumkan kolom yang terkait dengan pemicu Anda, termasuk ID pemicu Anda.

    Untuk melihat contohnya, lihat file konfigurasi notifikasi untuk notifikasi BigQuery.

    Untuk kolom tambahan yang dapat Anda gunakan untuk memfilter, lihat resource Build. Untuk contoh pemfilteran tambahan, lihat Menggunakan CEL untuk memfilter peristiwa build.

  3. Upload file konfigurasi notifikasi Anda ke bucket Cloud Storage:

    1. Jika Anda tidak memiliki bucket Cloud Storage, jalankan perintah berikut untuk membuat bucket, dengan bucket-name adalah nama yang Anda inginkan untuk bucket Anda, sesuai dengan persyaratan penamaan.

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

    2. Upload file konfigurasi notifikasi ke bucket Anda:

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

      Dengan:

      • bucket-name adalah nama bucket Anda.
      • config-file-name adalah nama file konfigurasi notifikasi Anda.

  4. Deploy notifikasi Anda ke 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

    Dengan:

    • service-name adalah nama layanan Cloud Run tempat Anda men-deploy image.
    • config-path adalah jalur ke file konfigurasi notifikasi untuk notifikasi BigQuery Anda, gs://bucket-name/config-file-name.
    • project-id adalah ID Google Cloud project Anda.

    Perintah gcloud run deploy mengambil versi terbaru image yang dihosting dari Artifact Registry milik Cloud Build. Cloud Build mendukung image notifikasi selama sembilan bulan. Setelah sembilan bulan, Cloud Build akan menghapus versi image. Jika ingin menggunakan versi image sebelumnya, Anda harus menentukan versi semantik lengkap tag image di atribut image perintah gcloud run deploy Anda. Versi dan tag image sebelumnya dapat ditemukan di Artifact Registry.

  5. Beri izin Pub/Sub untuk membuat token autentikasi di project Anda 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

    Dengan:

    • project-id adalah ID Google Cloud project Anda.
    • project-number adalah nomor project Anda Google Cloud .

  6. Buat akun layanan untuk merepresentasikan identitas langganan Pub/Sub Anda:

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

    Anda dapat menggunakan cloud-run-pubsub-invoker atau menggunakan nama yang unik dalam project Google Cloud Anda.

  7. Beri akun layanan cloud-run-pubsub-invoker izin Invoker Cloud Run:

    gcloud run services add-iam-policy-binding service-name \
   --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \
   --role=roles/run.invoker

    Dengan:

    • service-name adalah nama layanan Cloud Run tempat Anda men-deploy image.

    • project-id adalah ID Google Cloud project Anda.

  8. Buat topik cloud-builds untuk menerima pesan update build untuk notifikasi Anda:

    gcloud pubsub topics create cloud-builds

    Anda juga dapat menentukan nama topik kustom di file konfigurasi build sehingga pesan dikirim ke topik kustom. Dalam hal ini, Anda akan membuat topik dengan nama topik kustom yang sama:

    gcloud pubsub topics create topic-name

    Untuk mengetahui informasi selengkapnya, lihat topik Pub/Sub untuk notifikasi build.

  9. Buat pelanggan push Pub/Sub untuk notifikasi Anda:

     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

    Dengan:

    • subscriber-id adalah nama yang ingin Anda berikan ke langganan Anda.
    • service-url adalah URL yang dibuat Cloud Run untuk layanan baru Anda.
    • project-id adalah ID Google Cloud project Anda.

Notifikasi untuk project Cloud Build Anda kini telah disiapkan.

Saat Anda memanggil build berikutnya, tabel Anda akan diperbarui dengan data terbaru yang cocok dengan filter yang telah Anda konfigurasi untuk notifikasi BigQuery Anda.

Melihat data build

Untuk melihat data build Anda di BigQuery:

  1. Buka halaman konsol BigQuery:

    Buka halaman BigQuery

  2. Di bagian Resources, klik ID project yang Anda gunakan untuk mengonfigurasi notifikasi BigQuery Anda.

  3. Klik nama set data Anda.

  4. Klik nama tabel Anda.

Kini Anda dapat melihat informasi terkait tabel Anda, termasuk skemanya dan pratinjau data build Anda seperti yang tercantum dalam tabel.

Mengakses data build

Anda dapat membuat kueri data di tabel Anda menggunakan alat command line bq atau konsol BigQuery.

CLI

Untuk membuat kueri data di tabel Anda menggunakan alat command line bq, jalankan perintah berikut di terminal Anda dengan sql-query adalah kueri Anda:

bq query sql-query

Jika Anda berencana menggunakan contoh kueri di halaman ini, pastikan Anda menentukan --nouse_legacy_sql flag dalam perintah Anda. Alat command line bq menggunakan Legacy SQL, sedangkan contoh kueri tidak. Jalankan perintah berikut di terminal Anda untuk membuat kueri data tanpa Legacy SQL:

bq query sql-query --nouse_legacy_sql

Konsol

Untuk membuat kueri data di tabel Anda menggunakan konsol BigQuery:

  1. Buka halaman konsol BigQuery:

    Buka halaman BigQuery

  2. Di bagian Resources, klik nama tabel yang ingin Anda kueri.

  3. Tulis kueri SQL Anda di Query editor.

Menggunakan kueri untuk mengakses data build

Contoh kueri berikut menunjukkan cara mengakses data build untuk peristiwa build Anda, setelah konfigurasi notifikasi BigQuery:

Histori build keseluruhan

SELECT * FROM `projectID.datasetName.tableName`

Jumlah build yang dikelompokkan menurut status

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

Frekuensi deployment harian untuk minggu ini

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

Untuk melihat contoh kueri lainnya, lihat README Notifikasi BigQuery Cloud Build di repositori cloud-build-notifiers di GitHub. Untuk mempelajari lebih lanjut cara membuat kueri data menggunakan BigQuery, lihat Membuat kueri dan melihat data.

Menggunakan CEL untuk memfilter peristiwa build

Cloud Build menggunakan CEL dengan variabel, build, pada kolom yang tercantum dalam resource Build untuk mengakses kolom yang terkait dengan peristiwa build Anda seperti ID pemicu, daftar image, atau nilai substitusi. Anda dapat menggunakan filter string untuk memfilter peristiwa build di file konfigurasi build Anda menggunakan kolom apa pun yang tercantum dalam Build resource. Untuk menemukan sintaksis persis yang terkait dengan kolom Anda, lihat cloudbuild.proto file.

Memfilter menurut ID pemicu

Untuk memfilter menurut ID pemicu, tentukan nilai ID pemicu Anda di kolom filter menggunakan build.build_trigger_id, dengan trigger-id adalah ID pemicu Anda sebagai string:

filter: build.build_trigger_id == trigger-id

Memfilter menurut status

Untuk memfilter menurut status, tentukan status build yang ingin Anda filter di kolom filter menggunakan build.status.

Contoh berikut menunjukkan cara memfilter peristiwa build dengan status SUCCESS menggunakan kolom filter:

filter: build.status == Build.Status.SUCCESS

Anda juga dapat memfilter build dengan status yang berbeda-beda. Contoh berikut menunjukkan cara memfilter peristiwa build yang memiliki status SUCCESS, FAILURE, atau TIMEOUT menggunakan kolom filter:

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

Untuk melihat nilai status tambahan yang dapat Anda gunakan untuk memfilter, lihat Status di bagian referensi resource Build.

Memfilter menurut tag

Untuk memfilter menurut tag, tentukan nilai tag Anda di kolom filter menggunakan build.tags, dengan tag-name adalah nama tag Anda:

filter: tag-name in build.tags

Anda dapat memfilter berdasarkan jumlah tag yang ditentukan dalam peristiwa build Anda menggunakan size. Dalam contoh berikut, kolom filter memfilter peristiwa build yang memiliki tepat dua tag yang ditentukan dengan satu tag yang ditentukan sebagai v1:

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

Memfilter menurut gambar

Untuk memfilter menurut gambar, tentukan nilai gambar Anda di kolom filter menggunakan build.images, dengan image-name adalah nama lengkap gambar Anda seperti yang tercantum di Artifact Registry seperti us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

Dalam contoh berikut, filter memfilter peristiwa build yang memiliki us-east1-docker.pkg.dev/my-project/docker-repo/image-one atau us-east1-docker.pkg.dev/my-project/docker-repo/image-two yang ditentukan sebagai nama gambar:

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

Memfilter menurut waktu

Anda dapat memfilter peristiwa build berdasarkan waktu pembuatan, waktu mulai, atau waktu selesai build dengan menentukan salah satu opsi berikut di kolom filter Anda: build.create_time, build.start_time, atau build.finish_time.

Dalam contoh berikut, kolom filter menggunakan timestamp untuk memfilter peristiwa build dengan waktu permintaan untuk membuat build pada 20 Juli 2020 pukul 06.00:

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

Anda juga dapat memfilter peristiwa build berdasarkan perbandingan waktu. Dalam contoh berikut, kolom filter menggunakan timestamp untuk memfilter peristiwa build dengan waktu mulai antara 20 Juli 2020 pukul 06.00 dan 30 Juli 2020 pukul 06.00.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

Untuk mempelajari lebih lanjut cara zona waktu dinyatakan dalam CEL, lihat definisi bahasa untuk zona waktu.

Untuk memfilter menurut durasi build, Anda dapat menggunakan duration untuk membandingkan stempel waktu. Dalam contoh berikut, kolom filter menggunakan duration untuk memfilter peristiwa build dengan build yang berjalan selama minimal lima menit:

filter: build.finish_time - build.start_time >= duration("5m")

Memfilter menurut substitusi

Anda dapat memfilter menurut substitusi dengan menentukan variabel substitusi di kolom filter menggunakan build.substitutions. Dalam contoh berikut, kolom filter mencantumkan build yang berisi variabel substitusi substitution-variable dan memeriksa apakah substitution-variable cocok dengan substitution-value yang ditentukan:

filter: build.substitutions[substitution-variable] == substitution-value

Dengan:

  • substitution-variable adalah nama variabel substitusi Anda.
  • substitution-value adalah nama nilai substitusi Anda.

Anda juga dapat memfilter menurut nilai variabel substitusi default. Dalam contoh berikut, kolom filter mencantumkan build yang memiliki nama cabang master dan build yang memiliki nama repositori github.com/user/my-example-repo. Variabel substitusi default BRANCH_NAME dan REPO_NAME diteruskan sebagai kunci ke build.substitutions:

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

Jika Anda ingin memfilter string menggunakan ekspresi reguler, Anda dapat menggunakan fungsi matches bawaan. Dalam contoh di bawah, kolom filter memfilter build dengan status FAILURE atau TIMEOUT dan juga memiliki variabel substitusi build TAG_NAME dengan nilai yang cocok dengan ekspresi reguler 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}$")

Untuk melihat daftar nilai substitusi default, lihat Menggunakan substitusi default.

Langkah berikutnya