Memicu Pemrosesan Peristiwa dari Cloud Storage menggunakan fungsi Eventarc dan Cloud Run

1. Ringkasan

Dalam lab ini, Anda akan mempelajari cara menggunakan peristiwa bucket Cloud Storage dan Eventarc untuk memicu pemrosesan peristiwa. Anda akan menggunakan fungsi Cloud Run untuk menganalisis data dan memproses gambar. Fungsi ini akan menggunakan Vision API Google dan menyimpan gambar yang dihasilkan kembali di bucket Cloud Storage.

Yang akan Anda pelajari

Cara mem-build pipeline pemrosesan gambar.

• Mengonfigurasi bucket Storage
• Membuat fungsi Cloud Run untuk membaca dan menulis objek di Cloud Storage
• Men-deploy pemicu Eventarc
• Mengintegrasikan Vision API untuk mendeteksi gambar makanan
• Menguji dan memvalidasi solusi menyeluruh

Prasyarat

• Di lab ini, Anda dianggap telah memahami Konsol Cloud dan lingkungan shell.
• Pengalaman sebelumnya dengan Cloud Storage, fungsi Cloud Run, atau Vision API akan membantu, tetapi tidak diwajibkan.

2. Penyiapan dan Persyaratan

Penyiapan Project Cloud

1. Login ke Google Cloud Console dan buat project baru atau gunakan kembali project yang sudah ada. Jika belum memiliki akun Gmail atau Google Workspace, Anda harus membuatnya.

• Project name adalah nama tampilan untuk peserta project ini. String ini adalah string karakter yang tidak digunakan oleh Google API. Anda dapat memperbaruinya kapan saja.
• Project ID bersifat unik di semua project Google Cloud dan tidak dapat diubah (tidak dapat diubah setelah ditetapkan). Cloud Console otomatis membuat string unik; biasanya Anda tidak mementingkan kata-katanya. Di sebagian besar codelab, Anda harus merujuk Project ID-nya (umumnya diidentifikasi sebagai PROJECT_ID). Jika tidak suka dengan ID yang dibuat, Anda dapat membuat ID acak lainnya. Atau, Anda dapat mencobanya sendiri, dan lihat apakah ID tersebut tersedia. ID tidak dapat diubah setelah langkah ini dan tersedia selama durasi project.
• Sebagai informasi, ada nilai ketiga, Project Number, yang digunakan oleh beberapa API. Pelajari lebih lanjut ketiga nilai ini di dokumentasi.

Perhatian: Project ID bersifat unik secara global dan tidak dapat digunakan orang lain setelah Anda memilihnya. Anda adalah satu-satunya pengguna ID tersebut. Meskipun project sudah dihapus, ID tersebut tidak dapat digunakan lagi

Catatan: Jika menggunakan akun Gmail, Anda dapat menyetel lokasi default ke No organization. Jika Anda menggunakan akun Google Workspace, pilih lokasi yang sesuai untuk organisasi Anda.

2. Selanjutnya, Anda harus mengaktifkan penagihan di Konsol Cloud untuk menggunakan resource/API Cloud. Menjalankan operasi dalam codelab ini tidak akan memakan banyak biaya, bahkan mungkin tidak sama sekali. Guna mematikan resource agar tidak menimbulkan penagihan di luar tutorial ini, Anda dapat menghapus resource yang dibuat atau menghapus project-nya. Pengguna baru Google Cloud memenuhi syarat untuk mengikuti program Uji Coba Gratis senilai $300 USD.

Mengaktifkan Cloud Shell

Aktifkan Cloud Shell dengan mengklik ikon di sebelah kanan kotak penelusuran.

Penyiapan Lingkungan

1. Buat variabel lingkungan terkait project dan resource dengan menjalankan perintah di bawah di terminal Cloud Shell.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NAME=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export REGION=us-east1 
export UPLOAD_BUCKET_NAME=menu-item-uploads-$PROJECT_ID
export UPLOAD_BUCKET=gs://menu-item-uploads-$PROJECT_ID
export BUCKET_THUMBNAILS=gs://menu-item-thumbnails-$PROJECT_ID
export MENU_SERVICE_NAME=menu-service
export USER_EMAIL=$(gcloud config list account --format "value(core.account)")

2. Mengaktifkan API yang diperlukan untuk lab

gcloud services enable \
    vision.googleapis.com \
    cloudfunctions.googleapis.com \
    pubsub.googleapis.com \
    cloudbuild.googleapis.com \
    logging.googleapis.com \
    eventarc.googleapis.com \
    artifactregistry.googleapis.com \
    run.googleapis.com \
    --quiet

3. Melakukan cloning repositori

git clone https://github.com/GoogleCloudPlatform/cymbal-eats.git && cd cymbal-eats/cloud-functions

3. Mengonfigurasi bucket Cloud Storage

Membuat Bucket Penyimpanan

Buat bucket Cloud Storage upload dan thumbnail untuk pipeline pemrosesan gambar Anda.

Gunakan perintah gsutil mb dan nama unik untuk membuat dua bucket:

1. Bucket upload tempat gambar akan diupload terlebih dahulu
2. Bucket thumbnail untuk menyimpan gambar thumbnail yang dibuat

Buat bucket untuk mengupload gambar baru:

gsutil mb -p $PROJECT_ID -l $REGION $UPLOAD_BUCKET

Contoh output:

Creating gs://menu-item-uploads-cymbal-eats-8399-3119/...

Buat bucket untuk menyimpan thumbnail yang dihasilkan:

gsutil mb -p $PROJECT_ID -l $REGION $BUCKET_THUMBNAILS

Contoh output:

Creating gs://menu-item-thumbnails-cymbal-eats-8399-3119/...

Memperbarui izin Bucket

Perbarui izin bucket penyimpanan untuk mengizinkan izin baca kepada pengguna.

Gunakan perintah gsutil iam ch untuk memberikan izin membaca dan menulis objek di bucket Anda:

gsutil iam ch allUsers:objectViewer $UPLOAD_BUCKET
gsutil iam ch allUsers:objectViewer $BUCKET_THUMBNAILS

Peringatan: Praktik terbaiknya adalah membatasi akses ke bucket penyimpanan. Untuk tujuan lab ini, semua pengguna akan diizinkan untuk melihat semua objek. Untuk informasi selengkapnya tentang cara mengamankan bucket penyimpanan, tinjau artikel Menggunakan Izin IAM dan Praktik Terbaik untuk Cloud Storage

Contoh output

Updated IAM policy for project [cymbal-eats-8399-3119].
[...]

4. Konfigurasi akun layanan

Buat akun layanan kustom untuk Cloud Function guna memproses thumbnail:

export CF_SERVICE_ACCOUNT=thumbnail-service-sa
gcloud iam service-accounts create ${CF_SERVICE_ACCOUNT}

Berikan peran artifactregistry.reader untuk mengizinkan operasi baca dari Artifact Registry:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/artifactregistry.reader"

Berikan peran storage.objectCreator untuk mengizinkan penyimpanan gambar yang dihasilkan di bucket thumbnail:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/storage.objectCreator"

Berikan peran run.invoker untuk mengizinkan pemanggilan layanan Cloud Run:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/run.invoker"

Berikan peran eventarc.eventReceiver untuk mengizinkan peristiwa penerimaan dari penyedia:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/eventarc.eventReceiver"

Berikan peran pubsub.publisher ke akun layanan Cloud Storage. Tindakan ini akan memungkinkan akun layanan memublikasikan peristiwa saat gambar diupload ke bucket.

GCS_SERVICE_ACCOUNT=$(gsutil kms serviceaccount -p $PROJECT_NUMBER)

gcloud projects add-iam-policy-binding $PROJECT_NUMBER \
    --member "serviceAccount:$GCS_SERVICE_ACCOUNT" \
    --role "roles/pubsub.publisher"

5. Ringkasan Fungsi Pemrosesan Gambar

Buat fungsi untuk mendownload gambar dari Cloud Storage, mengubah ukuran gambar, dan mengupload gambar kembali ke Cloud Storage. Fungsi ini akan memanggil Vision API untuk menetapkan label deskripsi ke gambar. Fungsi ini akan memeriksa label deskripsi. Jika label mengidentifikasi gambar sebagai "Makanan", peristiwa akan dikirim ke layanan menu untuk memperbarui gambar dan thumbnail item menu.

Memicu Fungsi

Fungsi Cloud Storage didasarkan pada notifikasi Pub/Sub dari Cloud Storage dan mendukung jenis peristiwa serupa:

• finalisasi
• hapus
• arsip
• pembaruan metadata

Di lab ini, Anda akan men-deploy dan memicu fungsi saat objek diselesaikan di Cloud Storage.

Finalisasi Objek

Peristiwa penyelesaian objek dipicu saat "penulisan" Objek Cloud Storage berhasil diselesaikan. Secara khusus, hal ini berarti bahwa membuat objek baru atau menimpa objek yang ada akan memicu peristiwa ini. Operasi update metadata dan arsip akan diabaikan oleh pemicu ini.

6. Mengintegrasikan Cloud Storage

Cloud Storage adalah layanan untuk menyimpan objek di Google Cloud. Object adalah bagian data yang tidak dapat diubah dan terdiri dari file dalam format apa pun. Anda menyimpan objek di container yang disebut bucket. Semua bucket terkait dengan project, dan Anda dapat mengelompokkan project Anda di bawah organisasi. Library klien dan API membuat integrasi dengan Cloud Storage

Di lab ini, Anda akan menggunakan library klien untuk membaca dan menulis objek ke Cloud Storage.

Menginstal library klien

Library klien Cloud tersedia dalam banyak bahasa pemrograman populer. Untuk mulai menggunakan library, Anda harus menginstal library klien.

Menggunakan library klien

Detail penerapan secara besar bergantung pada bahasa pemrograman. Untuk menggunakan library klien di aplikasi Anda, langkah pertama adalah mengimpor dependensi Cloud Storage. Misalnya, dalam project Node.js, impor ditambahkan dalam file package.json. Cuplikan di bawah menunjukkan pemberitahuan file package.json lab ini.

package.json

{
    "name": "thumbnail-service",
    "version": "0.1.0",
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0",
      "@google-cloud/storage": "^5.18.2",
      "@google-cloud/vision": "^2.4.2",
        ...
    }
  }

File package.json mencantumkan google-cloud/storage sebagai salah satu dependensi aplikasi.

Dependensi google-cloud/functions-framework digunakan untuk mendaftarkan callback CloudEvent dengan Framework Fungsi yang akan dipicu oleh peristiwa Cloud Storage.

Dependensi google-cloud/vision akan digunakan untuk memanggil Vision API guna mendapatkan anotasi untuk gambar yang diupload untuk menentukan apakah gambar tersebut merupakan item makanan atau bukan.

Mendaftarkan callback CloudEvent

Daftarkan callback CloudEvent dengan Framework Fungsi yang akan dipicu oleh Cloud Storage saat gambar baru diupload ke bucket.

index.js

functions.cloudEvent('process-thumbnails', async (cloudEvent) => {
    console.log(`Event ID: ${cloudEvent.id}`);
    console.log(`Event Type: ${cloudEvent.type}`);
    ...

Membuat objek referensi penyimpanan

Setelah library klien diimpor, Anda harus membuat klien penyimpanan baru dan bucket yang akan berinteraksi dengan aplikasi Anda.

index.js

const storage = new Storage();
const bucket = storage.bucket(file.bucket);
const thumbBucket = storage.bucket(process.env.BUCKET_THUMBNAILS);

Kode di atas membuat klien penyimpanan yang disebut "storage" dan dua referensi ke bucket penyimpanan yang akan dirujuk oleh variabel "bucket" dan "thumbBucket"

Mendownload objek Cloud Storage

index.js

await bucket.file(file.name).download({
            destination: originalFile
        });

Dengan perilaku download dasar ini, Anda dapat melanjutkan download yang terhenti, dan dapat menggunakan strategi download lanjutan, seperti download objek irisan dan download streaming.

Mengupload objek ke Cloud Storage

Anda dapat mengirim permintaan upload ke Cloud Storage dengan tiga cara: upload multibagian XML API, upload multibagian yang dapat dilanjutkan, atau upload multibagian satu permintaan. Untuk upload yang lebih besar atau upload streaming, gunakan upload yang dapat dilanjutkan. Dengan XML API, file diupload sebagian dan digabungkan sebagai satu objek. Untuk objek yang lebih kecil, gunakan upload satu permintaan.

Kode di bawah mengupload gambar ke cloud storage menggunakan upload satu permintaan.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Mengintegrasikan Vision API

Cloud Vision memungkinkan developer untuk mengintegrasikan fitur deteksi penglihatan dengan mudah dalam aplikasi, termasuk pelabelan gambar, deteksi wajah dan tempat terkenal, pengenalan karakter optik (OCR), dan pemberian tag konten vulgar.

Menginstal library klien

Library klien Cloud tersedia dalam banyak bahasa pemrograman populer. Untuk mulai menggunakan library, Anda harus menginstal library klien.

Membuat Klien Anotasi Gambar

Untuk mengakses Google API menggunakan SDK klien resmi, Anda dapat membuat objek layanan berdasarkan dokumen penemuan API, yang menjelaskan API ke SDK. Anda perlu mengambilnya dari layanan penemuan Vision API, menggunakan kredensial Anda.

index.js

const client = new vision.ImageAnnotatorClient();

Secara default, klien akan melakukan autentikasi menggunakan file akun layanan yang ditentukan oleh variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS.

Membuat permintaan Vision API

Vision API dapat melakukan deteksi fitur pada file gambar dengan mengirimkan konten file gambar sebagai string yang dienkode base64 dalam isi permintaan Anda.

Untuk membuat permintaan menggunakan resource gambar guna menganotasi gambar Anda. Permintaan ke API ini berbentuk objek dengan daftar permintaan. Setiap item dalam daftar ini berisi dua bit informasi:

• Data gambar berenkode base64
• Daftar fitur yang ingin Anda anotasikan tentang gambar tersebut.

index.js

        const client = new vision.ImageAnnotatorClient();
        const visionRequest = {
            image: { source: { imageUri: `gs://${file.bucket}/${file.name}` } },
            features: [
                { type: 'LABEL_DETECTION' },
            ]
        };
        const visionPromise = client.annotateImage(visionRequest);

8. Men-deploy fungsi Cloud Run

Layanan pengubahan ukuran gambar ini adalah bagian dari sistem Cymbal Eats yang lebih besar. Di bagian ini, Anda hanya akan men-deploy komponen yang terkait dengan fitur pemrosesan gambar. Penginstalan lengkap menggabungkan UI untuk mengupload gambar dan permintaan downstream untuk menyimpan metadata yang dihasilkan. Kemampuan tersebut tidak diinstal sebagai bagian dari lab ini.

Komponen berikut akan dibuat selama deployment fungsi:

• Fungsi Cloud Run
• Pemicu Eventarc
• Topik dan Langganan Pub/Sub

Di terminal cloudshell, jalankan perintah di bawah untuk men-deploy fungsi Cloud Run dengan bucket pemicu di menu-item-uploads-$PROJECT_ID:

Untuk men-deploy fungsi Cloud Run langsung ke Cloud Run, Anda harus men-deploy fungsi terlebih dahulu, lalu membuat pemicu untuk fungsi tersebut.

Men-deploy fungsi cloud run:

gcloud beta run deploy process-thumbnails \
      --source=thumbnail \
      --function process-thumbnails \
      --region $REGION \
      --base-image google-22-full/nodejs20 \
      --no-allow-unauthenticated \
      --project=$PROJECT_ID \
--service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
--set-env-vars=BUCKET_THUMBNAILS=$BUCKET_THUMBNAILS,MENU_SERVICE_URL=$MENU_SERVICE_URL \
  --max-instances=1 \
  --quiet

Contoh output:

Done.                                                                                                                                                                                    
Service [process-thumbnails] revision [process-thumbnails-00001-abc] has been deployed and is serving 100 percent of traffic.
Service URL: https://process-thumbnails-000000000.us-east1.run.app

Buat pemicu:

gcloud eventarc triggers create process-thumbnails-trigger \
     --location=$REGION \
     --destination-run-service=process-thumbnails \
    --destination-run-region=$REGION \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=$UPLOAD_BUCKET_NAME" \
     --service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com"

Contoh output:

Creating trigger [process-thumbnails-trigger] in project [qwiklabs-gcp-02-53f8532696e1], location [us-east1]...done.                                                                     
WARNING: It may take up to 2 minutes for the new trigger to become active.

Jika deployment pemicu gagal karena masalah izin, tunggu hingga perubahan IAM dari langkah sebelumnya diterapkan. Biasanya memerlukan waktu 1-2 menit, lalu coba deploy lagi.

Contoh output error:

...If you recently started to use Eventarc, it may take a few minutes before all necessary permissions are propagated to the Service Agent...
[...] 

Di Cloud Console, tinjau layanan Cloud Run yang dibuat untuk fungsi:

Di konsol Cloud, tinjau pemicu Eventarc yang dibuat untuk fungsi:

Di konsol Cloud, tinjau Topik dan Langganan Pub/Sub yang dibuat untuk pemicu Eventarc:

9. Menguji dan memvalidasi solusi menyeluruh

Upload foto baru ke Cloud Storage dan pantau progres pipeline saat gambar dianalisis. Anda akan menguji solusi menyeluruh dengan memantau log cloud function.

Mengupload gambar

Catatan: Foto oleh Tom Dillon di Unsplash dapat digunakan secara gratis berdasarkan Lisensi Unsplash

1. Simpan gambar ini ke komputer lokal Anda
2. Ganti nama file 1.jpg
3. Buka konsol Cloud Storage
4. Klik bucket menu-item-uploads-...
5. Klik UPLOAD FILES
6. Upload 1.jpg ke bucket penyimpanan
7. Di Cloud Console, buka Cloud Run
8. Klik process-thumbails
9. Klik tab LOGS

Catatan: Fungsi berhasil berjalan dan memuat gambar ke bucket thumbnail. Berdasarkan label Vision API untuk gambar yang diupload, status item menu akan ditetapkan ke "Siap". Artinya, Vision API telah menganotasi gambar sebagai "Makanan".

Karena layanan menu tidak di-deploy di lab ini, permintaan untuk memperbarui item menu gagal.

10. Buka bucket menu-item-thumbnails-$PROJECT_ID Cloud Storage
11. Pastikan gambar thumbnail telah dibuat di bucket thumbnail

Mengupload gambar non-makanan

Untuk memverifikasi bahwa fungsi ini berfungsi dengan benar, Anda akan mengupload gambar yang tidak berisi objek yang akan diklasifikasikan sebagai item "Makanan".

Catatan: Foto oleh Insung Yoon di Unsplash dapat digunakan secara gratis berdasarkan Lisensi Unsplash

1. Simpan gambar ini ke komputer lokal Anda
2. Ganti nama file 2.jpg
3. Buka konsol Cloud Storage
4. Klik bucket menu-item-uploads-...
5. Klik UPLOAD FILE
6. Upload 2.jpg ke bucket penyimpanan
7. Di Cloud Console, buka Cloud Run
8. Klik process-thumbails
9. Klik tab LOGS

Catatan: Fungsi berhasil berjalan dan mengupload gambar ke bucket thumbnail. Berdasarkan label Vision API untuk gambar yang diupload, status item menu akan ditetapkan ke "Gagal". Artinya, Vision API tidak menganotasi gambar sebagai "Makanan".

Karena layanan menu tidak di-deploy di lab ini, permintaan untuk memperbarui item menu gagal.

10. Selamat!

Selamat, Anda telah menyelesaikan lab!

Langkah berikutnya:

Jelajahi codelab Cymbal Eats lainnya:

• Memicu Alur Kerja Cloud dengan Eventarc
• Menghubungkan ke CloudSQL Pribadi dari Cloud Run
• Menghubungkan ke Database yang Dikelola Sepenuhnya dari Cloud Run
• Mengamankan Aplikasi Serverless dengan Identity Aware Proxy (IAP)
• Memicu Tugas Cloud Run dengan Cloud Scheduler
• Men-deploy dengan Aman ke Cloud Run
• Mengamankan Traffic Masuk Cloud Run
• Menghubungkan ke AlloyDB pribadi dari GKE Autopilot

Pembersihan

Agar tidak dikenai biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus project yang berisi resource tersebut, atau simpan project dan hapus setiap resource.

Menghapus project

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