Eventarc ve Cloud Run işlevlerini kullanarak Cloud Storage'dan etkinlik işlemeyi tetikleme

1. Genel Bakış

Bu laboratuvarda, etkinlik işlemeyi tetiklemek için Cloud Storage paket etkinliklerini ve Eventarc'ı nasıl kullanacağınızı öğreneceksiniz. Verileri analiz etmek ve görüntüleri işlemek için Cloud Run işlevlerini kullanacaksınız. İşlev, Google'ın Vision API'sini kullanır ve elde edilen resmi Cloud Storage paketine geri kaydeder.

Öğrenecekleriniz

Resim işleme ardışık düzeni oluşturma.

• Depolama paketlerini yapılandırma
• Cloud Storage'da nesne okumak ve yazmak için Cloud Run işlevi oluşturma
• Eventarc tetikleyici dağıtma
• Yiyecek resimlerini algılamak için Vision API'yi entegre etme
• Uçtan uca çözümü test etme ve doğrulama

Ön koşullar

• Bu laboratuvarda, Cloud Console ve kabuk ortamlarına aşina olmanız gerekir.
• Cloud Storage, Cloud Run işlevleri veya Vision API ile ilgili deneyiminiz varsa faydalı olur ancak gerekli değildir.

2. Kurulum ve Gereksinimler

Cloud projesi oluşturma

1. Google Cloud Console'da oturum açın ve yeni bir proje oluşturun veya mevcut bir projeyi yeniden kullanın. Gmail veya Google Workspace hesabınız yoksa hesap oluşturmanız gerekir.

• Proje adı, bu projenin katılımcılarının görünen adıdır. Google API'leri tarafından kullanılmayan bir karakter dizesidir. Dilediğiniz zaman güncelleyebilirsiniz.
• Proje kimliği, tüm Google Cloud projelerinde benzersizdir ve değiştirilemez (ayarlandıktan sonra değiştirilemez). Cloud Console, benzersiz bir dize otomatik olarak oluşturur. Bu dizenin ne olduğu genellikle önemli değildir. Çoğu kod laboratuvarında proje kimliğinize (genellikle PROJECT_ID olarak tanımlanır) referans vermeniz gerekir. Oluşturulan kimliği beğenmezseniz rastgele başka bir kimlik oluşturabilirsiniz. Alternatif olarak, kendi anahtarınızı deneyerek kullanılabilir olup olmadığını görebilirsiniz. Bu adımdan sonra değiştirilemez ve proje boyunca geçerli kalır.
• Bazı API'lerin kullandığı üçüncü bir değer (Proje Numarası) olduğunu belirtmek isteriz. Bu üç değer hakkında daha fazla bilgiyi dokümanlar bölümünde bulabilirsiniz.

Dikkat: Proje kimliği dünya genelinde benzersizdir ve seçtikten sonra başkaları tarafından kullanılamaz. Bu kimliğin tek kullanıcısı siz olmalısınız. Bir proje silinse bile kimlik tekrar kullanılamaz.

Not: Gmail hesabı kullanıyorsanız varsayılan konumu Kuruluş yok olarak ayarlayabilirsiniz. Google Workspace hesabı kullanıyorsanız kuruluşunuz için uygun bir konum seçin.

2. Ardından, Cloud kaynaklarını/API'lerini kullanmak için Cloud Console'da faturalandırmayı etkinleştirmeniz gerekir. Bu codelab'i çalıştırmak çok pahalı değildir. Bu eğitimden sonra faturalandırılmamak için kaynakları kapatmak istiyorsanız oluşturduğunuz kaynakları veya projeyi silebilirsiniz. Yeni Google Cloud kullanıcıları 300 ABD doları değerindeki ücretsiz deneme programına uygundur.

Cloud Shell'i etkinleştirme

Arama çubuğunun sağındaki simgeyi tıklayarak Cloud Shell'i etkinleştirin.

Ortam Kurulumu

1. Cloud Shell terminalinde aşağıdaki komutları çalıştırarak proje ve kaynakla ilgili ortam değişkenleri oluşturun.

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. Laboratuvar için gerekli API'leri etkinleştirme

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. Depoyu klonlama

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

3. Cloud Storage paketlerini yapılandırma

Depolama paketleri oluşturma

Görüntü işleme ardışık düzeniniz için yükleme ve küçük resim Cloud Storage paketleri oluşturun.

İki paket oluşturmak için gsutil mb komutunu ve benzersiz bir ad kullanın:

1. Resimlerin önce yükleneceği paketi yükleme
2. Oluşturulan küçük resimleri depolamak için küçük resimler paketi

Yeni resimler yüklemek için bir paket oluşturun:

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

Örnek çıkış:

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

Oluşturulan küçük resimleri depolamak için bir paket oluşturun:

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

Örnek çıkış:

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

Paket izinlerini güncelleme

Depolama alanı paketi izinlerini, kullanıcılara okuma izinleri verecek şekilde güncelleyin.

Paketinizdeki nesneleri okuma ve yazma izni vermek için gsutil iam ch komutunu kullanın:

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

Uyarı: Depolama paketlerine erişimi sınırlamak en iyi uygulamadır. Bu laboratuvarda, tüm kullanıcıların tüm nesneleri görüntülemesine izin verilecektir. Depolama alanı paketlerinin güvenliğini sağlama hakkında daha fazla bilgi için IAM İzni ve Cloud Storage için En İyi Uygulamalar başlıklı makaleleri inceleyin.

Örnek çıkış

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

4. Hizmet hesaplarını yapılandır

Cloud Function'ın küçük resimleri işleyebilmesi için özel bir hizmet hesabı oluşturun:

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

Artifact Registry'den okuma işlemlerine izin vermek için artifactregistry.reader rolünü verin:

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

Oluşturulan resimlerin küçük resim paketinde depolanmasına izin vermek için storage.objectCreator rolünü verin:

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

Cloud Run hizmetinin çağrılmasına izin vermek için run.invoker rolünü verin:

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

Sağlayıcılardan etkinlik almasına izin vermek için eventarc.eventReceiver rolünü verin:

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

Cloud Storage hizmet hesabına pubsub.publisher rolünü verin. Bu sayede hizmet hesabı, pakete resim yüklendiğinde etkinlikleri yayınlayabilir.

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. Resim İşleme İşlevine Genel Bakış

Cloud Storage'dan bir resim indirip resmi yeniden boyutlandırıp Cloud Storage'a geri yükleyen bir işlev oluşturun. İşlev, resme açıklama etiketi atamak için Vision API'yi çağırır. İşlev, açıklama etiketini kontrol eder. Etiket, resmi "Yemek" olarak tanımlarsa menü öğesinin resmini ve küçük resmini güncellemek için menü hizmetine bir etkinlik gönderilir.

İşlevleri tetikleme

Cloud Storage işlevleri, Cloud Storage'daki Pub/Sub bildirimlerini temel alır ve benzer etkinlik türlerini destekler:

• tamamlama
• sil
• arşiv
• meta veri güncellemesi

Bu laboratuvarda, Cloud Storage'da bir nesne tamamlandığında bir işlevi dağıtıp tetikleyeceksiniz.

Nesne Sonlandırma

Nesne tamamlama etkinlikleri, bir Cloud Storage nesnesinin "yazma" işlemi başarıyla tamamlandığında tetiklenir. Özellikle, yeni bir nesne oluşturmak veya mevcut bir nesnenin üzerine yazmak bu etkinliği tetikler. Arşivleme ve meta veri güncelleme işlemleri bu tetikleyici tarafından yoksayılır.

6. Cloud Storage'ı entegre etme

Cloud Storage, nesnelerinizi Google Cloud'da depolamak için kullanabileceğiniz bir hizmettir. Nesne, herhangi bir biçimdeki bir dosyadan oluşan değişmez bir veri parçasıdır. Nesneleri paket adı verilen kapsayıcılarda depolarsınız. Tüm paketler bir projeyle ilişkilendirilir ve projelerinizi bir kuruluş altında gruplandırabilirsiniz. İstemci kitaplıkları ve API'ler , Cloud Storage ile entegrasyonu kolaylaştırır.

Bu laboratuvarda, Cloud Storage'da nesne okumak ve yazmak için istemci kitaplığını kullanacaksınız.

İstemci kitaplığını yükleme

Cloud istemci kitaplıkları birçok popüler programlama dilinde mevcuttur. Kitaplıkları kullanmaya başlamak için istemci kitaplığını yüklemeniz gerekir.

İstemci kitaplığını kullanma

Uygulama ayrıntıları büyük ölçüde programlama diline bağlıdır. İstemci kitaplığını uygulamanızda kullanmak için ilk adım, Cloud Storage bağımlılıkları içe aktarmaktır. Örneğin, Node.js projesinde içe aktarma işlemleri package.json dosyasına eklenir. Aşağıdaki snippet'te bu laboratuvarın package.json dosyası bildirimi gösterilmektedir.

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",
        ...
    }
  }

package.json dosyası, uygulamanın bağımlılıklarından biri olarak google-cloud/storage'ı listeler.

google-cloud/functions-framework bağımlılığı, Cloud Storage etkinlikleri tarafından tetiklenecek bir CloudEvent geri çağırma işlevini Functions Framework'a kaydetmek için kullanılır.

Yüklenen resimlerin gıda ürünü olup olmadığını belirlemek için ek açıklamalarını almak üzere Vision API'yi çağırmak amacıyla google-cloud/vision bağımlılığı kullanılır.

CloudEvent geri çağırma işlevi kaydetme

Pakete yeni bir resim yüklendiğinde Cloud Storage tarafından tetiklenecek bir CloudEvent geri çağırma işlevi Functions Framework ile kaydedin.

index.js

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

Depolama alanı referans nesnesi oluşturma

İstemci kitaplıkları içe aktarıldıktan sonra, uygulamanızın etkileşimde bulunacağı yeni bir depolama alanı istemcisi ve paketleri oluşturmanız gerekir.

index.js

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

Yukarıdaki kod, "storage" adlı bir depolama alanı istemcisi ve "bucket" ve "thumbBucket" değişkenleri tarafından referans verilecek iki depolama alanı paketi referansı oluşturur.

Cloud Storage nesnelerini indirme

index.js

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

Bu temel indirme davranışını kullanarak kesintiye uğrayan indirmeleri devam ettirebilir ve dilimlenmiş nesne indirmeleri ve akış indirmeleri gibi daha gelişmiş indirme stratejilerinden yararlanabilirsiniz.

Cloud Storage'a nesne yükleme

Cloud Storage'a yükleme isteklerini üç şekilde gönderebilirsiniz: tek istek, devam ettirilebilir veya XML API çok parçalı yükleme. Daha büyük yüklemeler veya canlı yüklemeler için devam ettirilebilir yüklemeleri kullanın. XML API ile dosyalar parçalara ayrılarak yüklenir ve tek bir nesne olarak birleştirilir. Küçük nesneler için tek istekli yüklemeleri kullanın.

Aşağıdaki kod, tek istekli yükleme kullanarak bir resmi Cloud Storage'a yükler.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Vision API'yi entegre etme

Cloud Vision, geliştiricilerin görsel etiketleme, yüz ve önemli nokta algılama, optik karakter tanıma (OCR) ve uygunsuz içeriği etiketleme gibi görsel algılama özelliklerini uygulamalara kolayca entegre etmelerini sağlar.

İstemci kitaplığını yükleme

Cloud istemci kitaplıkları birçok popüler programlama dilinde mevcuttur. Kitaplıkları kullanmaya başlamak için istemci kitaplığını yüklemeniz gerekir.

Resim Ekleyici istemcisi oluşturma

Resmi istemci SDK'larını kullanarak Google API'lerine erişmek için API'nin SDK'ya açıklandığı API'nin keşif belgesine dayalı bir hizmet nesnesi oluşturursunuz. Kimlik bilgilerinizi kullanarak Vision API'nin keşif hizmetinden almanız gerekir.

index.js

const client = new vision.ImageAnnotatorClient();

İstemci, varsayılan olarak GOOGLE_APPLICATION_CREDENTIALS ortam değişkeni tarafından belirtilen hizmet hesabı dosyasını kullanarak kimlik doğrulaması yapar.

Vision API isteği oluşturma

Vision API, görüntü dosyasının içeriğini isteğinizin gövdesinde base64 kodlu bir dize olarak göndererek görüntü dosyasında özellik algılama işlemi gerçekleştirebilir.

Resminizi notlandırmak için images kaynağını kullanarak istek oluşturmak. Bu API'ye gönderilen istek, istek listesi içeren bir nesne biçimindedir. Bu listedeki her öğe iki bilgi parçası içerir:

• Base64 kodlu görüntü verileri
• İlgili resimde açıklama eklenmesini istediğiniz özelliklerin listesi.

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. Cloud Run işlevlerini dağıtma

Bu resim boyutlandırma hizmeti, daha büyük Cymbal Eats sisteminin bir parçasıdır. Bu bölümde, yalnızca resim işleme özelliğiyle ilgili bileşenleri dağıtacaksınız. Tam kurulum, resmi yüklemek için bir kullanıcı arayüzü ve elde edilen meta verileri depolamak için bir yayın isteği içerir. Bu özellikler bu laboratuvar kapsamında yüklenmez.

İşlev dağıtımı sırasında aşağıdaki bileşenler oluşturulur:

• Cloud Run işlevleri
• Eventarc tetikleyicisi
• Pub/Sub Konusu ve Aboneliği

Cloud Shell terminalinde, menu-item-uploads-$PROJECT_ID üzerinde tetikleyici paketi içeren Cloud Run işlevlerini dağıtmak için aşağıdaki komutu çalıştırın:

Bir Cloud Run işlevini doğrudan Cloud Run'a dağıtmak için önce işlevi dağıtır, ardından işlev için bir tetikleyici oluşturursunuz.

Cloud Run işlevlerini dağıtın:

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

Örnek çıkış:

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

Tetikleyiciyi oluşturun:

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"

Örnek çıkış:

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.

Tetikleyici dağıtımı, izin sorunu nedeniyle başarısız olursa lütfen önceki adımdaki IAM değişikliklerinin dağıtılmasını bekleyin. Bu işlem genellikle 1-2 dakika sürer. Ardından dağıtımı tekrar deneyin.

Örnek hata çıkışı:

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

Cloud Console'da, işlev için oluşturulan Cloud Run hizmetini inceleyin:

Cloud Console'da, işlev için oluşturulan Eventarc tetikleyicisini inceleyin:

Cloud Konsolu'nda, Eventarc tetikleyicisi için oluşturulan Pub/Sub konusunu ve aboneliğini inceleyin:

9. Uçtan uca çözümü test etme ve doğrulama

Cloud Storage'a yeni bir fotoğraf yükleyin ve görüntüler analiz edilirken ardışık düzenin ilerleme durumunu izleyin. Cloud Functions günlüklerini izleyerek uçtan uca çözümü test edersiniz.

Resim yükleme

Not: Tom Dillon'un Unsplash'taki fotoğrafı, Unsplash Lisansı kapsamında ücretsiz olarak kullanılabilir.

1. Bu resmi yerel makinenize kaydedin.
2. Dosyayı 1.jpg olarak yeniden adlandırın.
3. Cloud Storage konsolunu açın
4. menu-item-uploads-... paketini tıklayın.
5. DOSYA YÜKLE'yi tıklayın.
6. 1.jpg dosyasını depolama paketine yükleyin
7. Cloud Console'da Cloud Run'a gidin.
8. process-thumbails'i tıklayın.
9. GÜNLÜKLER sekmesini tıklayın.

Not: İşlev başarıyla çalıştı ve resmi küçük resimler paketine yükledi. Yüklenen görüntünün Vision API etiketlerine göre menü öğesi durumu "Hazır" olarak ayarlanır. Bu, Vision API'nin resme "Gıda" olarak not eklediği anlamına gelir.

Menü hizmeti bu laboratuvara dağıtılmadığı için menü öğesini güncelleme isteği başarısız oldu.

10. menu-item-thumbnails-$PROJECT_ID Cloud Storage paketine gidin
11. Küçük resim resminin küçük resimler paketinde oluşturulduğunu doğrulama

Gıda dışı bir resim yükleme

İşlevin düzgün çalıştığını doğrulamak için "Gıda" öğesi olarak sınıflandırılacak bir nesne içermeyen bir resim yüklersiniz.

Not: Insung Yoon'un Unsplash'taki fotoğrafı, Unsplash Lisansı kapsamında ücretsiz olarak kullanılabilir.

1. Bu resmi yerel makinenize kaydedin.
2. Dosyayı 2.jpg olarak yeniden adlandırın.
3. Cloud Storage konsolunu açın
4. menu-item-uploads-... paketini tıklayın.
5. DOSYA YÜKLE'yi tıklayın.
6. 2.jpg dosyasını depolama paketine yükleyin
7. Cloud Console'da Cloud Run'a gidin.
8. process-thumbails'i tıklayın.
9. GÜNLÜKLER sekmesini tıklayın.

Not: İşlev başarıyla çalıştı ve resmi küçük resimler paketine yükledi. Yüklenen görüntünün Vision API etiketlerine göre menü öğesi durumu "Başarısız" olarak ayarlanır. Bu, Vision API'nin resme "Yiyecek" olarak not eklemediği anlamına gelir.

Menü hizmeti bu laboratuvara dağıtılmadığından menü öğesini güncelleme isteği başarısız oldu.

10. Tebrikler!

Tebrikler, laboratuvarı tamamladınız.

Sıradaki adım:

Diğer Cymbal Eats codelab'lerini keşfedin:

• Eventarc ile Cloud iş akışlarını tetikleme
• Cloud Run'dan Private CloudSQL'e bağlanma
• Cloud Run'dan Tümüyle Yönetilen Veritabanlara Bağlanma
• Identity-Aware Proxy (IAP) ile sunucusuz uygulamayı güvence altına alma
• Cloud Scheduler ile Cloud Run işlerini tetikleme
• Cloud Run'a Güvenli Dağıtım
• Cloud Run giriş trafiğinin güvenliğini sağlama
• GKE Autopilot'ten özel AlloyDB'ye bağlanma

Temizleme

Bu eğiticide kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız kaynakları içeren projeyi silin veya projeyi saklayıp kaynakları tek tek silin.

Projeyi silme

Faturalandırılmanın önüne geçmenin en kolay yolu, eğitim için oluşturduğunuz projeyi silmektir.