Attivazione dell'elaborazione degli eventi da Cloud Storage utilizzando Eventarc e Cloud Functions (2a gen.)

1. Panoramica

In questo lab imparerai a utilizzare gli eventi del bucket Cloud Storage e Eventarc per attivare l'elaborazione degli eventi. Utilizzerai Cloud Functions (2a gen.) 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 bucket Storage
• Crea una funzione Cloud Functions per leggere e scrivere oggetti in Cloud Storage
• Integra l'API Vision per rilevare immagini degli alimenti
• Esegui il deployment di una funzione Cloud Functions
• Esegui il deployment di un trigger Eventarc
• Testa e convalida la soluzione end-to-end

Prerequisiti

• Questo lab presuppone la conoscenza della console Cloud e degli ambienti shell.
• La precedente esperienza con Cloud Storage, Cloud Functions 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 progetto è il nome visualizzato dei partecipanti del progetto. Si tratta di una stringa di caratteri non utilizzata dalle API di Google. Puoi aggiornarla in qualsiasi momento.
• L'ID progetto è univoco in 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 importa cosa sia. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere è identificato come PROJECT_ID). Se l'ID generato non ti soddisfa, puoi generarne un altro casuale. In alternativa, puoi provarne una personalizzata per verificare se è disponibile. Non può essere modificato dopo questo passaggio e rimarrà per tutta la durata del progetto.
• Per informazione, c'è 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 nessun altro utente dopo essere stato selezionato. Sei l'unico utente di quell'ID. Anche se un progetto viene eliminato, l'ID non può più 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 località adatta alla tua organizzazione.

2. Successivamente, dovrai abilitare la fatturazione nella console Cloud per utilizzare risorse/API Cloud. Eseguire questo codelab non dovrebbe costare molto. Per arrestare le risorse in modo da non incorrere in fatturazione oltre questo tutorial, puoi eliminare le risorse che hai creato o eliminare l'intero 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 un progetto e variabili di ambiente relative alle risorse eseguendo i comandi seguenti 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=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. Abilita le API richieste per il lab. (passaggio specifico per Qwiklabs)

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

4. clona il repository

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

3. Configura i bucket Cloud Storage

Creazione di bucket di archiviazione

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

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

1. Carica il bucket in cui verranno caricate per prime le immagini
2. Bucket delle miniature per archiviare le miniature 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 in cui 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 autorizzazioni bucket

Aggiorna le autorizzazioni del bucket di archiviazione per concedere le autorizzazioni di lettura agli utenti.

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: si consiglia 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 Autorizzazione IAM e 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 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 al 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 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, ridimensiona l'immagine e caricala nuovamente in Cloud Storage. La funzione chiama 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 del menù per aggiornare l'immagine e la miniatura dell'elemento del menù.

Attivazione di una funzione

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

• finalizzare
• elimina
• archivio
• 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 viene eseguito un di un oggetto Cloud Storage è stato finalizzato correttamente. In particolare, questo evento viene attivato dalla creazione di un nuovo oggetto o dalla sovrascrittura di un oggetto esistente. Le operazioni di aggiornamento di archiviazione e metadati vengono ignorate da questo attivatore.

6. Integra 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 effettuano 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 dei linguaggi di programmazione più diffusi. Per iniziare a utilizzare le librerie, devi installare la libreria client.

Utilizzo della libreria client

I dettagli dell'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 seguente mostra la notifica relativa al 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 indica 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 di Functions che verrà attivato dagli eventi di Cloud Storage.

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

Registra un callback CloudEvent

Registra un callback CloudEvent con il framework delle funzioni che viene 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 Storage

Dopo aver importato le librerie client, devi creare un nuovo client di archiviazione e i bucket con cui l'applicazione interagirà.

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 chiamato "storage" e due riferimenti ai bucket di archiviazione a cui le variabili "bucket" faranno riferimento e "thumbBucket"

Scarica 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 il download di oggetti segmentati e i download in streaming.

Carica oggetti in Cloud Storage

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

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

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Integra API Vision

Cloud Vision consente agli sviluppatori di integrare facilmente le 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 dei linguaggi di programmazione più diffusi. 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, devi creare 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.

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 bit di informazioni:

• I dati immagine con codifica Base64
• Un elenco di funzionalità che vuoi annotare su quell'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 della funzione Cloud Functions

Questo servizio di ridimensionamento delle immagini fa parte del sistema più ampio Cymbal Eats. In questa sezione eseguirai il deployment solo dei componenti relativi alla funzionalità di elaborazione delle immagini. L'installazione completa incorpora un'interfaccia utente per caricare l'immagine e una richiesta downstream per l'archiviazione dei metadati risultanti. Queste funzionalità non sono installate nell'ambito di questo lab.

Durante il deployment della funzione verranno creati i seguenti componenti:

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

Nel terminale Cloudshell, esegui il comando seguente per eseguire il deployment della funzione Cloud Functions con un bucket di trigger su 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

Se il deployment non riesce a causa di un problema di autorizzazione sul bucket di archiviazione caricato, attendi la propagazione delle modifiche IAM del passaggio precedente. In genere sono necessari 1-2 minuti e poi riprova a eseguire il deployment.

Output di esempio

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

Nella console Cloud, rivedi la funzione Cloud Functions creata:

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

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

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

9. Testa e convalida la soluzione end-to-end

Carica una nuova foto in Cloud Storage e monitora l'avanzamento della pipeline man mano che le immagini vengono analizzate. Testerai la soluzione end-to-end monitorando i log di Cloud Functions.

Caricare un'immagine appropriata

Nota: l'utilizzo della foto di Tom Dillon su Unsplash è senza costi in base alla licenza di Unsplash

1. Salva questa immagine sulla tua macchina locale
2. Rinomina il file come 1.jpg.
3. Apri la console di 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 Functions.
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 della voce di menu verrà impostato su "Pronto". Ciò significa che l'API Vision ha annotato l'immagine come "Alimenti". Poiché non abbiamo eseguito il deployment del servizio del menu, la richiesta di aggiornamento della voce del 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

Caricare un'immagine non commestibile

Per verificare che la funzione funzioni correttamente, devi caricare un'immagine che non contiene un oggetto che verrebbe classificato come "Cibo" molto utile.

Nota: l'utilizzo della foto di Insung Yoon su Unsplash è consentito in base alla licenza di Unsplash.

1. Salva questa immagine sulla tua macchina locale
2. Rinomina il file come 2.jpg.
3. Apri la console di 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 Functions.
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 della voce di menu verrà impostato su "Non riuscito". Ciò significa che l'API Vision non ha annotato l'immagine come "cibo".

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

10. Complimenti!

Congratulazioni, hai terminato il lab.

Passaggi successivi

Esplora altri codelab di Cymbal Eats:

• Attivazione di Cloud Workflows con Eventarc
• Connessione a Cloud SQL privato da Cloud Run
• Connessione a database completamente gestiti da Cloud Run
• Applicazione serverless sicura con Identity-Aware Proxy (IAP)
• Attivazione di job Cloud Run con Cloud Scheduler
• Deployment sicuro su Cloud Run
• Protezione del traffico in entrata di Cloud Run
• Connessione ad AlloyDB privata 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 è quello di eliminare il progetto che hai creato per il tutorial.