Memicu fungsi dari Cloud Storage menggunakan Eventarc

---

Pratinjau — Cloud Run functions

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.

Tutorial ini menunjukkan cara men-deploy fungsi berbasis peristiwa di Cloud Run, dan menggunakan Eventarc untuk memicu fungsi sebagai respons terhadap peristiwa Cloud Storage menggunakan Google Cloud CLI.

Dengan menentukan filter untuk pemicu Eventarc, Anda dapat mengonfigurasi pemilihan rute peristiwa, termasuk sumber peristiwa dan target peristiwa. Untuk contoh dalam tutorial ini, update pada bucket Cloud Storage akan memicu peristiwa tersebut, dan permintaan akan dikirim ke fungsi Anda dalam bentuk permintaan HTTP.

Tujuan

Dalam tutorial ini, Anda akan:

1. Buat bucket Cloud Storage untuk menjadi sumber peristiwa.
2. Men-deploy fungsi berbasis peristiwa.
3. Buat pemicu Eventarc.
4. Picu fungsi dengan mengupload file ke Cloud Storage.

Biaya

Dalam dokumen ini, Anda menggunakan komponen Google Cloud yang dapat ditagih berikut:

• Artifact Registry
• Cloud Build
• Cloud Run
• Cloud Storage
• Eventarc

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga. Pengguna baru Google Cloud mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

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.

1. 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.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Buat atau pilih project Google Cloud.

   Catatan: Jika 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.

   • Membuat project Google Cloud:

     gcloud projects create PROJECT_ID

     Ganti PROJECT_ID dengan nama untuk project Google Cloud 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.

5. Make sure that billing is enabled for your Google Cloud project.

6. Install the Google Cloud CLI.

7. To initialize the gcloud CLI, run the following command:

   gcloud init

8. Buat atau pilih project Google Cloud.

   Catatan: Jika 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.

   • Membuat project Google Cloud:

     gcloud projects create PROJECT_ID

     Ganti PROJECT_ID dengan nama untuk project Google Cloud 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.

9. Make sure that billing is enabled for your Google Cloud project.

10. Jika tidak menggunakan Cloud Shell, update komponen Google Cloud CLI dan login menggunakan akun Anda:

    gcloud components update
    gcloud auth login

11. Aktifkan API:

    gcloud services enable artifactregistry.googleapis.com \
        cloudbuild.googleapis.com \
        eventarc.googleapis.com \
        run.googleapis.com \
        storage.googleapis.com

12. Tetapkan variabel konfigurasi yang akan digunakan dalam tutorial ini:

    export REGION=us-central1
    gcloud config set run/region ${REGION}
    gcloud config set run/platform managed
    gcloud config set eventarc/location ${REGION}

13. Jika Anda dikenai kebijakan organisasi pembatasan domain yang membatasi pemanggilan yang tidak diautentikasi untuk project, Anda perlu mengakses layanan yang di-deploy seperti yang dijelaskan di bagian Menguji layanan pribadi.

Menetapkan peran yang diperlukan

1. 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). Untuk mengetahui informasi selengkapnya, lihat halaman eran dan izin untuk tujuan peristiwa Anda.

   Izin yang diperlukan

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

   • Editor Cloud Build (roles/cloudbuild.builds.editor)
   • Cloud Run Admin (roles/run.admin)
   • Cloud Run Source Developer (roles/run.sourceDeveloper)
   • Eventarc Admin (roles/eventarc.admin)
   • 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)
   • Storage Admin (roles/storage.admin)

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

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

2. Catat akun layanan default Compute Engine karena Anda akan melampirkan akun tersebut ke pemicu Eventarc untuk merepresentasikan identitas pemicu untuk tujuan pengujian. Akun layanan ini dibuat secara otomatis setelah mengaktifkan atau menggunakan layanan Google Cloud yang menggunakan Compute Engine, dan dengan format email berikut:

   PROJECT_NUMBER-compute@

   Ganti PROJECT_NUMBER dengan nomor project Google Cloud Anda. Anda dapat menemukan nomor project di halaman Selamat Datang pada Konsol Google Cloud atau dengan menjalankan perintah berikut:

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

   Untuk lingkungan produksi, sebaiknya buat akun layanan baru dan berikan satu atau beberapa peran IAM yang berisi izin minimum yang diperlukan dan ikuti prinsip hak istimewa terendah.

   Catatan:

   Batasan kebijakan organisasi iam.automaticIamGrantsForDefaultServiceAccounts mencegah peran Editor diberikan secara otomatis ke akun layanan default. Jika Anda membuat organisasi setelah 3 Mei 2024, batasan ini akan diterapkan secara default.

   Sebaiknya terapkan batasan ini untuk menonaktifkan pemberian peran otomatis. Jika Anda menonaktifkan pemberian peran otomatis, Anda harus menentukan peran mana yang akan diberikan ke akun layanan default, lalu memberikan peran ini secara manual.

   Jika akun layanan default sudah memiliki peran Editor, sebaiknya ganti peran Editor dengan peran yang kurang permisif. Untuk mengubah peran akun layanan dengan aman, gunakan Policy Simulator untuk melihat dampak perubahan, lalu berikan dan cabut peran yang sesuai.

3. Secara default, layanan Cloud Run hanya dapat dipanggil oleh Project Owner, Project Editor, Cloud Run Admin dan Invoker. Anda dapat mengontrol akses per layanan; namun, untuk tujuan pengujian, berikan peran Cloud Run Invoker (run.invoker) di project Google Cloud ke akun layanan Compute Engine. Peran ini akan memberikan peran tersebut di semua layanan dan tugas Cloud Run dalam suatu project.

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:PROJECT_NUMBER-compute@ \
       --role=roles/run.invoker

   Perhatikan bahwa pemicu akan berhasil dibuat dan diaktifkan jika Anda membuat pemicu untuk layanan Cloud Run yang diautentikasi tanpa memberikan peran Cloud Run Namun, pemicu tidak akan berfungsi seperti yang diharapkan dan pesan yang mirip dengan berikut ini akan muncul di log:

   The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
4. Berikan Peran Eventarc Event Receiver (roles/eventarc.eventReceiver) pada project ke akun layanan default Compute Engine agar pemicu Eventarc dapat menerima peristiwa dari penyedia peristiwa.

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:PROJECT_NUMBER-compute@ \
       --role=roles/eventarc.eventReceiver

5. Sebelum membuat pemicu untuk peristiwa langsung dari Cloud Storage, berikan peran Pub/Sub Publisher (roles/pubsub.publisher) ke agen layanan Cloud Storage:

   SERVICE_ACCOUNT="$(gcloud storage service-agent --project=PROJECT_ID)"
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:${SERVICE_ACCOUNT}" \
       --role='roles/pubsub.publisher'

6. Jika Anda mengaktifkan agen layanan Cloud Pub/Sub pada atau sebelum 8 April 2021, untuk mendukung permintaan push Pub/Sub yang diautentikasi, berikan peran Service Account Token Creator (roles/iam.serviceAccountTokenCreator) ke agen layanan. Jika tidak, peran ini akan diberikan secara default:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub. \
       --role=roles/iam.serviceAccountTokenCreator

Membuat bucket Cloud Storage

Membuat bucket Cloud Storage untuk digunakan sebagai sumber peristiwa:

gcloud storage buckets create -l us-central1 gs://PROJECT_ID-bucket/

Catatan: Bucket Cloud Storage harus berada di project Google Cloud dan region atau multi-region yang sama dengan pemicu Eventarc.

Menulis fungsi berbasis peristiwa

Untuk menulis fungsi berbasis peristiwa, ikuti langkah-langkah berikut:

Node.js

1. Buat sebuah direktori baru bernama helloGCS dan ubah ke direktori tersebut:

      mkdir helloGCS
      cd helloGCS
   

2. Buat file package.json di direktori helloGCS untuk menentukan dependensi Node.js:

   {
     "name": "nodejs-docs-samples-functions-v2-storage",
     "version": "0.0.1",
     "private": true,
     "license": "Apache-2.0",
     "author": "Google LLC",
     "repository": {
       "type": "git",
       "url": "https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"
     },
     "engines": {
       "node": ">=16.0.0"
     },
     "scripts": {
       "test": "c8 mocha -p -j 2 test/*.test.js --timeout=60000"
     },
     "dependencies": {
       "@google-cloud/functions-framework": "^3.0.0"
     },
     "devDependencies": {
       "c8": "^10.0.0",
       "mocha": "^10.0.0",
       "sinon": "^18.0.0",
       "supertest": "^7.0.0"
     }
   }
   

3. Buat file index.js di direktori helloGCS dengan contoh Node.js berikut:

   const functions = require('@google-cloud/functions-framework');
   
   // Register a CloudEvent callback with the Functions Framework that will
   // be triggered by Cloud Storage.
   functions.cloudEvent('helloGCS', cloudEvent => {
     console.log(`Event ID: ${cloudEvent.id}`);
     console.log(`Event Type: ${cloudEvent.type}`);
   
     const file = cloudEvent.data;
     console.log(`Bucket: ${file.bucket}`);
     console.log(`File: ${file.name}`);
     console.log(`Metageneration: ${file.metageneration}`);
     console.log(`Created: ${file.timeCreated}`);
     console.log(`Updated: ${file.updated}`);
   });

Python

1. Buat sebuah direktori baru bernama helloGCS dan ubah ke direktori tersebut:

      mkdir helloGCS
      cd helloGCS
   

2. Buat file requirements.txt di direktori helloGCS, untuk menentukan dependensi Python:

   functions-framework==3.5.0
   cloudevents==1.11.0

   Langkah ini akan menambahkan paket yang dibutuhkan oleh contoh.

3. Buat file main.py di direktori helloGCS dengan contoh Python berikut:

   from cloudevents.http import CloudEvent
   
   import functions_framework
   
   
   # Triggered by a change in a storage bucket
   @functions_framework.cloud_event
   def hello_gcs(cloud_event: CloudEvent) -> tuple:
       """This function is triggered by a change in a storage bucket.
   
       Args:
           cloud_event: The CloudEvent that triggered this function.
       Returns:
           The event ID, event type, bucket, name, metageneration, and timeCreated.
       """
       data = cloud_event.data
   
       event_id = cloud_event["id"]
       event_type = cloud_event["type"]
   
       bucket = data["bucket"]
       name = data["name"]
       metageneration = data["metageneration"]
       timeCreated = data["timeCreated"]
       updated = data["updated"]
   
       print(f"Event ID: {event_id}")
       print(f"Event type: {event_type}")
       print(f"Bucket: {bucket}")
       print(f"File: {name}")
       print(f"Metageneration: {metageneration}")
       print(f"Created: {timeCreated}")
       print(f"Updated: {updated}")
   
       return event_id, event_type, bucket, name, metageneration, timeCreated, updated
   
   

Men-deploy fungsi berbasis peristiwa

Deploy fungsi bernama helloworld-events dengan menjalankan perintah berikut di direktori yang berisi kode contoh:

Node.js

gcloud beta run deploy helloworld-events \
      --source . \
      --function helloGCS \
      --base-image nodejs20 \
      --region us-central1

Python

gcloud beta run deploy helloworld-events \
      --source . \
      --function hello_gcs \
      --base-image python312 \
      --region us-central1

Setelah deployment selesai, Google Cloud CLI akan menampilkan URL tempat layanan helloworld-events berjalan.

Membuat pemicu Eventarc

Pemicu Eventarc mengirimkan peristiwa dari bucket Cloud Storage ke layanan Cloud Run helloworld-events Anda.

1. Buat pemicu yang memfilter peristiwa Cloud Storage:

   gcloud eventarc triggers create TRIGGER_NAME  \
       --location=${REGION} \
       --destination-run-service=helloworld-events  \
       --destination-run-region=${REGION} \
       --event-filters="type=google.cloud.storage.object.v1.finalized" \
       --event-filters="bucket=PROJECT_ID-bucket" \
       --service-account=PROJECT_NUMBER-compute@

   Ganti:

   • TRIGGER_NAME dengan nama untuk pemicu Anda.
   • PROJECT_ID dengan ID project Google Cloud Anda.
   • PROJECT_NUMBER dengan nomor project Google Cloud Anda.

   Perhatikan bahwa saat membuat pemicu Eventarc untuk pertama kalinya dalam project Google Cloud, mungkin akan ada penundaan dalam penyediaan agen layanan Eventarc. Masalah ini biasanya dapat diatasi dengan mencoba membuat ulang pemicu. Untuk informasi selengkapnya, lihat Error izin ditolak.

2. Konfirmasi bahwa pemicu telah berhasil dibuat. Perhatikan bahwa meskipun pemicu Anda langsung dibuat, diperlukan waktu hingga dua menit agar pemicu berfungsi sepenuhnya.

   gcloud eventarc triggers list --location=${REGION}

   Output-nya akan mirip dengan berikut ini:

   NAME: helloworld-events
   TYPE: google.cloud.storage.object.v1.finalized
   DESTINATION: Cloud Run service: helloworld-events
   ACTIVE: Yes
   LOCATION: us-central1
   

Membuat dan melihat peristiwa

Upload file teks ke bucket Cloud Storage untuk membuat peristiwa yang dirutekan ke fungsi. Fungsi Cloud Run mencatat peristiwa ke dalam log layanan.

1. Upload file teks ke Cloud Storage untuk membuat peristiwa:

    echo "Hello World" > random.txt
    gcloud storage cp random.txt gs://PROJECT_ID-bucket/random.txt
   

   Hasil upload ini akan membuat peristiwa dan fungsi Cloud Run akan mencatat pesan peristiwa tersebut ke dalam log.

2. Untuk melihat entri log:

   1. Filter entri log dan tampilkan output dalam format JSON:

      gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json
      

   2. Cari entri log yang mirip dengan:

      [
        {
         ....
          "resource": {
            "labels": {
              ....
              "location": "us-central1",
              .....
              "service_name": "helloworld-events"
            },
          },
          "textPayload": "File: random.txt",
           .....
        }
      ]
      

      Catatan: Jika Anda tidak melihat entri log, tunggu beberapa menit dan coba lagi perintah gcloud logging read. Pemicu dapat memerlukan waktu hingga dua menit untuk mulai memfilter peristiwa setelah dibuat

      Log mungkin memerlukan waktu beberapa saat untuk ditampilkan. Jika Anda tidak melihatnya, periksa lagi setelah satu menit.

Setelah Anda melihat entri log, ini mengonfirmasi bahwa Anda telah berhasil men-deploy fungsi berbasis peristiwa yang dipicu saat file teks diupload ke Cloud Storage.

Pembersihan

Jika Anda membuat project baru untuk tutorial ini, hapus project tersebut. Jika Anda menggunakan project yang ada dan ingin mempertahankannya tanpa perubahan yang ditambahkan dalam tutorial ini, hapus resource yang dibuat untuk tutorial.

Menghapus project

Cara termudah untuk menghilangkan penagihan adalah dengan menghapus project yang Anda buat untuk tutorial.

Untuk menghapus project:

Perhatian: Menghapus project memiliki efek berikut:

• Semua hal dalam project akan dihapus. Jika menggunakan project yang sudah ada untuk tugas dalam dokumen ini, saat Anda menghapusnya, pekerjaan lain yang telah Anda lakukan dalam project tersebut juga akan terhapus.
• Project ID kustom hilang. Saat membuat project ini, Anda mungkin telah membuat project ID kustom yang ingin digunakan di masa mendatang. Untuk mempertahankan URL yang menggunakan project ID, 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, menggunakan kembali project dapat membantu agar Anda tidak melampaui batas kuota project.

1. Di konsol Google Cloud, buka halaman Manage resource.

   Buka Manage resource

2. Pada daftar project, pilih project yang ingin Anda hapus, lalu klik Delete.
3. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.

Menghapus referensi tutorial

1. Hapus layanan Cloud Run yang Anda deploy dalam tutorial ini:

   gcloud run services delete SERVICE_NAME

   Dengan SERVICE_NAME adalah nama layanan pilihan Anda.

   Anda juga dapat menghapus layanan Cloud Run dari Google Cloud Console.

2. Hapus konfigurasi default gcloud CLI yang Anda tambahkan selama penyiapan tutorial.

   Contoh:

   gcloud config unset run/region

   atau

   gcloud config unset project

3. Hapus resource Google Cloud lain yang dibuat dalam tutorial ini:

   • Hapus pemicu Eventarc:

     gcloud eventarc triggers delete TRIGGER_NAME
     

     Ganti TRIGGER_NAME dengan nama pemicu Anda.

Langkah selanjutnya

• Membuat pemicu Eventarc untuk jenis peristiwa lainnya
• Mengelola fungsi