Attivazione dell'elaborazione degli eventi da Cloud Storage utilizzando Eventarc e le funzioni Cloud Run

1. Panoramica

In questo lab imparerai a utilizzare gli eventi bucket Cloud Storage ed Eventarc per attivare l'elaborazione degli eventi. Utilizzerai Cloud Run Functions per analizzare i dati ed elaborare le immagini. La funzione utilizzerà l'API Vision di Google e salverà l'immagine risultante nel bucket Cloud Storage.

Cosa imparerai a fare

Come creare una pipeline di elaborazione delle immagini.

• Configura i bucket di archiviazione
• Crea una funzione Cloud Run per leggere e scrivere oggetti in Cloud Storage
• Esegui il deployment di un trigger Eventarc
• Integra l'API Vision per rilevare le immagini di cibo
• Testare e convalidare la soluzione end-to-end

Prerequisiti

• Questo lab presuppone familiarità con la console Cloud e gli ambienti shell.
• L'esperienza pregressa con Cloud Storage, le funzioni Cloud Run o l'API Vision è utile, ma non obbligatoria.

2. Configurazione e requisiti

Configurazione del progetto Cloud

1. Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora un account Gmail o Google Workspace, devi crearne uno.

• Il nome del progetto è il nome visualizzato per i partecipanti a questo progetto. È una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarlo.
• L'ID progetto è univoco in tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo l'impostazione). La console Cloud genera automaticamente una stringa univoca, di solito non ti interessa di cosa si tratta. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere identificato come PROJECT_ID). Se non ti piace l'ID generato, puoi generarne un altro casuale. In alternativa, puoi provare a crearne uno e vedere se è disponibile. Non può essere modificato dopo questo passaggio e rimane per tutta la durata del progetto.
• Per tua informazione, esiste un terzo valore, un numero di progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.

Attenzione:un ID progetto è univoco a livello globale e non può essere utilizzato da altri dopo che lo hai selezionato. Sei l'unico utente di questo ID. Anche se un progetto viene eliminato, l'ID non può essere riutilizzato

Nota:se utilizzi un account Gmail, puoi lasciare la posizione predefinita impostata su Nessuna organizzazione. Se utilizzi un account Google Workspace, scegli una posizione adatta alla tua organizzazione.

2. Successivamente, devi abilitare la fatturazione in Cloud Console per utilizzare le risorse/API Cloud. Completare questo codelab non costa molto, se non nulla. Per arrestare le risorse ed evitare addebiti oltre a quelli previsti in questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud possono usufruire del programma prova senza costi di 300$.

Attiva Cloud Shell

Attiva Cloud Shell facendo clic sull'icona a destra della barra di ricerca.

Configurazione dell'ambiente

1. Crea variabili di ambiente correlate al progetto e alle risorse eseguendo i comandi riportati di seguito nel terminale 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. Abilita le API richieste per il 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. Clona il repository

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

3. Configura i bucket Cloud Storage

Crea bucket di archiviazione

Crea bucket Cloud Storage per il caricamento e le miniature per la pipeline di elaborazione delle immagini.

Utilizza il comando gsutil mb e un nome univoco per creare due bucket:

1. Bucket di caricamento in cui verranno caricate prima le immagini
2. Bucket delle miniature per archiviare le immagini in miniatura generate

Crea un bucket per caricare nuove immagini:

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

Output di esempio:

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

Crea un bucket per archiviare le miniature generate:

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

Output di esempio:

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

Aggiorna le autorizzazioni del bucket

Aggiorna le autorizzazioni del bucket di archiviazione per consentire agli utenti di leggere i dati.

Utilizza il comando gsutil iam ch per concedere l'autorizzazione a leggere e scrivere oggetti nel tuo bucket:

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

Avviso: la best practice prevede di limitare l'accesso ai bucket di archiviazione. Ai fini di questo lab, tutti gli utenti potranno visualizzare tutti gli oggetti. Per saperne di più sulla protezione dei bucket di archiviazione, consulta Utilizza l'autorizzazione IAM e le best practice per Cloud Storage.

Output di esempio

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

4. Configura account di servizio

Crea un service account personalizzato per Cloud Functions per elaborare le miniature:

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

Concedi il ruolo artifactregistry.reader per consentire le operazioni di lettura da Artifact Registry:

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

Concedi il ruolo storage.objectCreator per consentire l'archiviazione delle immagini generate nel bucket delle miniature:

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

Concedi il ruolo run.invoker per consentire la chiamata del servizio Cloud Run:

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

Concedi il ruolo eventarc.eventReceiver per consentire la ricezione di eventi dai provider:

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

Concedi il ruolo pubsub.publisher al service account Cloud Storage. In questo modo, il service account potrà pubblicare eventi quando le immagini vengono caricate nel 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. Panoramica della funzione di elaborazione delle immagini

Crea una funzione per scaricare un'immagine da Cloud Storage, ridimensionarla e caricarla di nuovo su Cloud Storage. La funzione chiamerà l'API Vision per assegnare un'etichetta di descrizione all'immagine. La funzione controllerà l'etichetta della descrizione. Se l'etichetta identifica l'immagine come "Cibo", verrà inviato un evento al servizio di menu per aggiornare l'immagine e la miniatura della voce di menu.

Attivazione di una funzione

Le funzioni Cloud Storage si basano sulle notifiche Pub/Sub di Cloud Storage e supportano tipi di eventi simili:

• finalizzazione
• eliminazione
• archiviazione
• aggiornamento dei metadati

In questo lab, eseguirai il deployment e attiverai una funzione quando un oggetto viene finalizzato in Cloud Storage.

Finalizzazione oggetto

Gli eventi di finalizzazione oggetto vengono attivati quando una "scrittura" di un oggetto Cloud Storage viene finalizzata correttamente. In particolare, la creazione di un nuovo oggetto o la sovrascrittura di un oggetto esistente attiva questo evento. Le operazioni di archiviazione e aggiornamento dei metadati vengono ignorate da questo trigger.

6. Integrare Cloud Storage

Cloud Storage è un servizio per l'archiviazione di oggetti in Google Cloud. Un oggetto è un dato immutabile costituito da un file di qualsiasi formato. Gli oggetti vengono memorizzati in container chiamati bucket. Tutti i bucket sono associati a un progetto e puoi raggruppare i tuoi progetti in un'organizzazione. Le librerie client e le API semplificano l'integrazione con Cloud Storage.

In questo lab utilizzerai la libreria client per leggere e scrivere oggetti in Cloud Storage.

Installare la libreria client

Le librerie client di Cloud sono disponibili in molti linguaggi di programmazione comuni. Per iniziare a utilizzare le librerie, devi installare la libreria client.

Utilizzo della libreria client

I dettagli di implementazione dipendono in gran parte dal linguaggio di programmazione. Per utilizzare la libreria client nella tua applicazione, il primo passaggio consiste nell'importare le dipendenze di Cloud Storage. Ad esempio, nel progetto Node.js, le importazioni vengono aggiunte nel file package.json. Lo snippet riportato di seguito mostra l'avviso del file package.json di questo lab.

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

Il file package.json elenca google-cloud/storage come una delle dipendenze dell'applicazione.

La dipendenza google-cloud/functions-framework viene utilizzata per registrare un callback CloudEvent con Functions Framework che verrà attivato dagli eventi Cloud Storage.

La dipendenza google-cloud/vision verrà utilizzata per chiamare l'API Vision per ottenere le annotazioni per le immagini caricate e determinare se si tratta o meno di un alimento.

Registra un callback CloudEvent

Registra un callback CloudEvent con il framework Functions che verrà attivato da Cloud Storage quando una nuova immagine viene caricata nel bucket.

index.js

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

Creazione di un oggetto di riferimento di archiviazione

Dopo aver importato le librerie client, dovrai creare un nuovo client di archiviazione e i bucket con cui interagirà la tua applicazione.

index.js

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

Il codice precedente crea un client di archiviazione denominato "storage" e due riferimenti ai bucket di archiviazione a cui faranno riferimento le variabili "bucket" e "thumbBucket".

Scaricare oggetti Cloud Storage

index.js

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

Utilizzando questo comportamento di download di base, puoi riprendere i download interrotti e utilizzare strategie di download più avanzate, come i download di oggetti suddivisi e i download in streaming.

Caricare oggetti in Cloud Storage

Puoi inviare richieste di caricamento a Cloud Storage in tre modi: caricamento in una singola richiesta, caricamento ripristinabile o caricamento in più parti dell'API XML. Per caricamenti più grandi o caricamenti in streaming, utilizza i caricamenti ripristinabili. Con l'API XML, i file vengono caricati in parti e assemblati come un unico oggetto. Per gli oggetti più piccoli, utilizza i caricamenti con una sola richiesta.

Il codice riportato di seguito carica un'immagine in Cloud Storage utilizzando un caricamento a richiesta singola.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Integrare l'API Vision

Cloud Vision consente agli sviluppatori di integrare facilmente funzionalità di rilevamento visivo nelle applicazioni, tra cui etichettatura delle immagini, riconoscimento facciale e dei punti di riferimento, riconoscimento ottico dei caratteri (OCR) e tagging dei contenuti espliciti.

Installare la libreria client

Le librerie client di Cloud sono disponibili in molti linguaggi di programmazione comuni. Per iniziare a utilizzare le librerie, devi installare la libreria client.

Crea un client Image Annotator

Per accedere alle API di Google utilizzando gli SDK client ufficiali, crea un oggetto di servizio basato sul documento di rilevamento dell'API, che descrive l'API all'SDK. Dovrai recuperarlo dal servizio di rilevamento dell'API Vision utilizzando le tue credenziali.

index.js

const client = new vision.ImageAnnotatorClient();

Per impostazione predefinita, il client esegue l'autenticazione utilizzando il file dell'account di servizio specificato dalla variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

Crea una richiesta API Vision

L'API Vision può eseguire il rilevamento delle funzionalità su un file immagine inviando i contenuti del file immagine come stringa codificata in base64 nel corpo della richiesta.

Per creare una richiesta utilizzando la risorsa immagini per annotare l'immagine. Una richiesta a questa API assume la forma di un oggetto con un elenco di richieste. Ogni voce di questo elenco contiene due informazioni:

• I dati immagine con codifica base64
• Un elenco delle funzionalità che vuoi annotare in merito all'immagine.

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. Esegui il deployment di Cloud Run Functions

Questo servizio di ridimensionamento delle immagini fa parte del sistema più ampio di Cymbal Eats. In questa sezione, eseguirai il deployment solo dei componenti correlati alla funzionalità di elaborazione delle immagini. L'installazione completa incorpora una UI per caricare l'immagine e una richiesta downstream per archiviare i metadati risultanti. Queste funzionalità non sono installate in questo lab.

Durante il deployment della funzione verranno creati i seguenti componenti:

• Cloud Run Functions
• Trigger Eventarc
• Argomento e sottoscrizione Pub/Sub

Nel terminale Cloud Shell, esegui il comando riportato di seguito per eseguire il deployment di Cloud Run Functions con un bucket di trigger su menu-item-uploads-$PROJECT_ID:

Per eseguire il deployment di una funzione Cloud Run direttamente su Cloud Run, devi prima eseguire il deployment della funzione e poi creare un trigger.

Esegui il deployment delle funzioni 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

Output di esempio:

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

Crea il trigger:

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"

Output di esempio:

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.

Se il deployment del trigger non va a buon fine a causa di un problema di autorizzazione, attendi che le modifiche IAM del passaggio precedente vengano propagate. Di solito richiede 1-2 minuti, quindi riprova a eseguire il deployment.

Output di errore di esempio:

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

Nella console Google Cloud, esamina il servizio Cloud Run creato per la funzione:

Nella console Cloud, esamina il trigger Eventarc creato per la funzione:

Nella console Google Cloud, esamina l'argomento e l'abbonamento Pub/Sub creati per il trigger Eventarc:

9. Testare e convalidare la soluzione end-to-end

Carica una nuova foto su Cloud Storage e monitora l'avanzamento della pipeline durante l'analisi delle immagini. Testerai la soluzione end-to-end monitorando i log delle funzioni cloud.

Caricamento di un'immagine

Nota:la foto di Tom Dillon su Unsplash è utilizzabile senza costi ai sensi della licenza Unsplash.

1. Salva questa immagine sul tuo computer locale.
2. Rinomina il file 1.jpg
3. Apri la console Cloud Storage.
4. Fai clic sul bucket menu-item-uploads-....
5. Fai clic su CARICA FILE.
6. Carica 1.jpg nel bucket di archiviazione.
7. Nella console Google Cloud, vai a Cloud Run.
8. Fai clic su process-thumbails.
9. Fai clic sulla scheda LOG.

Nota:la funzione è stata eseguita correttamente e l'immagine è stata caricata nel bucket delle miniature. In base alle etichette dell'API Vision per l'immagine caricata, lo stato della voce di menu verrà impostato su "Pronto". Ciò significa che l'API Vision ha annotato l'immagine come "Cibo".

Poiché il servizio di menu non è stato implementato in questo lab, la richiesta di aggiornamento della voce di menu non è riuscita.

10. Vai al bucket menu-item-thumbnails-$PROJECT_ID Cloud Storage
11. Verifica che l'immagine in miniatura sia stata creata nel bucket delle miniature

Caricamento di un'immagine non alimentare

Per verificare che la funzione funzioni correttamente, caricherai un'immagine che non contiene un oggetto che verrebbe classificato come elemento "Cibo".

Nota: la foto di Insung Yoon su Unsplash è utilizzabile senza costi ai sensi della licenza Unsplash.

1. Salva questa immagine sul tuo computer locale.
2. Rinomina il file 2.jpg
3. Apri la console Cloud Storage.
4. Fai clic sul bucket menu-item-uploads-....
5. Fai clic su CARICA FILE.
6. Carica 2.jpg nel bucket di archiviazione.
7. Nella console Google Cloud, vai a Cloud Run.
8. Fai clic su process-thumbails.
9. Fai clic sulla scheda LOG.

Nota:la funzione è stata eseguita correttamente e l'immagine è stata caricata nel bucket delle miniature. In base alle etichette dell'API Vision per l'immagine caricata, lo stato della voce di menu verrà impostato su "Non riuscito". Ciò significa che l'API Vision non ha annotato l'immagine come "Cibo".

Poiché il servizio di menu non è stato implementato in questo lab, la richiesta di aggiornamento della voce di menu non è riuscita.

10. Complimenti!

Complimenti, hai completato il lab.

Qual è il passaggio successivo?

Esplora altri codelab di Cymbal Eats:

• Attivazione di Cloud Workflows con Eventarc
• Connessione a Private CloudSQL da Cloud Run
• Connessione a database completamente gestiti da Cloud Run
• Proteggi l'applicazione serverless con Identity-Aware Proxy (IAP)
• Attivazione di Cloud Run Jobs con Cloud Scheduler
• Eseguire il deployment in Cloud Run in modo sicuro
• Protezione del traffico in entrata di Cloud Run
• Connessione ad AlloyDB privato da GKE Autopilot

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto

Il modo più semplice per eliminare la fatturazione è eliminare il progetto creato per il tutorial.