Déclencher le traitement des événements depuis Cloud Storage à l'aide d'Eventarc et de Cloud Functions (2e génération)

1. Présentation

Dans cet atelier, vous allez apprendre à utiliser les événements de bucket Cloud Storage et Eventarc pour déclencher le traitement des événements. Vous allez utiliser Cloud Functions (2nd gen) pour analyser des données et traiter des images. La fonction utilisera l'API Vision de Google et enregistrera l'image obtenue dans le bucket Cloud Storage.

Objectifs de l'atelier

Créer un pipeline de traitement d'images

• Configurer les buckets Storage
• Créer une fonction Cloud pour lire et écrire des objets dans Cloud Storage
• Intégrer l'API Vision pour détecter les images d'aliments
• Déployer une fonction Cloud
• Déployer un déclencheur Eventarc
• Tester et valider la solution de bout en bout

Prérequis

• Dans cet atelier, nous considérons que vous connaissez la console Cloud et les environnements de shell.
• Une expérience préalable de l'API Cloud Storage, Cloud Functions ou Vision est utile, mais pas obligatoire.

2. Préparation

Configuration du projet Cloud

1. Connectez-vous à la console Google Cloud, puis créez un projet ou réutilisez un projet existant. (Si vous ne possédez pas encore de compte Gmail ou Google Workspace, vous devez en créer un.)

• Le nom du projet est le nom à afficher pour les participants au projet. Il s'agit d'une chaîne de caractères non utilisée par les API Google. Vous pouvez le modifier à tout moment.
• L'ID du projet est unique parmi tous les projets Google Cloud et non modifiable une fois défini. La console Cloud génère automatiquement une chaîne unique. généralement, vous ne vous souciez pas de ce que c’est. Dans la plupart des ateliers de programmation, vous devrez référencer l'ID du projet (il est généralement identifié comme PROJECT_ID). Si l'ID généré ne vous convient pas, vous pouvez en générer un autre au hasard. Vous pouvez également essayer la vôtre pour voir si elle est disponible. Il ne peut pas être modifié après cette étape et restera actif pendant toute la durée du projet.
• Pour votre information, il existe une troisième valeur, le numéro de projet, utilisé par certaines API. Pour en savoir plus sur ces trois valeurs, consultez la documentation.

Attention:Un ID de projet est unique et ne peut être utilisé par personne d'autre une fois que vous l'avez sélectionné. Vous en êtes le seul utilisateur. Même si un projet est supprimé, l'ID ne peut plus jamais être utilisé

Remarque : Si vous utilisez un compte Gmail, vous pouvez conserver l'emplacement par défaut défini sur Aucune organisation. Si vous utilisez un compte Google Workspace, choisissez un emplacement pertinent pour votre organisation.

2. Vous devez ensuite activer la facturation dans la console Cloud pour utiliser les ressources/API Cloud. L'exécution de cet atelier de programmation est très peu coûteuse, voire sans frais. Pour arrêter les ressources afin d'éviter que des frais ne vous soient facturés au-delà de ce tutoriel, vous pouvez supprimer les ressources que vous avez créées ou l'ensemble du projet. Les nouveaux utilisateurs de Google Cloud peuvent participer au programme d'essai gratuit pour bénéficier d'un crédit de 300 $.

Activer Cloud Shell

Activez Cloud Shell en cliquant sur l'icône située à droite de la barre de recherche.

Configuration de l'environnement

1. Créez un projet et des variables d'environnement liées aux ressources en exécutant les commandes ci-dessous dans le terminal 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. Activer les API requises pour l'atelier

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. Activez les API requises pour l'atelier. (étape spécifique à Qwiklabs)

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

4. Cloner le dépôt

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

3. Configurer des buckets Cloud Storage

Créer des buckets Storage

Créez des buckets Cloud Storage d'importation et de vignettes pour votre pipeline de traitement d'images.

Utilisez la commande gsutil mb et un nom unique pour créer deux buckets:

1. Bucket d'importation dans lequel les images seront importées en premier
2. Bucket de vignettes pour stocker les vignettes générées

Créez un bucket pour importer de nouvelles images:

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

Exemple de résultat :

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

Créez un bucket pour stocker les vignettes générées:

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

Exemple de résultat :

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

Mettre à jour les autorisations du bucket

Mettez à jour les autorisations du bucket de stockage pour accorder des autorisations de lecture aux utilisateurs.

Utilisez la commande "gsutil iam ch" pour autoriser l'accès en lecture et en écriture aux objets de votre bucket:

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

Avertissement: Il est recommandé de limiter l'accès aux buckets de stockage. Pour les besoins de cet atelier, tous les utilisateurs seront autorisés à afficher tous les objets. Pour en savoir plus sur la sécurisation des buckets de stockage, consultez Utiliser l'autorisation IAM et Bonnes pratiques pour Cloud Storage.

Exemple de résultat :

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

4. Configurer des comptes de service

Créez un compte de service personnalisé pour que Cloud Functions traite les vignettes:

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

Accordez le rôle artifactregistry.reader pour autoriser les opérations de lecture à partir d'Artifact Registry:

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

Accordez le rôle storage.objectCreator pour permettre le stockage des images générées dans le bucket de vignettes:

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

Accordez le rôle run.invoker pour autoriser l'appel du service Cloud Run:

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

Accordez le rôle eventarc.eventReceiver pour autoriser la réception d'événements des fournisseurs:

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

Accordez le rôle pubsub.publisher au compte de service Cloud Storage. Cela permettra au compte de service de publier des événements lorsque des images sont importées dans le 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. Présentation de la fonction de traitement des images

Créez une fonction pour télécharger une image à partir de Cloud Storage, redimensionner l'image et la réimporter dans Cloud Storage. La fonction appelle l'API Vision pour attribuer une étiquette de description à l'image. La fonction vérifie le libellé de la description. Si l'étiquette identifie l'image comme "Nourriture" un événement sera envoyé au service de menu pour mettre à jour l'image et la vignette de l'élément de menu.

Déclencher une fonction

Les fonctions Cloud Storage sont basées sur les notifications Pub/Sub de Cloud Storage et acceptent des types d'événements similaires:

• finalisation
• supprimer
• archivage
• mise à jour des métadonnées

Dans cet atelier, vous allez déployer et déclencher une fonction lorsqu'un objet est finalisé dans Cloud Storage.

Finalisation de l'objet

Les événements de finalisation des objets sont déclenchés lorsqu'une opération d'un objet Cloud Storage est correctement finalisée. Cela signifie en particulier que la création d'un objet ou le remplacement d'un objet existant déclenche cet événement. Les opérations d'archivage et de mise à jour des métadonnées sont ignorées par ce déclencheur.

6. Intégrer Cloud Storage

Cloud Storage est un service permettant de stocker vos objets dans Google Cloud. Un objet est une donnée immuable constituée d'un fichier qui peut être de n'importe quel format. Vous stockez des objets dans des conteneurs appelés buckets. Tous les buckets sont associés à un projet, et vous pouvez regrouper vos projets dans une organisation. Les bibliothèques clientes et les API facilitent l'intégration à Cloud Storage

Dans cet atelier, vous utiliserez la bibliothèque cliente pour lire et écrire des objets dans Cloud Storage.

Installer la bibliothèque cliente

Les bibliothèques clientes Cloud sont disponibles dans de nombreux langages de programmation courants. Pour commencer à utiliser les bibliothèques, vous devez installer la bibliothèque cliente.

Utiliser la bibliothèque cliente

Les détails de l'implémentation dépendent globalement du langage de programmation. Pour utiliser la bibliothèque cliente dans votre application, la première étape consiste à importer les dépendances Cloud Storage. Par exemple, dans le projet Node.js, les importations sont ajoutées au fichier package.json. L'extrait ci-dessous montre la notification liée au fichier package.json de cet atelier.

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

Le fichier package.json répertorie google-cloud/storage comme l'une des dépendances de l'application.

La dépendance google-cloud/functions-framework permet d'enregistrer un rappel CloudEvent avec le framework des fonctions qui sera déclenché par des événements Cloud Storage.

La dépendance google-cloud/vision permet d'appeler l'API Vision afin d'obtenir des annotations pour les images importées afin de déterminer s'il s'agit d'un aliment ou non.

Enregistrer un rappel CloudEvent

Enregistrez un rappel CloudEvent avec le framework des fonctions qui est déclenché par Cloud Storage lorsqu'une nouvelle image est importée dans le bucket.

index.js

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

Créer un objet de référence Storage

Une fois les bibliothèques clientes importées, vous devrez créer un client de stockage et des buckets avec lesquels votre application interagira.

index.js

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

Le code ci-dessus crée un client de stockage appelé "storage" et deux références aux buckets de stockage, qui seront référencées par les variables "bucket" et "thumbBucket"

Télécharger des objets Cloud Storage

index.js

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

Ce comportement de base vous permet de reprendre des téléchargements interrompus et d'appliquer des stratégies de téléchargement plus avancées, telles que les téléchargements d'objets segmentés et les téléchargements en streaming.

Importer des objets dans Cloud Storage

Vous pouvez envoyer des requêtes d'importation à Cloud Storage de trois manières: à l'aide d'une requête unique, d'une importation avec reprise ou d'une importation en plusieurs parties via l'API XML. Pour les importations plus volumineuses ou en streaming, utilisez des importations avec reprise. Avec l'API XML, les fichiers sont importés en plusieurs parties et assemblés en un seul objet. Pour les objets plus petits, utilisez les importations de requête simple.

Le code ci-dessous permet d'importer une image dans Cloud Storage à l'aide d'une requête simple d'importation.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Intégrer l'API Vision

Cloud Vision permet aux développeurs d'intégrer facilement des fonctionnalités de détection visuelle dans des applications, comme l'étiquetage d'images, la détection de visages et de points de repère, la reconnaissance optique des caractères (OCR) et l'ajout de tags au contenu explicite.

Installer la bibliothèque cliente

Les bibliothèques clientes Cloud sont disponibles dans de nombreux langages de programmation courants. Pour commencer à utiliser les bibliothèques, vous devez installer la bibliothèque cliente.

Créer un client d'annotation d'images

Pour accéder aux API Google à l'aide des SDK clients officiels, vous devez créer un objet de service basé sur le document de découverte de l'API, qui décrit l'API pour le SDK. Vous devez le récupérer à partir du service de découverte de l'API Vision à l'aide de vos identifiants.

index.js

const client = new vision.ImageAnnotatorClient();

Par défaut, le client s'authentifie à l'aide du fichier de compte de service spécifié par la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

Créer une requête API Vision

L'API Vision peut détecter des caractéristiques sur un fichier image en envoyant le contenu du fichier image sous forme de chaîne encodée en base64 dans le corps de la requête.

Créer une requête à l'aide de la ressource Images afin d'annoter votre image Une requête envoyée à cette API se présente sous la forme d'un objet avec une liste de requêtes. Chaque élément de cette liste contient deux types d’informations :

• les données d'image encodées en base64 ;
• une liste des fonctionnalités que vous souhaitez annoter à propos de cette image.

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. Déployer la fonction Cloud

Ce service de redimensionnement d'images fait partie du système plus vaste Cymbal Eats. Dans cette section, vous allez déployer uniquement les composants associés à la fonctionnalité de traitement d'images. L'installation complète comprend une interface utilisateur permettant d'importer l'image et une requête en aval pour stocker les métadonnées obtenues. Ces fonctionnalités ne sont pas installées dans le cadre de cet atelier.

Les composants suivants seront créés lors du déploiement de la fonction:

• Fonction Cloud
• Service Cloud Run
• Déclencheur Eventarc
• Sujet et abonnement Pub/Sub

Dans le terminal cloudshell, exécutez la commande ci-dessous pour déployer la fonction Cloud avec un bucket de déclenchement sur le 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

Si le déploiement échoue en raison d'un problème d'autorisation sur le bucket de stockage d'importation, veuillez attendre que les modifications IAM de l'étape précédente soient appliquées. Cela prend généralement une à deux minutes, puis relance le déploiement.

Exemple de résultat :

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

Dans la console Cloud, consultez la fonction Cloud créée:

Dans la console Cloud, examinez le service Cloud Run créé pour la fonction:

Dans la console Cloud, examinez le déclencheur Eventarc créé pour la fonction:

Dans la console Cloud, examinez le sujet et l'abonnement Pub/Sub créés pour le déclencheur Eventarc:

9. Tester et valider la solution de bout en bout

Importez une nouvelle photo dans Cloud Storage et surveillez la progression du pipeline pendant l'analyse des images. Vous testerez la solution de bout en bout en surveillant les journaux Cloud Functions.

Importer une image appropriée

Remarque:La photo de Tom Dillon sur Unsplash peut être utilisée sans frais sous la licence Unsplash.

1. Enregistrez cette image sur votre ordinateur local.
2. Renommez le fichier 1.jpg.
3. Ouvrez la console Cloud Storage.
4. Cliquez sur le bucket menu-item-uploads-....
5. Cliquez sur IMPORTER DES FICHIERS.
6. Importer le fichier 1.jpg dans le bucket de stockage
7. Dans la console Cloud, accédez à Cloud Functions.
8. Cliquez sur process-thumbails.
9. Cliquez sur l'onglet JOURNAUX.

Remarque:La fonction a bien été exécutée et a chargé l'image dans le bucket des vignettes. Selon les étiquettes de l'API Vision pour l'image importée, l'état des éléments de menu sera défini sur "Prêt". Cela signifie que l'API Vision a annoté l'image en tant que "Food". Comme nous n'avons pas déployé le service de menu, la requête de mise à jour de l'élément de menu a échoué.

10. Accédez au bucket Cloud Storage menu-item-thumbnails-$PROJECT_ID .
11. Vérifier que l'image de vignette a été créée dans le bucket de vignettes

Importer une image non alimentaire

Pour vérifier que la fonction fonctionne correctement, vous devez importer une image qui ne contient pas d'objet classé dans la catégorie "Aliments". élément.

Remarque: La photo d'Insung Yoon sur Unsplash peut être utilisée sans frais dans le cadre de la licence Unsplash.

1. Enregistrez cette image sur votre ordinateur local.
2. Renommez le fichier 2.jpg.
3. Ouvrez la console Cloud Storage.
4. Cliquez sur le bucket menu-item-uploads-....
5. Cliquez sur IMPORTER DES FICHIERS
6. Importer le fichier 2.jpg dans le bucket de stockage
7. Dans la console Cloud, accédez à Cloud Functions.
8. Cliquez sur process-thumbails.
9. Cliquez sur l'onglet JOURNAUX.

Remarque:La fonction a bien été exécutée et a importé l'image dans le bucket des vignettes. Selon les étiquettes de l'API Vision associées à l'image importée, l'état de l'élément de menu sera défini sur "Échec". Cela signifie que l'API Vision n'a pas annoté l'image en tant que "Food".

Comme le service de menu n'a pas été déployé dans cet atelier, la requête de mise à jour de l'élément de menu a échoué.

10. Félicitations !

Félicitations, vous avez terminé l'atelier !

Étapes suivantes :

Découvrez d'autres ateliers de programmation Cymbal Eats:

• Déclencher Cloud Workflows avec Eventarc
• Se connecter au service Cloud SQL privé depuis Cloud Run
• Se connecter à des bases de données entièrement gérées depuis Cloud Run
• Sécuriser une application sans serveur avec Identity-Aware Proxy (IAP)
• Déclencher des jobs Cloud Run avec Cloud Scheduler
• Déployer une application sur Cloud Run en toute sécurité
• Sécuriser le trafic d'entrée Cloud Run
• Se connecter à une instance privée AlloyDB depuis GKE Autopilot

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez chaque ressource individuellement.

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.