Merutekan peristiwa Cloud Firestore ke Alur Kerja

Pemicu Eventarc menyatakan minat Anda pada peristiwa atau rangkaian peristiwa tertentu. Anda dapat mengonfigurasi pemilihan rute peristiwa dengan menentukan filter untuk pemicu, termasuk sumber peristiwa, dan alur kerja target.

Peristiwa dikirim dalam format CloudEvents melalui permintaan HTTP. Layanan Alur kerja mengonversi peristiwa menjadi objek JSON (mengikuti spesifikasi CloudEvents) dan meneruskan peristiwa ke eksekusi alur kerja sebagai argumen runtime alur kerja. Pastikan ukuran peristiwa tidak melebihi 512 KB. Peristiwa yang lebih besar dari ukuran argumen Workflows maksimum tidak akan memicu eksekusi alur kerja.

Cloud Firestore mendukung Konteks Autentikasi sebagai atribut ekstensi ke format CloudEvents. Saat membuat pemicu, Anda dapat menerapkan atribut jenis peristiwa ini untuk memfilter peristiwa dengan informasi autentikasi.

Petunjuk ini menunjukkan cara mengonfigurasi pemilihan rute peristiwa sehingga eksekusi alur kerja Anda dipicu sebagai respons terhadap peristiwa Cloud Firestore langsung. Untuk mengetahui detail selengkapnya, lihat daftar peristiwa langsung yang didukung.

Bersiap untuk membuat pemicu

Sebelum membuat pemicu Eventarc untuk alur kerja target, selesaikan tugas berikut.

Konsol

  1. Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat Google Cloud project.

    Buka pemilih project

  2. Aktifkan Eventarc, Eventarc Publishing, Workflows, dan Workflow Executions API.

    Mengaktifkan API

  3. Jika berlaku, aktifkan API yang terkait dengan peristiwa langsung. Misalnya, untuk peristiwa Cloud Firestore , aktifkan APICloud Firestore .

  4. Jika Anda belum memilikinya, buat akun layanan yang dikelola pengguna, lalu berikan peran dan izin yang diperlukan agar Eventarc dapat mengelola peristiwa untuk alur kerja target.

    1. Di Konsol Google Cloud, buka halaman Akun layanan.

      Buka Akun Layanan

    2. Pilih project Anda.

    3. Di kolom Nama akun layanan, masukkan nama. Konsol Google Cloud akan mengisi kolom ID akun layanan berdasarkan nama ini.

      Di kolom Deskripsi akun layanan, masukkan sebuah deskripsi. Contoh, Service account for event trigger.

    4. Klik Buat dan lanjutkan.

    5. Untuk memberikan akses yang sesuai, di daftar Select a role, pilih peran Identity and Access Management (IAM) yang diperlukan untuk diberikan ke akun layanan Anda. Untuk mengetahui informasi selengkapnya, lihat Peran dan izin untuk target Alur Kerja.

      Untuk peran tambahan, klik Tambahkan peran lain, lalu tambahkan setiap peran tambahan.

    6. Klik Lanjutkan.

    7. Untuk menyelesaikan pembuatan akun, klik Selesai.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Aktifkan Eventarc, Eventarc Publishing, Workflows, dan Workflow Executions API:

    gcloud services enable eventarc.googleapis.com \
    eventarcpublishing.googleapis.com \
    workflows.googleapis.com \
    workflowexecutions.googleapis.com

  3. Jika berlaku, aktifkan API yang terkait dengan peristiwa langsung. Misalnya, untuk peristiwa Cloud Firestore , aktifkan firestore.googleapis.com.

  4. Jika Anda belum memilikinya, buat akun layanan yang dikelola pengguna, lalu berikan peran dan izin yang diperlukan agar Eventarc dapat mengelola peristiwa untuk alur kerja target.

    1. Buat akun layanan:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Ganti SERVICE_ACCOUNT_NAME dengan nama akun layanan. Panjangnya harus antara 6 dan 30 karakter, serta dapat berisi karakter alfanumerik huruf kecil dan tanda pisah. Setelah membuat akun layanan, Anda tidak dapat mengubah namanya.

    2. Berikan peran atau izin Identity and Access Management (IAM) yang diperlukan. Untuk mengetahui informasi selengkapnya, lihat Peran dan izin untuk target Alur Kerja.

Buat pemicu

Anda dapat membuat pemicu Eventarc dengan alur kerja yang di-deploy sebagai penerima peristiwa menggunakan Google Cloud CLI (gcloud atau Terraform), atau melalui konsol Google Cloud.

Konsol

  1. Di konsol Google Cloud, buka halaman Pemicu Eventarc.

    Buka Pemicu

  2. Klik Create trigger.
  3. Ketik Nama pemicu.

    Ini adalah ID pemicu dan harus diawali dengan huruf. Nama dapat berisi maksimal 63 huruf kecil, angka, atau tanda hubung.

  4. Untuk Jenis pemicu, pilih Sumber Google.
  5. Dalam daftar Penyedia peristiwa, pilih Cloud Firestore.

    Perhatikan bahwa nama penyedia peristiwa yang digunakan dalam dokumentasiGoogle Cloud terkait mungkin tidak memiliki awalan Cloud atau Google Cloud. Misalnya, di konsol, Memorystore for Redis disebut sebagai Google Cloud Memorystore for Redis.

  6. Di daftar Jenis peristiwa, dari peristiwa Langsung, pilih jenis peristiwa.
  7. Di daftar Jenis konten data peristiwa, pilih encoding payload peristiwa.

    Untuk peristiwa langsung dari Cloud Firestore, ini harus berupa application/protobuf dan data peristiwanya adalah array byte. Untuk informasi selengkapnya tentang pesan protobuf untuk peristiwa Cloud Firestore, lihat Peristiwa umum. Perhatikan bahwa Anda dapat menggunakan fungsi library standar Workflows untuk mengenkode byte ke teks Base64. Untuk informasi selengkapnya, lihat Menampilkan byte.

  8. Dalam daftar Region, pilih region yang sama dengan layananGoogle Cloud yang menghasilkan peristiwa.

    Untuk informasi selengkapnya, lihat Lokasi Eventarc.

  9. Jika berlaku untuk penyedia peristiwa, klik Tambahkan filter, lalu tentukan hal berikut:
    1. Di kolom Atribut 1, bergantung pada peristiwa langsung yang Anda pilih, pilih ID resource yang dapat berfungsi sebagai filter peristiwa.
    2. Pilih operator:
      • Sama dengan
      • Pola jalur: berlaku untuk resource document (mode Native) dan entity (mode Datastore). Gunakan karakter pengganti untuk merespons perubahan yang cocok dengan pola. Karakter pengganti * cocok dengan satu segmen dan karakter pengganti multi-segmen ** cocok dengan nol atau beberapa segmen dalam pola. Contoh:
        /users/* atau /users/{userId} Mencocokkan semua dokumen dalam koleksi /users. Tidak cocok dengan dokumen dalam subkoleksi seperti /users/marie/messages/33e2IxYBD9enzS50SJ68
        /users/** Mencocokkan semua dokumen dalam koleksi /users dan dokumen dalam subkoleksi seperti /users/marie/messages/33e2IxYBD9enzS50SJ68

        Untuk mengetahui informasi selengkapnya, lihat Memahami pola jalur.

    3. Di kolom Attribute value 1, bergantung pada operator yang Anda pilih, ketik nilai yang tepat atau terapkan pola jalur.
    4. Jika ada filter atribut lainnya yang berlaku, klik Tambahkan filter dan tentukan nilai yang sesuai.
  10. Pilih Service account yang akan memanggil layanan atau alur kerja Anda.

    Atau, Anda dapat membuat akun layanan baru.

    Ini menentukan email akun layanan Identity and Access Management (IAM) yang terkait dengan pemicu dan yang sebelumnya Anda berikan peran tertentu yang diperlukan oleh Eventarc.

  11. Dalam daftar Tujuan peristiwa, pilih Workflows.
  12. Pilih alur kerja.

    Ini adalah nama alur kerja yang akan menerima peristiwa. Peristiwa untuk eksekusi alur kerja diubah dan diteruskan ke alur kerja sebagai argumen runtime.

    Untuk mengetahui informasi selengkapnya, lihat Membuat pemicu untuk Alur Kerja.

  13. Secara opsional, untuk menambahkan label, Anda dapat mengklik Tambahkan label. Label adalah pasangan nilai kunci yang membantu Anda mengatur resourceGoogle Cloud . Untuk informasi selengkapnya, lihat Apa yang dimaksud dengan label?
  14. Klik Buat.

    15. Setelah pemicu dibuat, filter sumber peristiwa tidak dapat diubah. Sebagai gantinya, buat pemicu baru dan hapus pemicu lama. Untuk informasi selengkapnya, lihat Mengelola pemicu.

gcloud

Anda dapat membuat pemicu dengan menjalankan perintah gcloud eventarc triggers create bersama dengan flag wajib dan opsional.

Flag-nya berbeda-beda, bergantung pada apakah Anda menjalankan Firestore dalam mode Native atau dalam mode Datastore. Untuk mengetahui informasi selengkapnya, lihat Memilih antara mode Native dan mode Datastore.

Mode native

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-workflow=DESTINATION_WORKFLOW  \
    --destination-workflow-location=DESTINATION_WORKFLOW_LOCATION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="document=DOCUMENT" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account="MY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"

Mode Datastore

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-workflow=DESTINATION_WORKFLOW  \
    --destination-workflow-location=DESTINATION_WORKFLOW_LOCATION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="database=DATABASE" \
    --event-filters="namespace=NAMESPACE" \
    --event-filters-path-pattern="entity=ENTITY" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account="MY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"

Ganti kode berikut:

  • TRIGGER: ID pemicu atau ID yang memenuhi syarat sepenuhnya.

  • LOCATION: lokasi pemicu Eventarc. Atau, Anda dapat menetapkan properti eventarc/location; misalnya gcloud config set eventarc/location us-central1.

    Pemicu Cloud Firestore untuk Eventarc hanya tersedia di lokasi tertentu dan pemicu harus berada di lokasi yang sama dengan database Cloud Firestore. Untuk mengetahui informasi selengkapnya, lihat lokasi Eventarc dan lokasi Cloud Firestore.

  • DESTINATION_WORKFLOW: ID alur kerja yang di-deploy yang menerima peristiwa dari pemicu. Alur kerja dapat berada di salah satu lokasi Workflow yang didukung dan tidak perlu berada di lokasi yang sama dengan pemicu. Namun, alur kerja harus berada dalam project yang sama dengan pemicu.
  • DESTINATION_WORKFLOW_LOCATION (opsional): lokasi tempat alur kerja tujuan di-deploy. Jika tidak ditentukan, workflow dianggap berada di lokasi yang sama dengan pemicu.
  • EVENT_FILTER_TYPE: ID peristiwa. Peristiwa dibuat saat panggilan API untuk metode berhasil. Untuk operasi yang berjalan lama, peristiwa hanya dibuat di akhir operasi, dan hanya jika tindakan berhasil dilakukan. Untuk mengetahui daftar jenis peristiwa yang didukung, lihat Jenis peristiwa Google yang didukung oleh Eventarc.

    • Cloud Firestore mendukung jenis peristiwa berikut dalam mode Native saja.

    • google.cloud.firestore.document.v1.created: peristiwa dikirim saat dokumen ditulis untuk pertama kalinya
    • google.cloud.firestore.document.v1.created.withAuthContext: peristiwa dengan atribut informasi autentikasi dikirim saat dokumen ditulis untuk pertama kalinya
    • google.cloud.firestore.document.v1.updated: peristiwa dikirim saat dokumen sudah ada dan nilainya berubah
    • google.cloud.firestore.document.v1.updated.withAuthContext: peristiwa dengan atribut informasi autentikasi dikirim saat dokumen sudah ada dan nilainya berubah
    • google.cloud.firestore.document.v1.deleted: peristiwa dikirim saat dokumen dihapus
    • google.cloud.firestore.document.v1.deleted.withAuthContext: peristiwa dengan atribut informasi autentikasi dikirim saat dokumen dihapus
    • google.cloud.firestore.document.v1.written: peristiwa dikirim saat dokumen dibuat, diperbarui, atau dihapus
    • google.cloud.firestore.document.v1.written.withAuthContext: peristiwa dengan atribut informasi autentikasi dikirim saat dokumen dibuat, diperbarui, atau dihapus.

    Cloud Firestore mendukung jenis peristiwa berikut dalam mode Datastore saja. Objek data di Firestore dalam mode Datastore dikenal sebagai entity.

    • google.cloud.datastore.entity.v1.created: peristiwa dikirim saat entity ditulis untuk pertama kalinya
    • google.cloud.datastore.entity.v1.created.withAuthContext: peristiwa dengan atribut informasi autentikasi dikirim saat entitas ditulis untuk pertama kalinya
    • google.cloud.datastore.entity.v1.updated: peristiwa dikirim saat entitas sudah ada dan nilainya berubah
    • google.cloud.datastore.entity.v1.updated.withAuthContext: peristiwa dengan atribut informasi autentikasi dikirim saat entity sudah ada dan nilainya berubah
    • google.cloud.datastore.entity.v1.deleted: peristiwa dikirim saat entitas dihapus
    • google.cloud.datastore.entity.v1.deleted.withAuthContext: peristiwa dengan atribut informasi autentikasi dikirim saat entity dihapus
    • google.cloud.datastore.entity.v1.written: peristiwa dikirim saat entity dibuat, diperbarui, atau dihapus
    • google.cloud.datastore.entity.v1.written.withAuthContext: peristiwa dengan atribut informasi autentikasi dikirim saat entity dibuat, diperbarui, atau dihapus
  • DATABASE: database Firestore. Untuk nama database default, gunakan (default).
  • NAMESPACE (opsional): namespace database Firestore. Untuk namespace default dalam mode Datastore, gunakan (default). Jika tidak ditentukan, pencocokan karakter pengganti (*) ke kemunculan apa pun akan dilakukan.
  • DOCUMENT (opsional): berlaku untuk instance database yang berjalan dalam mode Native saja. Jalur database tempat Anda ingin menerima peristiwa saat data dibuat, diperbarui, atau dihapus di jalur tersebut. Operator dapat berupa salah satu dari berikut:
    • Sama; misalnya, --event-filters="document=DOCUMENT"
    • Pola jalur; misalnya, --event-filters-path-pattern="document=DOCUMENT".

      Gunakan karakter pengganti untuk merespons perubahan dalam dokumen yang cocok dengan pola. Karakter pengganti * cocok dengan satu segmen dan karakter pengganti multi-segmen ** cocok dengan nol atau beberapa segmen dalam pola. Contoh:

      /users/* atau /users/{userId} Mencocokkan semua dokumen dalam koleksi /users. Tidak cocok dengan dokumen dalam sub-koleksi seperti /users/marie/messages/33e2IxYBD9enzS50SJ68
      /users/** Mencocokkan semua dokumen dalam koleksi /users dan dokumen dalam subkoleksi seperti /users/marie/messages/33e2IxYBD9enzS50SJ68
      Untuk mengetahui informasi selengkapnya, lihat Memahami pola jalur.
  • ENTITY (opsional): berlaku untuk instance database yang berjalan dalam mode Datastore saja. Jalur database yang ingin Anda gunakan untuk menerima peristiwa saat data dibuat, diperbarui, atau dihapus di jalur tersebut. Operator dapat berupa salah satu dari berikut:
    • Sama; misalnya, --event-filters="document=ENTITY"
    • Pola jalur; misalnya, --event-filters-path-pattern="ENTITY=ENTITY"

      Untuk mengetahui informasi selengkapnya, lihat Memahami pola jalur.

      Perhatikan bahwa Anda mungkin perlu meng-escape karakter dalam ID jenis dan ID entity. Dengan meng-escape karakter, filter peristiwa dapat menafsirkan ID dengan benar. Untuk informasi selengkapnya, lihat Escaping karakter.

  • EVENT_DATA_CONTENT_TYPE: Encoding payload peristiwa. Untuk peristiwa langsung dari Firestore, parameter ini harus berupa application/protobuf dan data peristiwanya adalah array byte. Untuk mengetahui informasi selengkapnya tentang pesan protobuf untuk peristiwa Cloud Firestore, lihat Peristiwa umum. Perhatikan bahwa Anda dapat menggunakan fungsi library standar Workflows untuk mengenkode byte ke teks Base64. Untuk informasi selengkapnya, lihat Menampilkan byte.
  • SERVICE_ACCOUNT_NAME: nama akun layanan IAM yang Anda buat dan Anda berikan peran tertentu yang diperlukan oleh Alur Kerja.
  • PROJECT_ID: Google Cloud project ID Anda

Catatan:

  • Untuk peristiwa langsung dari Cloud Firestore, encoding payload peristiwa adalah application/protobuf.
  • Flag --event-filters="type=EVENT_FILTER_TYPE" wajib diisi. Jika tidak ada filter peristiwa lain yang ditetapkan, peristiwa untuk semua resource akan dicocokkan.
  • EVENT_FILTER_TYPE tidak dapat diubah setelah dibuat. Untuk mengubah EVENT_FILTER_TYPE, buat pemicu baru dan hapus pemicu lama.
  • Setiap pemicu dapat memiliki beberapa filter peristiwa, yang dipisahkan koma dalam satu flag --event-filters=[ATTRIBUTE=VALUE,...], atau Anda dapat mengulangi flag untuk menambahkan lebih banyak filter. Hanya peristiwa yang cocok dengan semua filter yang dikirim ke tujuan. Karakter pengganti dan ekspresi reguler tidak didukung. Namun, saat menggunakan flag --event-filters-path-pattern, Anda dapat menentukan pola jalur resource.
  • Flag --service-account digunakan untuk menentukan email akun layanan Identity and Access Management (IAM) yang terkait dengan pemicu.

Contoh:

gcloud eventarc triggers create helloworld-trigger \
    --location=us-east1 \
    --destination-workflow=my-workflow \
    --destination-workflow-location=us-east1 \
    --event-filters="type=google.cloud.firestore.document.v1.updated" \
    --event-filters="database=my-database" \
    --event-filters-path-pattern="document=users/my-document-*" \
    --event-data-content-type="application/protobuf" \
    --service-account="${TRIGGER_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

Perintah ini membuat pemicu yang disebut helloworld-trigger untuk peristiwa yang diidentifikasi sebagai google.cloud.firestore.document.v1.updated di instance database my-database yang berjalan dalam mode Native, dan memfilter peristiwa untuk jalur document yang cocok dengan users/my-document-.

Terraform

Anda dapat membuat pemicu untuk alur kerja menggunakan Terraform. Untuk mengetahui detailnya, lihat Memicu alur kerja menggunakan Eventarc dan Terraform.

Mencantumkan pemicu

Anda dapat mengonfirmasi pembuatan pemicu dengan mencantumkan pemicu Eventarc menggunakan Google Cloud CLI atau melalui konsol Google Cloud.

Konsol

  1. Di konsol Google Cloud, buka halaman Pemicu Eventarc.

    Buka Pemicu

    Halaman ini mencantumkan pemicu Anda di semua lokasi, dan menyertakan detail seperti nama, wilayah, penyedia peristiwa, tujuan, dan lainnya.

  2. Untuk memfilter pemicu:

    1. Klik Filter atau kolom Filter triggers.
    2. Di daftar Properti, pilih opsi untuk memfilter pemicu.

    Anda dapat memilih satu properti atau menggunakan operator logika OR untuk menambahkan properti lainnya.

  3. Untuk mengurutkan pemicu, di samping judul kolom yang didukung, klik Urutkan.

gcloud

Jalankan perintah berikut untuk membuat daftar pemicu:

gcloud eventarc triggers list --location=-

Perintah ini mencantumkan pemicu Anda di semua lokasi, dan menyertakan detail seperti nama, jenis, tujuan, dan status.

Langkah berikutnya