Memicu Pemrosesan Peristiwa dari Cloud Storage menggunakan Eventarc dan Cloud Functions (generasi ke-2)

1. Ringkasan

Di lab ini, Anda akan mempelajari cara menggunakan peristiwa bucket Cloud Storage dan Eventarc untuk memicu pemrosesan peristiwa. Anda akan menggunakan Cloud Functions (generasi ke-2) untuk menganalisis data dan memproses gambar. Fungsi ini akan menggunakan Vision API Google dan menyimpan kembali gambar yang dihasilkan di bucket Cloud Storage.

Yang akan Anda pelajari

Cara membangun pipeline pemrosesan gambar.

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

Prasyarat

• Di lab ini, Anda dianggap telah memahami Konsol Cloud dan lingkungan shell.
• Pengalaman Cloud Storage, Cloud Functions, atau Vision API sebelumnya 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 peduli tentang apa itu. Di sebagian besar codelab, Anda harus mereferensikan Project ID (biasanya diidentifikasi sebagai PROJECT_ID). Jika Anda tidak menyukai ID yang dihasilkan, 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 akan tetap ada 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 akan dapat digunakan lagi

Catatan: Jika menggunakan akun Gmail, Anda dapat menyetel lokasi default ke Tidak ada organisasi. 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 seharusnya tidak memerlukan banyak biaya, bahkan mungkin tidak sama sekali. Untuk mematikan resource agar tidak menimbulkan penagihan di luar tutorial ini, Anda dapat menghapus resource yang dibuat atau menghapus seluruh project. 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 project dan variabel lingkungan terkait resource dengan menjalankan perintah di bawah ini 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=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. Aktifkan API yang diperlukan untuk lab. (Langkah khusus Qwiklabs)

gcloud services disable cloudfunctions.googleapis.com
gcloud services enable cloudfunctions.googleapis.com

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

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

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

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

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 memberikan 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: Sebaiknya batasi 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 Gunakan 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}

Beri 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 dibuat 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"

Beri peran eventarc.eventReceiver untuk mengizinkan penerimaan peristiwa 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 dalam 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 sebuah objek difinalisasi di Cloud Storage.

Finalisasi Objek

Peristiwa finalisasi 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 arsip dan metadata 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 yang populer. Untuk mulai menggunakan library, Anda harus menginstal library klien.

Menggunakan library klien

Detail implementasi secara besar-besaran 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 ini 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 Functions Framework yang akan dipicu oleh peristiwa Cloud Storage.

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

Mendaftarkan callback CloudEvent

Daftarkan callback CloudEvent dengan Framework Functions yang akan dipicu oleh Cloud Storage saat gambar baru diupload ke dalam 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 bernama "storage" dan dua referensi ke bucket penyimpanan yang akan direferensikan oleh variabel "bucket" dan "thumbBucket"

Mendownload objek Cloud Storage

index.js

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

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

Mengupload objek ke Cloud Storage

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

Kode di bawah mengupload gambar ke penyimpanan cloud menggunakan upload permintaan tunggal.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Mengintegrasikan Vision API

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

Menginstal library klien

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

Membuat Klien Annotator Gambar

Untuk mengakses Google API menggunakan SDK klien resmi, Anda membuat objek layanan berdasarkan dokumen penemuan API, yang menjelaskan API ke SDK. Anda harus 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 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 Cloud Function

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:

• Cloud Function
• Layanan Cloud Run
• Pemicu Eventarc
• Topik dan Langganan Pub/Sub

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

gcloud functions deploy process-thumbnails \
  --gen2 \
  --runtime=nodejs16 \
  --source=thumbnail \
  --region=$REGION \
  --project=$PROJECT_ID \
  --entry-point=process-thumbnails \
  --trigger-bucket=$UPLOAD_BUCKET \
  --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

Jika deployment gagal karena masalah izin pada bucket penyimpanan upload - harap tunggu sampai perubahan IAM diterapkan dari langkah sebelumnya. Biasanya memerlukan waktu 1-2 menit, lalu coba lagi deployment lagi.

Contoh output

Deploying function (may take a while - up to 2 minutes)...done.
[...] 

Di konsol Cloud, tinjau Cloud Function yang telah dibuat:

Di konsol Cloud, tinjau layanan Cloud Run yang dibuat untuk fungsi tersebut:

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

Di konsol Cloud, tinjau Topic dan Subscription Pub/Sub yang dibuat untuk pemicu Eventarc:

9. Menguji dan memvalidasi solusi end-to-end

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

Mengupload gambar yang sesuai

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

1. Simpan image ini ke komputer lokal Anda
2. Ganti nama file menjadi 1.jpg
3. Buka konsol Cloud Storage
4. Klik bucket menu-item-uploads-...
5. Klik UPLOAD FILES
6. Mengupload 1.jpg ke bucket penyimpanan
7. Di Konsol Cloud, buka Cloud Functions
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". Ini berarti Vision API menganotasi gambar sebagai "Food". Karena kita tidak men-deploy layanan menu, permintaan untuk memperbarui item menu gagal.

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

Mengupload gambar non-makanan

Untuk memverifikasi bahwa fungsi tersebut berfungsi dengan baik, Anda akan mengupload gambar yang tidak berisi objek yang akan diklasifikasikan sebagai "Makanan" yang bermanfaat.

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

1. Simpan image ini ke komputer lokal Anda
2. Ganti nama file menjadi 2.jpg
3. Buka konsol Cloud Storage
4. Klik bucket menu-item-uploads-...
5. Klik UPLOAD FILES
6. Mengupload 2.jpg ke bucket penyimpanan
7. Di Konsol Cloud, buka Cloud Functions
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 disetel ke "Gagal". Ini berarti 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, kamu telah menyelesaikan lab!

Langkah berikutnya:

Pelajari codelab Cymbal Eats lainnya:

• Memicu Cloud Workflows dengan Eventarc
• Terhubung ke Private CloudSQL dari Cloud Run
• Terhubung ke Database yang Terkelola Sepenuhnya dari Cloud Run
• Aplikasi Serverless yang Aman dengan Identity-Aware Proxy (IAP)
• Memicu Tugas Cloud Run dengan Cloud Scheduler
• Men-deploy dengan Aman ke Cloud Run
• Mengamankan Traffic Masuk Cloud Run
• Terhubung ke AlloyDB pribadi dari Autopilot GKE

Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus project yang berisi resource, atau simpan project dan hapus resource satu per satu.

Menghapus project

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