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 dei bucket Cloud Storage e Eventarc per attivare l'elaborazione degli eventi. Utilizzerai le funzioni Cloud Run 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
• Creare funzioni Cloud Run per leggere e scrivere oggetti in Cloud Storage
• Esegui il deployment di un trigger Eventarc
• Integrare l'API Vision per rilevare le immagini di cibo
• Testa e convalida 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 al progetto. Si tratta di una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarlo.
• L'ID progetto è univoco per tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo essere stato impostato). La console Cloud genera automaticamente una stringa univoca; di solito non ti interessa quale sia. Nella maggior parte dei codelab, dovrai fare riferimento al tuo ID progetto (in genere identificato come PROJECT_ID). Se l'ID generato non ti piace, puoi generarne un altro casuale. In alternativa, puoi provare il tuo e vedere se è disponibile. Non può essere modificato dopo questo passaggio e rimane invariato per tutta la durata del progetto.
• Per tua informazione, esiste un terzo valore, un Numero 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 la selezione. Sei l'unico utente di quell'ID. Anche se un progetto viene eliminato, l'ID non può essere riutilizzato

Nota:se utilizzi un account Gmail, puoi lasciare l'impostazione predefinita su Nessuna organizzazione. Se utilizzi un account Google Workspace, scegli una località adatta alla tua organizzazione.

2. Successivamente, dovrai abilitare la fatturazione nella console Cloud per utilizzare le API/risorse Cloud. La partecipazione a questo codelab non ha costi, o quasi. Per arrestare le risorse ed evitare di incorrere in fatturazione al termine di questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud sono idonei al 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 relative a progetti e 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. Configurare i bucket Cloud Storage

Creare 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 per prime le immagini
2. Bucket 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 le autorizzazioni di lettura.

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: è buona prassi limitare l'accesso ai bucket di archiviazione. Ai fini di questo lab, a tutti gli utenti sarà consentito visualizzare tutti gli oggetti. Per ulteriori informazioni sulla protezione dei bucket di archiviazione, consulta Utilizzare le autorizzazioni 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 account di servizio personalizzato per la funzione Cloud che elabora 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 lo stoccaggio 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 l'invocazione 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 fornitori:

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 all'account di servizio Cloud Storage. In questo modo, l'account di servizio potrà pubblicare gli 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 ricaricarla 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 dell'elemento del menu.

Attivazione di una funzione

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

• finalize
• elimina
• archive
• 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 degli oggetti vengono attivati quando una "scrittura" di un oggetto Cloud Storage viene completata correttamente. In particolare, questo significa che la creazione di un nuovo oggetto o la sovrascrittura di un oggetto esistente attiva questo evento. Le operazioni di aggiornamento dell'archivio e dei metadati vengono ignorate da questo attivatore.

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 larga misura 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 la notifica 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 il framework Functions che verrà attivato dagli eventi Cloud Storage.

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

Registra un callback CloudEvent

Registra un callback CloudEvent con il Functions Framework che verrà attivato da Cloud Storage quando viene caricata una nuova immagine 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 allo spazio 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 riportato sopra 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
        });

Con 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 con una singola richiesta, caricamento parziale riavviabile o API XML. Per caricamenti di dimensioni maggiori o caricamenti in streaming, utilizza i caricamenti ripristinabili. Con le API XML, i file vengono caricati in parti e assemblati come un singolo oggetto. Per gli oggetti più piccoli, utilizza i caricamenti con una singola richiesta.

Il codice seguente carica un'immagine in Cloud Storage utilizzando un caricamento con una singola richiesta.

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, rilevamento di volti e 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.

Creare un client di annotazione delle immagini

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

index.js

const client = new vision.ImageAnnotatorClient();

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

Creare una richiesta all'API Vision

L'API Vision può eseguire il rilevamento di elementi in 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 images per annotare l'immagine. Una richiesta a questa API ha la forma di un oggetto con un elenco di richieste. Ogni elemento di questo elenco contiene due informazioni:

• I dati immagine con codifica base64
• Un elenco di elementi che vuoi annotare nell'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ù grande di Cymbal Eats. In questa sezione eseguirai il deployment solo dei componenti relativi alla funzionalità di elaborazione delle immagini. L'installazione completa include un'interfaccia utente per caricare l'immagine e una richiesta a valle per archiviare i metadati risultanti. Queste funzionalità non vengono installate nell'ambito di questo lab.

Durante il deployment della funzione verranno creati i seguenti componenti:

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

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

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

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 l'attivatore:

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 dell'attivatore non va a buon fine a causa di un problema di autorizzazione, attendi la propagazione delle modifiche IAM del passaggio precedente. Di solito sono necessari 1-2 minuti, quindi riprova a eseguire il deployment.

Esempio di output di errore:

...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 Cloud, controlla il servizio Cloud Run creato per la funzione:

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

Nella console Cloud, controlla l'argomento e l'abbonamento Pub/Sub creati per l'attivatore Eventarc:

9. Testa e convalida 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 è di uso 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. In Cloud Console, vai a Cloud Run.
8. Fai clic su process-thumbails.
9. Fai clic sulla scheda LOG.

Nota:la funzione è stata eseguita correttamente e ha caricato l'immagine nel bucket delle miniature. In base alle etichette dell'API Vision per l'immagine caricata, lo stato dell'elemento del 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 dell'elemento del menu non è andata a buon fine.

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

Caricamento di un'immagine non correlata a prodotti alimentari

Per verificare il corretto funzionamento della funzione, devi caricare un'immagine che non contenga un oggetto che potrebbe essere classificato come elemento "Cibo".

Nota: la foto di Insung Yoon su Unsplash è di uso 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. In Cloud Console, vai a Cloud Run.
8. Fai clic su process-thumbails.
9. Fai clic sulla scheda LOG.

Nota:la funzione è stata eseguita correttamente e ha caricato l'immagine nel bucket delle miniature. In base alle etichette dell'API Vision per l'immagine caricata, lo stato dell'elemento del 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 dell'elemento del menu non è andata a buon fine.

10. Complimenti!

Complimenti, hai completato il lab.

Passaggi successivi

Esplora altri codelab di Cymbal Eats:

• Attivazione dei flussi di lavoro cloud con Eventarc
• Connessione a Private CloudSQL da Cloud Run
• Connessione ai database completamente gestiti da Cloud Run
• Proteggi un'applicazione serverless con Identity-Aware Proxy (IAP)
• Attivazione di job Cloud Run con Cloud Scheduler
• Eseguire il deployment in sicurezza in Cloud Run
• 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 che hai creato per il tutorial.