Mengonfigurasi notifikasi BigQuery

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

Pemberi tahu BigQuery menyediakan fungsi bagi Anda untuk menentukan filter pada build mana yang ingin disimpan di database. Misalnya, Anda dapat mengelompokkan build berdasarkan ID pemicu, tag, atau nilai substitusi. Pemberi tahu BigQuery juga menulis data ke BigQuery dalam format standar yang mencakup kolom terkomputasi yang tidak langsung dapat diakses di objek Build, seperti ukuran gambar atau durasi eksekusi. Jika Anda ingin mempelajari cara mengekspor entri log ke BigQuery atau tujuan lainnya, lihat Mengekspor log dengan konsol Google Cloud.

Sebelum memulai

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

Instal Google Cloud CLI.

Mengonfigurasi notifikasi BigQuery

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

Untuk mengonfigurasi notifikasi BigQuery:

Berikan izin pada akun layanan Cloud Run Anda 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 konsol Google Cloud:
  
  Buka halaman IAM
2. Temukan akun layanan default Compute Engine yang terkait dengan project Anda:
  
  Akun layanan default Compute Engine Anda akan terlihat seperti berikut:
```
project-number-compute@developer.gserviceaccount.com
```
3. Klik ikon pensil di baris yang berisi akun layanan default Compute Engine Anda. Anda akan melihat tab Akses edit.
4. Klik Add another role.
5. Tambahkan peran berikut:
  - Pembaca Artifact Registry
  - BigQuery Data Editor
  - Storage Object Viewer
  Peran Artifact Registry Reader memungkinkan Anda mengambil data untuk image. BigQuery Data Editor memberi Anda akses baca dan tulis ke data Anda. Storage Object Viewer memberi Anda akses baca ke objek Cloud Storage.
  
  Catatan: Jika Anda ingin memberikan izin di level bucket, bukan level project, tambahkan peran Storage Legacy Object Owner ke bucket saat Anda membuatnya. Untuk mempelajari lebih lanjut, lihat Peran tingkat project vs. peran tingkat bucket.
6. Klik Simpan.
Tulis file konfigurasi notifier untuk mengonfigurasi notifier BigQuery dan filter pada peristiwa build:

Pada contoh file konfigurasi notifikasi berikut, kolom filter menggunakan Common Expression Language dengan variabel, build, untuk memfilter peristiwa build dengan ID pemicu yang ditetapkan:
```
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
```
Dengan keterangan:
- buildStatus adalah parameter yang ditentukan pengguna. Parameter ini menggunakan nilai ${build.status}, status build.
- project-id adalah ID project Google Cloud Anda.
- dataset-name adalah nama yang ingin Anda berikan untuk set data.
- table-name adalah nama yang ingin Anda berikan pada tabel.
- Kolom uri merujuk ke file bq.json. File ini merujuk ke template JSON yang dihosting di Cloud Storage dan mewakili informasi yang akan disisipkan ke tabel bigquery Anda.
  
  Eksperimental — Customizing notifications using templates
  
  Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dalam Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.
Untuk melihat contoh file template, lihat file bq.json di repositori cloud-build-notifiers-repositori.

table-name dalam 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 pemberitahuan BigQuery
  
  Catatan: Referensi ke tabel yang sudah ada dengan spesifikasi skema yang tidak cocok dengan notifier BigQuery akan menghasilkan error.
Sebaiknya tetapkan ID pemicu build sebagai filter karena dengan menentukan ID pemicu build, Anda dapat menghubungkan data build untuk pemicu. 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:

Pemicu build gcloud mendeskripsikan trigger-name

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

Catatan: Data hanya disimpan untuk peristiwa build dengan status terminal seperti SUCCESS atau FAILURE.

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

Untuk kolom tambahan yang dapat digunakan untuk memfilter, lihat resource Build. Untuk mengetahui contoh pemfilteran tambahan, lihat Menggunakan CEL untuk memfilter peristiwa build.
Upload file konfigurasi notifier ke bucket Cloud Storage:
1. Jika Anda tidak memiliki bucket Cloud Storage, jalankan perintah berikut untuk membuat bucket, dengan bucket-name sebagai nama yang ingin Anda berikan untuk bucket, sesuai dengan persyaratan penamaan.
```
gsutil mb gs://bucket-name/
```
2. Upload file konfigurasi notifier ke bucket Anda:
```
gsutil cp config-file-name gs://bucket-name/config-file-name
```
  Dengan keterangan:
  - bucket-name adalah nama bucket Anda.
  - config-file-name adalah nama file konfigurasi notifikasi Anda.
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 keterangan:
- service-name adalah nama layanan Cloud Run tempat Anda men-deploy image.
  
  Catatan: service-name mereferensikan layanan notifikasi baru yang Anda buat.
- config-path adalah jalur ke file konfigurasi untuk notifikasi BigQuery Anda, gs://bucket-name/config-file-name.
- project-id adalah ID project Google Cloud Anda.
Perintah gcloud run deploy mengambil versi terbaru image build Anda dari Artifact Registry. 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 gambar dalam atribut image perintah gcloud run deploy. Versi dan tag image sebelumnya dapat ditemukan di Artifact Registry.

Catatan: Saat menjalankan perintah ini, Anda mungkin diminta untuk menentukan argumen tambahan seperti --region atau --platform. Untuk mempelajari lebih lanjut parameter yang dapat Anda teruskan ke perintah gcloud run deploy, lihat Men-deploy ke Cloud Run. Jika Anda tidak dapat men-deploy notifikasi menggunakan perintah ini, lihat panduan pemecahan masalah Cloud Run untuk mendapatkan solusi tentang cara mengatasi error deployment.
Beri izin Pub/Sub untuk membuat token autentikasi di project Anda:
```
 gcloud projects add-iam-policy-binding project-id \
   --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
   --role=roles/iam.serviceAccountTokenCreator
```
Dengan keterangan:
- project-id adalah ID project Google Cloud Anda.
- project-number adalah nomor project Google Cloud Anda.
Catatan: Jika akun layanan Pub/Sub tidak ada di project Anda, lihat Membuat dan menggunakan langganan.
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.
Berikan izin Invoker Cloud Run untuk akun layanan 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
```
Dengan keterangan:
- service-name adalah nama layanan Cloud Run tempat Anda men-deploy image.
- project-id adalah ID project Google Cloud Anda.
Buat topik cloud-builds untuk menerima pesan update build untuk notifier Anda:
```
gcloud pubsub topics create cloud-builds
```
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 keterangan:
- subscriber-id adalah nama yang ingin diberikan untuk langganan Anda.
- service-url adalah URL yang dihasilkan Cloud Run untuk layanan baru Anda.
- project-id adalah ID project Google Cloud Anda.

Notifikasi untuk project Cloud Build Anda sudah disiapkan.

Pada saat berikutnya Anda memanggil build, tabel Anda akan diperbarui dengan data terbaru yang cocok dengan filter yang telah dikonfigurasi untuk pemberitahuan BigQuery.

Melihat data build

Untuk melihat data build di BigQuery:

Buka halaman konsol BigQuery:

Buka halaman BigQuery
Di bagian Resources, klik project ID yang Anda gunakan untuk mengonfigurasi notifier BigQuery Anda.
Klik nama {i>dataset<i} Anda.
Klik nama tabel Anda.

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

Mengakses data build

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

CLI

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

bq query sql-query

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

bq query sql-query --nouse_legacy_sql

Konsol

Untuk membuat kueri data di tabel Anda menggunakan konsol BigQuery:

Buka halaman konsol BigQuery:

Buka halaman BigQuery
Di bawah Resource, klik nama tabel yang ingin Anda kueri.
Tulis kueri SQL Anda di Editor kueri.

Menggunakan kueri untuk mengakses data build

Contoh kueri berikut menunjukkan cara mengakses data build untuk peristiwa build, sesuai dengan konfigurasi notifier BigQuery:

Histori build secara 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, baca 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 gambar, atau nilai substitusi. Anda dapat menggunakan string filter untuk memfilter peristiwa build dalam file konfigurasi build menggunakan kolom yang tercantum dalam resource Build. Untuk menemukan sintaksis yang terkait dengan kolom Anda, lihat file cloudbuild.proto.

Pemfilteran menurut ID pemicu

Untuk memfilter menurut ID pemicu, tentukan nilai ID pemicu 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 berdasarkan 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 beragam status. 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 difilter, baca bagian 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 sebagai nama tag Anda:

filter: tag-name in build.tags

Anda dapat memfilter berdasarkan jumlah tag yang ditentukan dalam peristiwa build menggunakan size. Pada contoh berikut, kolom filter memfilter peristiwa membuat peristiwa 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 berdasarkan image, tentukan nilai image Anda di kolom filter menggunakan build.images. image-name adalah nama lengkap image Anda seperti yang tercantum dalam Artifact Registry, seperti us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

Pada 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: build.create_time, build.start_time, atau build.finish_time.

Pada 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. Pada 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. Pada contoh berikut, kolom filter menggunakan duration untuk memfilter peristiwa build dengan build yang berjalan setidaknya selama lima menit:

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

Pemfilteran berdasarkan substitusi

Anda dapat memfilter berdasarkan 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 keterangan:

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 ingin memfilter string menggunakan ekspresi reguler, Anda dapat menggunakan fungsi matches bawaan. Pada contoh di bawah, kolom filter memfilter build dengan status FAILURE atau TIMEOUT dan yang 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 selanjutnya

Pelajari pemberi tahu Cloud Build.
Pelajari cara berlangganan untuk membuat notifikasi.
Pelajari cara menulis file konfigurasi build Cloud Build.