Memublikasikan dan menerima peristiwa dengan membuat bus dan pendaftaran (gcloud CLI)

Memublikasikan dan menerima peristiwa dengan membuat bus dan pendaftaran (gcloud CLI)

Lanjutan

Panduan memulai ini menunjukkan cara memublikasikan dan menerima pesan peristiwa dengan membuat bus Eventarc Advanced dan pendaftaran di project Google CloudAnda.

• Bus bertindak sebagai router pusat, yang menerima pesan dari sumber peristiwa atau dipublikasikan oleh penyedia.

• Pendaftaran merutekan pesan yang diterima oleh bus ke satu atau beberapa tujuan melalui pipeline pemrosesan.

Dalam panduan memulai ini, Anda akan:

1. Buat repositori standar Artifact Registry.

2. Men-deploy layanan penerima peristiwa ke Cloud Run.

3. Buat bus Lanjutan Eventarc.

4. Buat pendaftaran Lanjutan Eventarc.

5. Memublikasikan pesan peristiwa ke bus.

6. Lihat data peristiwa di log Cloud Run.

Anda dapat menyelesaikan panduan memulai ini menggunakan gcloud CLI. Untuk menyelesaikan langkah-langkah menggunakan konsol Google Cloud , lihat Memublikasikan dan menerima peristiwa dengan membuat bus dan pendaftaran (konsol).

Sebelum memulai

Batasan keamanan yang ditentukan oleh organisasi mungkin mencegah Anda menyelesaikan langkah-langkah berikut. Untuk mengetahui informasi pemecahan masalah, lihat Mengembangkan aplikasi di lingkungan Google Cloud yang terbatas.

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika Anda tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan Artifact Registry, Cloud Build, Cloud Run, Compute Engine, dan Eventarc API:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika Anda tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan Artifact Registry, Cloud Build, Cloud Run, Compute Engine, dan Eventarc API:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com

1. Perbarui komponen gcloud:

   gcloud components update

2. Login menggunakan akun Anda:

   gcloud auth login

3. Tetapkan variabel konfigurasi yang digunakan dalam panduan memulai ini:

   REGION=REGION

   Ganti REGION dengan lokasi yang didukung untuk bus.

4. Jika Anda adalah project creator, Anda diberi peran Pemilik dasar (roles/owner). Secara default, peran Identity and Access Management (IAM) ini mencakup izin yang diperlukan untuk akses penuh ke sebagian besar resource Google Cloud dan Anda dapat melewati langkah ini.

   Jika Anda bukan project creator, izin yang diperlukan harus diberikan pada project kepada akun utama yang sesuai. Misalnya, akun utama dapat berupa Akun Google (untuk pengguna akhir) atau akun layanan (untuk aplikasi dan workload komputasi).

   Perhatikan bahwa secara default, izin Cloud Build mencakup izin untuk mengupload dan mendownload artefak Artifact Registry.

   Izin yang diperlukan

   Untuk mendapatkan izin yang Anda perlukan untuk menyelesaikan panduan memulai cepat ini, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

   • Editor Cloud Build (roles/cloudbuild.builds.editor)
   • Admin Cloud Run (roles/run.admin)
   • Eventarc Developer (roles/eventarc.developer)
   • Eventarc Message Bus Admin (roles/eventarc.messageBusAdmin)
   • Logs View Accessor (roles/logging.viewAccessor)
   • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
   • Service Account Admin (roles/iam.serviceAccountAdmin)
   • Service Account User (roles/iam.serviceAccountUser)
   • Service Usage Admin (roles/serviceusage.serviceUsageAdmin)

   Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

   Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

5. Untuk tujuan pengujian, buat akun layanan, dan berikan peran yang diperlukan untuk menyelesaikan panduan memulai ini.
   1. Membuat akun layanan:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Ganti SERVICE_ACCOUNT_NAME dengan nama untuk akun layanan Anda.
   2. Berikan peran yang diperlukan untuk mem-build dan men-deploy image container, serta untuk merepresentasikan identitas pipeline Lanjutan Eventarc:
      • Penulis Artifact Registry: untuk mengupload artefak Artifact Registry
      • Logs Writer: untuk menulis log ke Cloud Logging
      • Admin Penyimpanan: untuk mengakses objek Cloud Storage
      • Cloud Run Invoker: untuk memanggil Cloud Run

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/artifactregistry.writer
      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/logging.logWriter
      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/storage.admin
      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/run.invoker

   Perhatikan bahwa Anda dapat mengonfigurasi siapa saja yang dapat mengakses layanan Cloud Run Anda dengan salah satu cara berikut:

   • Berikan izin untuk memilih akun atau grup layanan yang akan mengizinkan akses ke layanan tersebut. Semua permintaan harus memiliki header Otorisasi HTTP yang berisi token OpenID Connect yang ditandatangani oleh Google untuk salah satu akun layanan yang diberi otorisasi. Dengan cara ini, akses dikonfigurasi dalam panduan memulai ini.
   • Berikan izin kepada allUsers untuk mengizinkan akses tanpa autentikasi.

   Untuk mengetahui informasi selengkapnya, lihat Kontrol akses untuk Cloud Run.

Membuat repositori standar Artifact Registry

Buat repositori standar Artifact Registry untuk menyimpan image container Anda.

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

Ganti REPOSITORY dengan nama unik untuk repositori Artifact Registry—misalnya, my-repo.

Men-deploy layanan penerima peristiwa ke Cloud Run

Deploy layanan Cloud Run yang mencatat konten peristiwa. Tujuan peristiwa lainnya didukung seperti topik Pub/Sub, Workflows, atau endpoint HTTP. Untuk mengetahui informasi selengkapnya, lihat Penyedia dan tujuan peristiwa.

1. Buat clone repositori GitHub:

   git clone https://github.com/GoogleCloudPlatform/eventarc-samples.git

2. Ubah ke direktori yang memuat kode contoh Cloud Run:

   cd eventarc-samples/eventarc-advanced-quickstart/

3. Bangun image container Docker dan kirim image ke repositori Anda:

   gcloud builds submit \
       --tag $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
       --service-account=projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --default-buckets-behavior=regional-user-owned-bucket

4. Men-deploy image container ke Cloud Run

   gcloud run deploy SERVICE_NAME \
       --image $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
       --platform managed \
       --ingress all \
       --no-allow-unauthenticated \
       --region=$REGION

   Ganti SERVICE_NAME dengan nama layanan Anda—misalnya, my-service.

   Setelan ingress all mengizinkan semua permintaan, termasuk permintaan langsung dari internet ke URL run.app. Untuk mengetahui informasi selengkapnya, lihat Membatasi traffic masuk jaringan untuk Cloud Run.

   Flag --no-allow-unauthenticated mengonfigurasi layanan agar hanya mengizinkan pemanggilan terautentikasi.

Jika Anda melihat URL layanan Cloud Run, berarti deployment telah selesai. Catat URL ini agar Anda dapat menggunakannya pada langkah berikutnya.

Membuat bus Eventarc Advanced

Bus menerima pesan peristiwa dari sumber pesan atau yang dipublikasikan oleh penyedia dan bertindak sebagai router pesan.

Untuk mengetahui informasi selengkapnya, lihat Membuat bus untuk merutekan pesan.

Catatan: Anda dapat membuat satu bus per Google Cloud project per region yang didukung.

Buat bus Eventarc Advanced di project Anda menggunakan perintah gcloud eventarc message-buses create:

gcloud eventarc message-buses create BUS_NAME \
    --location=$REGION

Ganti BUS_NAME dengan ID atau ID yang sepenuhnya memenuhi syarat dari bus Anda—misalnya, my-bus.

Membuat pendaftaran Lanjutan Eventarc

Pendaftaran menentukan pesan mana yang dirutekan ke tujuan dan juga menentukan pipeline yang digunakan untuk mengonfigurasi tujuan bagi pesan peristiwa.

Untuk mengetahui informasi selengkapnya, lihat Membuat pendaftaran untuk menerima peristiwa.

Catatan: Pembuatan pipeline mungkin memerlukan waktu lebih dari 10 menit.

Saat menggunakan gcloud CLI, Anda akan membuat pipeline terlebih dahulu, lalu membuat pendaftaran:

1. Buat pipeline menggunakan perintah gcloud eventarc pipelines create:

   gcloud eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='CLOUD_RUN_SERVICE_URL',google_oidc_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --location=$REGION

   Ganti kode berikut:

   • PIPELINE_NAME: ID pipeline atau nama yang sepenuhnya memenuhi syarat.
   • CLOUD_RUN_SERVICE_URL: URL yang sepenuhnya memenuhi syarat dari layanan Cloud Run Anda—misalnya, https://SERVICE_NAME-abcdef-uc.a.run.app. Ini adalah tujuan untuk pesan acara Anda.

   Perhatikan bahwa kunci google_oidc_authentication_service_account menentukan email akun layanan yang digunakan untuk membuat token OIDC.

2. Buat pendaftaran menggunakan perintah gcloud eventarc enrollments create:

   gcloud eventarc enrollments create ENROLLMENT_NAME \
       --cel-match=MATCH_EXPRESSION \
       --destination-pipeline=PIPELINE_NAME \
       --message-bus=BUS_NAME \
       --message-bus-project=PROJECT_ID \
       --location=$REGION

   Ganti kode berikut:

   • ENROLLMENT_NAME: ID pendaftaran atau nama yang memenuhi syarat sepenuhnya.

   • MATCH_EXPRESSION: ekspresi pencocokan untuk pendaftaran ini menggunakan CEL—misalnya:

     "message.type == 'hello-world-type'"
     

Memublikasikan pesan acara ke bus

Untuk memublikasikan pesan langsung ke bus, Anda dapat menggunakan perintah gcloud eventarc message-buses publish atau mengirim permintaan ke Eventarc Publishing REST API. Untuk mengetahui informasi selengkapnya, lihat Memublikasikan peristiwa secara langsung.

Pesan harus dalam format CloudEvents, yaitu spesifikasi untuk mendeskripsikan data peristiwa dengan cara yang umum. Elemen data adalah payload peristiwa Anda. JSON yang disusun dengan baik dapat dimasukkan ke dalam kolom ini. Untuk mengetahui informasi selengkapnya tentang atribut konteks CloudEvents, lihat Format peristiwa.

Berikut adalah contoh memublikasikan peristiwa secara langsung ke bus Eventarc Advanced:

Contoh 1

Anda dapat memublikasikan peristiwa ke bus menggunakan gcloud CLI dan --event-data serta flag atribut peristiwa lainnya:

gcloud eventarc message-buses publish BUS_NAME \
    --event-data='{"key": "hello-world-data"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

Contoh 2

Anda dapat memublikasikan peristiwa ke bus sebagai pesan JSON menggunakan gcloud CLI dan flag --json-message:

gcloud eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"key": "hello-world-data"}}'

Setelah memublikasikan acara, Anda akan menerima pesan "Acara berhasil dipublikasikan".

Melihat data peristiwa di log Cloud Run

Setelah memublikasikan peristiwa ke bus Eventarc Advanced, Anda dapat memeriksa log layanan Cloud Run untuk memverifikasi bahwa peristiwa diterima seperti yang diharapkan.

1. Filter entri log dan tampilkan output menggunakan perintah gcloud logging read:

   gcloud logging read 'textPayload: "hello-world-data"'
   

2. Cari entri log yang mirip dengan berikut ini:

   insertId: 670808e70002b5c6477709ae
   labels:
   instanceId: 007989f2a10a4a33c21024f2c8e06a9de65d9b4fdc2ee27697a50379b3fab2f975b9233dc357d50b06270829b9b479d5a1ee54a10fa2cb2d98c5f77a0895e2be0f9e6e4b20
   logName: projects/PROJECT_ID/logs/run.googleapis.com%2Fstderr
   receiveTimestamp: '2024-10-10T17:03:35.424659450Z'
   resource:
   labels:
   ...
   type: cloud_run_revision
   textPayload: "[2024-10-21 15:33:19,581] INFO in server: Body: b'{\"value\":\"hello-world-data\"\
     }'"
   timestamp: '2024-10-10T17:03:35.177606Z'
   

   Catatan: Jika Anda tidak melihat entri log, tunggu beberapa menit dan coba perintah gcloud logging read lagi.

Anda telah berhasil membuat bus dan pendaftaran Eventarc Advanced, memublikasikan pesan peristiwa ke bus, dan memverifikasi hasil yang diharapkan dalam log layanan penerima peristiwa.

Pembersihan

Setelah menyelesaikan tugas yang dijelaskan dalam panduan memulai ini, Anda dapat menghindari penagihan berkelanjutan dengan menghapus resource yang Anda buat:

1. Hapus repositori Artifact Registry.

2. Hapus layanan Cloud Run.

3. Hapus resource Eventarc Advanced:

   1. Menghapus pendaftaran.

   2. Menghapus pipeline.

   3. Menghapus bus.

Atau, Anda dapat menghapus project Google Cloud untuk menghindari tagihan. Menghapus project Google Cloud akan menghentikan penagihan untuk semua resource yang digunakan dalam project tersebut.

Perhatian: Menghapus project akan mengakibatkan:

• Semua hal dalam project akan dihapus. Jika Anda menggunakan project yang ada untuk mengerjakan tugas di dokumen ini, saat Anda menghapusnya, pekerjaan lain dalam project tersebut juga akan dihapus.
• Project ID kustom akan hilang. Saat membuat project ini, Anda mungkin juga membuat project ID kustom yang masih ingin digunakan pada masa mendatang. Agar tidak kehilangan URL yang menggunakan project ID tersebut, seperti URL appspot.com, hapus resource yang dipilih di dalam project, bukan menghapus seluruh project.

Jika Anda berencana mempelajari beberapa arsitektur, tutorial atau panduan memulai, dengan menggunakan kembali project dapat membantu Anda agar tidak melampaui batas kuota project.

Menghapus Google Cloud project:

gcloud projects delete PROJECT_ID

Langkah berikutnya

• Memublikasikan acara dari sumber Google
• Memublikasikan acara secara langsung
• Mentransformasi peristiwa yang diterima
• Memformat peristiwa yang diterima