Memublikasikan peristiwa ke tugas Cloud Run

Memublikasikan peristiwa ke tugas Cloud Run

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. Men-deploy tugas Cloud Run dari kode sumber.

2. Buat bus Eventarc Advanced.

3. Buat pendaftaran Lanjutan Eventarc.

4. Memublikasikan pesan peristiwa ke bus.

5. Pastikan bahwa tugas Cloud Run berhasil dieksekusi.

Anda dapat menyelesaikan panduan memulai ini menggunakan gcloud CLI.

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.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the 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 pada gcloud CLI, jalankan perintah berikut:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Cloud Build, Cloud Run and Eventarc APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

Install the 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 pada gcloud CLI, jalankan perintah berikut:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Cloud Build, Cloud Run and Eventarc APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable artifactregistry.googleapis.com cloudbuild.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—misalnya, us-central1.

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).

   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:

   • Cloud Run Developer (roles/run.developer)
   • 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 memberikan izin yang diperlukan kepada Eventarc Advanced untuk menjalankan tugas Cloud Run, minta administrator Anda untuk memberikan peran IAM Cloud Run Invoker (roles/run.invoker) di projectGoogle Cloud Anda kepada akun layanan:
   1. Membuat akun layanan. Untuk tujuan pengujian, Anda akan melampirkan akun layanan ini ke pipeline Lanjutan Eventarc untuk merepresentasikan identitas pipeline.

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Ganti SERVICE_ACCOUNT_NAME dengan nama untuk akun layanan Anda.
   2. Berikan peran IAM roles/run.invoker ke akun layanan:

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

Men-deploy tugas Cloud Run dari kode sumber

Deploy tugas Cloud Run sebagai tujuan peristiwa Anda. Tidak seperti layanan Cloud Run yang memproses dan menyalurkan permintaan, tugas Cloud Run hanya menjalankan tugasnya dan keluar setelah selesai. Tugas tidak memproses atau melayani permintaan.

Tujuan peristiwa lainnya—seperti topik Pub/Sub, Workflows, atau endpoint HTTP lain—didukung. Untuk mengetahui informasi selengkapnya, lihat Penyedia dan tujuan peristiwa.

Buat tugas dari kode sumber Python menggunakan perintah gcloud run jobs deploy. Kode Anda secara otomatis dikemas ke dalam image container, diupload ke Artifact Registry, lalu di-deploy ke Cloud Run.

1. Buat direktori bernama jobs dan buka direktori tersebut:

   mkdir jobs
   cd jobs
   

2. Buat file main.py dan salin kode contoh berikut ke dalamnya:

   import os
   
   TASK_INDEX = os.getenv("CLOUD_RUN_TASK_INDEX", 0)
   
   def main():
       """
       This job prints "Hello world"
       """
       print(f"Starting task #{TASK_INDEX}...")
       print("Hello world")
       print(f"Completed task #{TASK_INDEX}.")
   
   # Start script
   if __name__ == "__main__":
       main()
   

3. Buat file teks bernama Procfile tanpa ekstensi file dan salin teks berikut ke dalamnya:

   web: python3 main.py
   

4. Deploy tugas:

   gcloud run jobs deploy JOB_NAME \
       --source . \
       --tasks 1 \
       --region=$REGION

   Ganti JOB_NAME dengan nama unik untuk tugas Cloud Run—misalnya, my-job.

Membuat bus Lanjutan Eventarc

Bus menerima pesan peristiwa dari sumber pesan atau yang dipublikasikan oleh penyedia, dan berfungsi 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 bus atau nama yang sepenuhnya memenuhi syarat—misalnya, my-bus.

Membuat pendaftaran Lanjutan Eventarc

Pendaftaran menentukan pesan mana yang dirutekan ke tujuan. Objek ini juga menentukan pipeline yang digunakan untuk mengonfigurasi tujuan pesan peristiwa. Dalam hal ini, tujuan target adalah tugas Cloud Run.

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='https://REGION-run.googleapis.com/apis/run.googleapis.com/v1/namespaces/PROJECT_NUMBER/jobs/JOB_NAME:run',http_endpoint_message_binding_template='{"body": ""}',oauth_token_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --input-payload-format-json= \
       --location=$REGION

   Ganti kode berikut:

   • PIPELINE_NAME: ID pipeline atau nama yang sepenuhnya memenuhi syarat—misalnya, my-pipeline.
   • PROJECT_NUMBER: nomor project Anda. Google Cloud Anda dapat mengambil nomor project dengan menjalankan perintah berikut:

   gcloud projects describe PROJECT_ID --format='value(projectNumber)'

   Perhatikan hal berikut:

   • Kunci http_endpoint_message_binding_template mengubah peristiwa menjadi format yang diharapkan oleh Cloud Run Admin API. Saat menentukan pengikatan pesan, Anda harus mengonfigurasi format input untuk mengakses payload.
   • Kunci oauth_token_authentication_service_account menentukan email akun layanan. Email ini digunakan untuk membuat token OAuth yang biasanya hanya digunakan saat memanggil Google API yang dihosting di *.googleapis.com.

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 sepenuhnya memenuhi syarat—misalnya, my-enrollment.

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

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

Memublikasikan pesan acara ke bus

Untuk memublikasikan pesan secara langsung ke bus, gunakan perintah gcloud eventarc message-buses publish atau kirim permintaan ke REST API Penerbitan Eventarc. 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

Publikasikan peristiwa ke bus menggunakan gcloud CLI dan --event-data serta tanda 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

Publikasikan 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".

Pastikan bahwa tugas Cloud Run berhasil dieksekusi

Setelah memublikasikan peristiwa ke bus Eventarc Advanced, periksa log tugas Cloud Run untuk memverifikasi bahwa tugas Cloud Run berhasil dieksekusi dan "Hello world" dicetak. Mungkin perlu waktu beberapa menit sebelum tugas berjalan dan selesai.

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

   gcloud logging read 'textPayload: "Hello world"'
   

2. Cari entri log yang mirip dengan berikut ini:

   insertId: 693c8dd0000cb2976d7966b8
   ...
   labels:
       job_name: JOB_NAME
       location: REGION
       project_id: PROJECT_ID
   type: cloud_run_job
   textPayload: Hello world
   timestamp: '2025-12-12T21:49:04.832151Z'
   

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

3. Anda juga dapat mengonfirmasi bahwa tugas Cloud Run berhasil dieksekusi menggunakan perintah gcloud run jobs describe:

   gcloud run jobs describe JOB_NAME \
       --region=$REGION
   

   Anda akan melihat output yang mirip dengan hal berikut ini:

   ✔ Job JOB_NAME in region us-central1
   Executed 1 time
   ...
   

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

Pembersihan

Untuk membantu menghindari penagihan berkelanjutan setelah Anda menyelesaikan panduan memulai ini, hapus resource yang Anda buat:

1. Menghapus tugas Cloud Run.

2. Hapus resource Eventarc Advanced:

   1. Menghapus pendaftaran.

   2. Menghapus pipeline.

   3. Menghapus bus.

Atau, hapus project Google Cloud Anda untuk membantu menghindari timbulnya biaya. Menghapus project Google Cloud akan menghentikan penagihan untuk semua resource yang digunakan dalam project tersebut.

Perhatian: Penghapusan project memiliki efek berikut:

• 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 berbagai arsitektur, tutorial, atau panduan memulai, project dapat digunakan kembali agar Anda tidak melampaui batas kuota project.

Delete a 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