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 paketi 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 sonuçtaki resmi Cloud Storage paketine geri kaydeder.

Öğrenecekleriniz

Görüntü işleme hattı oluşturma

Depolama paketlerini yapılandırma
Cloud Storage'daki nesneleri okumak ve yazmak için Cloud Run işlevleri oluşturma
Eventarc tetikleyicisi dağıtma
Yemek resimlerini algılamak için Vision API'yi entegre edin
Uçtan uca çözümü test etme ve doğrulama

Ön koşullar

Bu laboratuvarda Cloud Console ve kabuk ortamları hakkında bilgi sahibi olduğunuz varsayılır.
Daha önce Cloud Storage, Cloud Run işlevleri veya Vision API deneyiminiz olması yararlı olsa da zorunlu değildir.

2. Kurulum ve Gereksinimler

Cloud projesi kurulumu

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ı için görünen addır. Google API'leri tarafından kullanılmayan bir karakter dizesidir. Bu bilgiyi istediğiniz zaman güncelleyebilirsiniz.
Proje kimliği, tüm Google Cloud projelerinde benzersizdir ve sabittir (ayarlandıktan sonra değiştirilemez). Cloud Console, benzersiz bir dizeyi otomatik olarak oluşturur. Genellikle bu dizenin ne olduğuyla ilgilenmezsiniz. Çoğu codelab'de proje kimliğinize (genellikle PROJECT_ID olarak tanımlanır) başvurmanız gerekir. Oluşturulan kimliği beğenmezseniz başka bir rastgele kimlik oluşturabilirsiniz. Dilerseniz kendi adınızı deneyerek kullanılabilir olup olmadığını kontrol edebilirsiniz. Bu adım tamamlandıktan sonra değiştirilemez ve proje süresince geçerli kalır.
Bazı API'lerin kullandığı üçüncü bir değer olan Proje Numarası da vardır. Bu üç değer hakkında daha fazla bilgiyi belgelerde bulabilirsiniz.

Ardından, Cloud kaynaklarını/API'lerini kullanmak için Cloud Console'da faturalandırmayı etkinleştirmeniz gerekir. Bu codelab'i tamamlamak neredeyse hiç maliyetli değildir. Bu eğitimin ötesinde faturalandırılmayı önlemek için kaynakları kapatmak üzere oluşturduğunuz kaynakları veya projeyi silebilirsiniz. Yeni Google Cloud kullanıcıları 300 ABD doları değerinde ücretsiz deneme programından yararlanabilir.

Cloud Shell'i etkinleştirme

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

Ortam Kurulumu

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

Lab için gerekli API'leri etkinleştirin.

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

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:

Resimlerin ilk olarak yükleneceği yükleme paketi
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 grubu izinlerini, kullanıcılara okuma izni 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

Örnek çıkış

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

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

Cloud Functions için küçük resimleri işleyecek ö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 hizmeti ç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 alınması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 resimler yüklendiğinde etkinlik 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. Görüntü İşleme İşlevine Genel Bakış

Cloud Storage'dan bir resmi indirmek, resmi yeniden boyutlandırmak ve resmi tekrar Cloud Storage'a yüklemek için 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 "Yiyecek" 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'dan gelen Pub/Sub bildirimlerine dayanır ve benzer etkinlik türlerini destekler:

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

Nesne Sonlandırma

Nesne sonlandırma etkinlikleri, bir Cloud Storage nesnesinin "yazma" işlemi başarıyla sonlandırıldığında tetiklenir. Bu özellikle, yeni bir nesne oluşturmanın veya mevcut bir nesnenin üzerine yazmanın bu etkinliği tetiklediği anlamına gelir. Arşiv 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 depolamaya yönelik 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, nesneleri Cloud Storage'a 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 kullanılabilir. 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ını içe aktarmaktır. Örneğin, Node.js projesinde içe aktarmalar package.json dosyasına eklenir. Aşağıdaki snippet'te bu laboratuvarın package.json dosya 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",
        ...
    }
  }

CloudEvent geri çağırması kaydetme

Yeni bir resim pakete yüklendiğinde Cloud Storage tarafından tetiklenecek Functions Framework ile bir CloudEvent geri çağırma kaydı oluşturun.

index.js

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

Depolama referans nesnesi oluşturma

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

index.js

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

Cloud Storage nesnelerini indirme

index.js

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

Cloud Storage'a nesne yükleme

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

Aşağıdaki kod, tek istekli yükleme kullanarak bulut depolama alanına bir resim yükler.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Vision API'yi entegre etme

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

İstemci kitaplığını yükleme

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

Görüntü Notlandırma İstemcisi Oluşturma

Resmi istemci SDK'larını kullanarak Google API'lerine erişmek için API'yi SDK'ya açıklayan 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();

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.

Resminize açıklama eklemek için Görseller kaynağını kullanarak bir istek oluşturun. Bu API'ye yapılan istekler, istek listesi içeren bir nesne biçimindedir. Bu listedeki her öğe iki bilgi içerir:

Base64 kodlu görüntü verileri
Bu görüntüyle ilgili olarak açıklama eklemek 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 yeniden boyutlandırma hizmeti, daha büyük olan Cymbal Eats sisteminin bir parçasıdır. Bu bölümde, yalnızca görüntü işleme özelliğiyle ilgili bileşenleri dağıtacaksınız. Tam kurulumda, görüntüyü yüklemek için bir kullanıcı arayüzü ve sonuç meta verilerini depolamak için bir aşağı akış isteği bulunur. Bu özellikler, bu laboratuvarın bir parçası olarak 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 olan Cloud Run işlevlerini dağıtmak için aşağıdaki komutu çalıştırın:

Cloud Run işlevlerini 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 yayılmasını bekleyin. 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 Console'da, Eventarc tetikleyicisi için oluşturulan Pub/Sub Konusu ve Aboneliği'ni 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 işlem hattının ilerleme durumunu izleyin. Cloud Functions günlüklerini izleyerek uçtan uca çözümü test edeceksiniz.

Resim yükleme

Bu resmi yerel makinenize kaydedin.
1.jpg dosyasını yeniden adlandırın.
Cloud Storage konsolunu açın.
menu-item-uploads-... paketini tıklayın.
DOSYA YÜKLE'yi tıklayın.
1.jpg dosyasını depolama paketine yükleyin.
Cloud Console'da Cloud Run'a gidin.
process-thumbails'i tıklayın.
LOGS (Günlükler) sekmesini tıklayın.

menu-item-thumbnails-$PROJECT_ID Cloud Storage paketine gidin.
Küçük resim dosyasının küçük resimler paketinde oluşturulduğunu doğrulayın.

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

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

Bu resmi yerel makinenize kaydedin.
2.jpg dosyasını yeniden adlandırın.
Cloud Storage konsolunu açın.
menu-item-uploads-... paketini tıklayın.
DOSYA YÜKLE'yi tıklayın.
2.jpg dosyasını depolama paketine yükleyin.
Cloud Console'da Cloud Run'a gidin.
process-thumbails'i tıklayın.
LOGS (Günlükler) sekmesini tıklayın.

10. Tebrikler!

Tebrikler, laboratuvarı tamamladınız.

Sıradaki adım:

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

Temizleme

Bu eğitimde kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini önlemek amacıyla kaynakları içeren projeyi silin veya projeyi koruyup tek tek kaynakları silin.

Projeyi silme

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