Présentation

Cloud Run Functions peut étendre vos applications et services en s'intégrant à des bases de données Google Cloud, à savoir Firestore, Cloud Spanner, Cloud SQL et Cloud Bigtable, ainsi qu'à Memorystore, le service de mise en cache de datastore en mémoire de Google Cloud.

Dans cet atelier, vous allez créer des fonctions Cloud Run qui s'intègrent à Firestore, la base de données de documents NoSQL sans serveur de Google Cloud. Vous créerez des fonctions à l'aide du framework Cloud Run Functions et de la bibliothèque cliente Firestore pour Node.js. Vous configurerez également des déclencheurs pour les exécuter lorsque des événements se produiront dans la base de données.

Le cycle de vie d'une fonction Firestore implique généralement les étapes suivantes :

• Elle attend que des modifications soient apportées à un document donné dans la base de données Firestore.
• Elle se déclenche lorsqu'un événement se produit.
• Elle effectue des tâches à l'aide d'un objet de données qui est reçu avec un instantané du document concerné.

Objectifs

Au cours de cet atelier, vous allez :

• configurer une base de données Firestore ;
• développer et déployer une fonction basée sur des événements pour consigner des informations lorsqu'un document est créé dans Firestore ;
• développer et déployer une fonction basée sur des événements pour mettre à jour le contenu d'un document ;
• accéder à des secrets et les utiliser avec Cloud Run Functions ;
• utiliser la console Google Cloud pour afficher les journaux générés par votre fonction.

Préparation

Avant de cliquer sur le bouton "Démarrer l'atelier"

Cet atelier pratique Google Skills vous permet de suivre vous-même les activités dans un véritable environnement cloud, et non dans un environnement de simulation ou de démonstration. Nous vous fournissons des identifiants temporaires pour vous connecter à Google Cloud le temps de l'atelier.

Ce dont vous avez besoin

Pour réaliser cet atelier, vous devez :

• avoir accès à un navigateur Internet standard (nous vous recommandons d'utiliser Chrome) ;
• disposer de suffisamment de temps pour effectuer l'atelier en une fois.

Activer Google Cloud Shell

Google Cloud Shell est une machine virtuelle qui contient de nombreux outils pour les développeurs. Elle comprend un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud.

Google Cloud Shell vous permet d'accéder à vos ressources Google Cloud grâce à une ligne de commande.

1. Dans la barre d'outils située en haut à droite dans la console Cloud, cliquez sur le bouton "Ouvrir Cloud Shell".

   

2. Cliquez sur Continuer.

Le provisionnement et la connexion à l'environnement prennent quelques instants. Une fois connecté, vous êtes en principe authentifié et le projet est défini sur votre ID_PROJET. Par exemple :

gcloud est l'outil de ligne de commande pour Google Cloud. Il est préinstallé sur Cloud Shell et permet la complétion par tabulation.

• Vous pouvez lister les noms des comptes actifs à l'aide de cette commande :

Résultat :

Exemple de résultat :

• Vous pouvez lister les ID de projet à l'aide de cette commande :

Résultat :

Exemple de résultat :

Tâche 1 : Configurer l'environnement

Dans cette tâche, vous allez configurer des variables d'environnement et activer les API de service nécessaires pour réaliser cet atelier.

Définir des variables d'environnement

Avant de créer des fonctions Cloud Run, vous devez définir des variables d'environnement.

1. Connectez-vous à la console Google Cloud avec les identifiants qui vous ont été attribués pour cet atelier et ouvrez la fenêtre du terminal Cloud Shell.

2. Exécutez la commande suivante dans Cloud Shell pour définir les variables d'environnement PROJECT_ID et REGION.

   PROJECT_ID=$(gcloud config get-value project) REGION={{{project_0.default_region|set at lab start}}}

3. Définissez une variable d'environnement pour le numéro de projet :

   PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" \ --format="value(projectNumber)")

4. Définissez la région par défaut pour Cloud Run Functions :

   gcloud config set functions/region {{{project_0.default_region|set at lab start}}}

Activer les API

1. Pour activer les API de service nécessaires à cet atelier, exécutez la commande suivante :

   gcloud services enable \ artifactregistry.googleapis.com \ cloudfunctions.googleapis.com \ cloudbuild.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ logging.googleapis.com \ storage.googleapis.com \ pubsub.googleapis.com

Tâche 2 : Configurer Firestore

Pour effectuer les tâches de cet atelier, vous devez configurer une base de données Firestore. Firestore stocke les données sous forme de documents et de collections. Pour utiliser Cloud Run Functions avec Firestore, vous devez configurer Firestore avant de déployer les fonctions.

1. Dans la console Google Cloud, cliquez sur la barre de recherche dans la navigation supérieure et saisissez Firestore. Sélectionnez Firestore dans les résultats de recherche.

2. Cliquez sur Créer une base de données Firestore.

3. Sélectionnez Édition Standard.

4. Sous "Options de configuration", sélectionnez Firestore en mode natif.

5. Pour les règles de sécurité, choisissez Ouvrir.

6. Dans "Type d'emplacement", cliquez sur Région, puis sélectionnez la région d'atelier set at lab start dans la liste.

   Remarque : Si la liste des régions n'est pas renseignée, actualisez le navigateur ou relancez l'assistant depuis le menu de la console Cloud.

7. Conservez les autres paramètres par défaut, puis cliquez sur Créer une base de données.

Cliquez sur Vérifier ma progression pour valider l'objectif. Configurer Firestore.

Tâche 3 : Développer une fonction basée sur des événements pour les nouveaux documents Firestore

Une fois la base de données Firestore créée, vous pouvez développer le code de votre fonction. Dans cette tâche, vous allez écrire le code source de la fonction qui répond à la création de documents dans la base de données. La fonction consigne des informations sur les données reçues lors de son appel.

Configurer votre répertoire de travail

Les fonctions de Firestore sont appelées avec une structure de données cloudevents qui peut être décodée à l'aide de Protocol Buffers avec le module NPM protobuf.js. Pour en savoir plus, consultez les liens fournis à la fin de l'atelier.

1. Pour copier les fichiers .proto et de dépendance requis depuis Cloud Storage et extraire le contenu de l'archive, exécutez la commande suivante :

   gcloud storage cp gs://cloud-training/CBL493/firestore_functions.zip . && unzip firestore_functions && rm firestore_functions.zip

2. Accédez au répertoire firestore_functions :

   cd firestore_functions

   Le répertoire firestore_functions contient également des fichiers node.js et package.json vides que vous allez modifier dans la sous-tâche suivante.

Écrire le code de la fonction

1. Dans la barre d'outils Cloud Shell, cliquez sur Ouvrir l'éditeur.

   Vous pouvez passer de Cloud Shell à l'éditeur de code et vice versa en cliquant sur Ouvrir l'éditeur et Ouvrir le terminal selon le cas. Vous pouvez également cliquer sur Ouvrir dans une nouvelle fenêtre pour laisser l'éditeur ouvert dans un autre onglet.

2. Dans l'éditeur, ajoutez le code suivant au fichier firestore_functions/index.js :

   /** * Cloud Event Function triggered by a change to a Firestore document. */ const functions = require('@google-cloud/functions-framework'); const protobuf = require('protobufjs'); functions.cloudEvent('newCustomer', async cloudEvent => { console.log(`Function triggered by event on: ${cloudEvent.source}`); console.log(`Event type: ${cloudEvent.type}`); console.log('Loading protos...'); const root = await protobuf.load('data.proto'); const DocumentEventData = root.lookupType('google.events.cloud.firestore.v1.DocumentEventData'); console.log('Decoding data...'); const firestoreReceived = DocumentEventData.decode(cloudEvent.data); console.log('\nNew document:'); console.log(JSON.stringify(firestoreReceived.value, null, 2)); const documentData = firestoreReceived.value.fields; console.log('Document data:', documentData); }); Le code utilise la bibliothèque Node.js du framework des fonctions pour créer une fonction qui traite les données transmises à l'aide de la spécification cloudEvent.

3. Dans l'éditeur, ajoutez le contenu ci-dessous au fichier firestore_functions/package.json :

   { "name": "firestore_functions", "version": "0.0.1", "main": "index.js", "dependencies": { "@google-cloud/functions-framework": "^3.1.3", "protobufjs": "^7.2.2", "@google-cloud/firestore": "^6.0.0" } }

Modifier les autorisations du compte de service

Accordez certaines autorisations à l'agent de service Cloud Run Functions avant de déployer la fonction. Exécutez les commandes suivantes dans Cloud Shell.

1. Cliquez sur Ouvrir le terminal.

2. Définissez une variable d'environnement pour le compte de service de l'agent de service Cloud Run Functions :

   SERVICE_ACCOUNT=service-$PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com

3. Pour afficher et récupérer des artefacts depuis Artifact Registry, attribuez le rôle artifactregistry.reader au compte de service Cloud Run Functions :

   gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:$SERVICE_ACCOUNT --role roles/artifactregistry.reader Remarque : Si vous recevez un message d'erreur lors de l'étape précédente indiquant que le compte de service n'existe pas ou que la requête contient des identifiants d'authentification non valides, procédez comme indiqué ci-dessous.

4. Désactivez l'API Cloud Functions :

   gcloud services disable cloudfunctions.googleapis.com

5. Réactivez l'API Cloud Functions :

   gcloud services enable cloudfunctions.googleapis.com

6. Patientez quelques secondes, puis réexécutez la commande pour attribuer le rôle artifactregistry.reader au compte de service Cloud Run Functions :

   gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:$SERVICE_ACCOUNT --role roles/artifactregistry.reader

Déployer la fonction

• Pour déployer la fonction, exécutez la commande suivante dans Cloud Shell :

  gcloud functions deploy newCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=newCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.created \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}' Firestore accepte les événements created, updated, deleted et written que vous spécifiez comme option trigger-event-filter pour la commande deploy. Le format de chemin d'accès indique que tous les documents de la collection customers doivent être surveillés.

  Une fois la commande exécutée, l'URL du point de terminaison de la fonction est générée, comme indiqué dans cet exemple de résultat partiel de la commande :

  ... state: ACTIVE updateTime: '2024-03-19T21:38:04.917134057Z' url: https://{{{project_0.default_region|set at lab start}}}-{{{project_0.default_region}}}.cloudfunctions.net/newCustomer Si vous recevez un message d'erreur lorsque vous déployez la fonction, patientez quelques minutes avant de relancer la commande deploy. La propagation des autorisations du compte de service pour Eventarc peut prendre un certain temps.

Tester la fonction

1. Accédez à Firestore Studio dans la console Cloud.

2. Pour créer une collection de documents, cliquez sur Commencer une collection.

3. Dans le champ ID de collection, saisissez customers.

4. Pour générer un ID pour un document de cette collection, cliquez sur ID du document.

5. Pour ce document, ajoutez un champ avec les valeurs suivantes :

   Nom du champ	Type de champ	Valeur du champ
   firstname	string	Lucas

6. Cliquez sur Enregistrer.

7. Pour vérifier que votre fonction Cloud Run a bien été appelée, accédez au menu de navigation () et cliquez sur Cloud Run.

8. Cliquez sur le nom de la fonction newCustomer.

9. Cliquez sur Journaux.

10. Vérifiez que les entrées de journal générées à partir du code de la fonction sont présentes et affichent les données du document de base de données que vous avez créé.

    Vous devrez peut-être cliquer sur Actualiser pour afficher les dernières entrées de journal.

Cliquez sur Vérifier ma progression pour valider l'objectif. Développer une fonction basée sur des événements pour les nouveaux documents Firestore

Tâche 4 : Développer une fonction basée sur des événements pour Firestore afin de mettre à jour un document

Dans cette tâche, vous allez développer une fonction qui est déclenchée lorsqu'un document est mis à jour dans la base de données Firestore. Votre fonction ajoute un champ au document avec une valeur dérivée des valeurs de certains des autres champs du document.

Écrire le code de la fonction

1. Dans l'éditeur, ajoutez le code ci-dessous au fichier firestore_functions/index.js :

   const Firestore = require('@google-cloud/firestore'); const firestore = new Firestore({ projectId: process.env.GOOGLE_CLOUD_PROJECT, }); functions.cloudEvent('updateCustomer', async cloudEvent => { console.log('Loading protos...'); const root = await protobuf.load('data.proto'); const DocumentEventData = root.lookupType( 'google.events.cloud.firestore.v1.DocumentEventData' ); console.log('Decoding data...'); const firestoreReceived = DocumentEventData.decode(cloudEvent.data); const resource = firestoreReceived.value.name; const affectedDoc = firestore.doc(resource.split('/documents/')[1]); // Fullname already exists, so don't update again to avoid infinite loop. if (firestoreReceived.value.fields.hasOwnProperty('fullname')) { console.log('Fullname is already present in document.'); return; } if (firestoreReceived.value.fields.hasOwnProperty('lastname')) { const lname = firestoreReceived.value.fields.lastname.stringValue; const fname = firestoreReceived.value.fields.firstname.stringValue; const fullname = `${fname} ${lname}` console.log(`Adding fullname --> ${fullname}`); await affectedDoc.update({ fullname: fullname }); } }); Vous pouvez définir plusieurs fonctions ayant leurs propres points d'entrée dans le même fichier main du projet et les déployer séparément dans Cloud Run Functions.

   Avec cette approche, toutes les fonctions peuvent partager le même ensemble de dépendances, même si certaines d'entre elles n'en ont pas besoin.

   Pour limiter le nombre de dépendances nécessaires à une fonction donnée et réduire ses besoins en mémoire, il est recommandé de conserver le code source de chaque fonction dans son propre répertoire de premier niveau, avec ses propres fichiers de configuration de projet.

Déployer la fonction

1. Pour déployer la nouvelle fonction, exécutez la commande suivante dans Cloud Shell :

   gcloud functions deploy updateCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=updateCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.updated \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}'

2. Vérifiez que le résultat de la commande indique que la fonction a été déployée et que son état est Active.

Tester la fonction

1. Dans la console Cloud, accédez à Firestore Studio et sélectionnez les documents existants de la collection customers dont le champ firstname est défini sur Lucas.

2. Pour ce document, cliquez sur Ajouter un champ.

3. Ajoutez un champ avec les valeurs suivantes :

   Nom du champ	Type de champ	Valeur du champ
   lastname	string	Sherman

4. Cliquez sur Enregistrer.

5. Patientez quelques secondes, puis vérifiez que le nouveau champ fullname a bien été ajouté au document.

   Cela indique que votre fonction updateCustomer a été appelée lors de la mise à jour du document.

6. Pour vérifier que votre fonction Cloud Run a bien été appelée, accédez au menu de navigation (), puis cliquez sur Cloud Run.

7. Cliquez sur le nom de la fonction updateCustomer.

8. Cliquez sur Journaux.

9. Vérifiez que les entrées de journal générées à partir du code de la fonction sont présentes et indiquent que le champ fullname a été ajouté au document.

   Vous devrez peut-être cliquer sur Actualiser pour afficher les dernières entrées de journal.

Cliquez sur Vérifier ma progression pour valider l'objectif. Développer une fonction basée sur des événements pour Firestore afin de mettre à jour un document

Tâche 5 : Utiliser des secrets avec Cloud Run Functions

Secret Manager est un service Google Cloud qui stocke de manière sécurisée des données telles que des clés API, des mots de passe, des certificats, des identifiants et d'autres informations sensibles. Vous pouvez ensuite accéder à ces secrets depuis Cloud Run Functions ou d'autres services pour les utiliser dans votre logique de fonction ou implémentation de service.

Dans cette tâche, vous allez créer et stocker un identifiant en tant que secret dans Secret Manager. Vous allez développer une fonction pour accéder à la clé dans votre logique de fonction.

Créer un secret

1. Pour créer et utiliser des secrets, exécutez la commande suivante dans Cloud Shell et activez l'API Secret Manager :

   gcloud services enable secretmanager.googleapis.com

2. Créez et stockez un secret nommé api-cred avec la valeur secret_api_key dans Secret Manager :

   echo -n "secret_api_key" | gcloud secrets create api-cred --replication-policy="automatic" --data-file=- L'option "replication-policy" permet de déterminer les régions utilisées pour stocker les secrets et leurs versions. Pour spécifier une ou plusieurs régions dans lesquelles un secret peut être répliqué, vous pouvez définir cette option sur user-managed.

Accorder l'accès

Pour accéder à un secret, le compte de service d'exécution de votre fonction doit disposer d'un accès au secret.

• Cloud Run Functions utilise le compte de service Compute Engine par défaut comme compte de service d'exécution de la fonction si vous ne modifiez pas cette option.

  Pour l'authentification auprès de Secret Manager, accordez le rôle Accesseur de secrets Secret Manager au compte de service Compute Engine par défaut :

  gcloud secrets add-iam-policy-binding api-cred --member=serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com --project=$PROJECT_ID --role='roles/secretmanager.secretAccessor' Remarque : Pour une utilisation en production, vous devez configurer votre fonction afin qu'elle s'authentifie à l'aide de son propre compte de service géré par l'utilisateur, disposant de l'ensemble de rôles le moins permissif nécessaire pour accomplir les tâches de cette fonction.

Accéder au secret depuis votre fonction

Dans cette sous-tâche, vous allez modifier la fonction newCustomer développée précédemment pour accéder au secret.

• Dans l'éditeur, ajoutez le code ci-dessous à la fonction newCustomer dans le fichier index.js. Ajoutez le code à la fin, après la dernière instruction console.log dans le corps de la fonction :

  // BEGIN access a secret const fs = require('fs/promises'); try { const secret = await fs.readFile('/etc/secrets/api_cred/latest', { encoding: 'utf8' }); // use the secret. For lab testing purposes, we log the secret. console.log('secret: ', secret); } catch (err) { console.log(err); } // End access a secret Le code de la fonction lit la valeur du secret à partir d'un fichier installé sur un volume accessible à la fonction. Vous configurerez cette méthode d'accès au secret lorsque vous déploierez la fonction à l'étape suivante.

Redéployer la fonction

1. Dans Cloud Shell, redéployez la fonction newCustomer avec le secret :

   gcloud functions deploy newCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=newCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.created \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}' \ --set-secrets '/etc/secrets/api_cred/latest=api-cred:latest' L'option set-secrets de la commande deploy spécifie le chemin d'installation /etc/secrets/api_cred et le chemin d'accès au secret /latest.

   En référençant un secret en tant que volume, vous permettez à votre fonction d'accéder à la dernière valeur du secret dans Secret Manager chaque fois que le fichier est lu à partir du disque.

   Votre fonction peut également accéder à une version spécifique de la valeur du secret en tant que variable d'environnement. Pour en savoir plus, consultez la documentation sur l'utilisation de secrets avec Cloud Run Functions.

2. Une fois la fonction déployée, vérifiez qu'elle a accès au secret :

   gcloud functions describe newCustomer

   Le résultat de la commande describe inclut des informations sur le secret. Voici une partie du résultat de la commande :

   ... secretVolumes: - mountPath: /etc/secrets/api_cred projectId: '{{{project_0.project_id|Project_ID}}}' secret: api-cred versions: - path: /latest version: latest ...

Tester la fonction

1. Pour tester la fonction, répétez le test de la tâche précédente pour ajouter un nouveau document client à partir de Firestore Studio dans la console Cloud.

2. Pour afficher les journaux de la fonction dans la console Cloud, accédez au menu de navigation (), puis cliquez sur Cloud Run.

3. Cliquez sur le nom de la fonction newCustomer.

4. Pour afficher les journaux de la fonction, cliquez sur Journaux.

   Vérifiez que l'entrée permettant de consigner la valeur de la clé secrète est présente :

   secret: secret_api_key Remarque : La valeur des secrets n'est pas consignée en général, mais cette étape permet de confirmer que la fonction a accès à la valeur et peut donc utiliser le secret dans son code.

Cliquez sur Vérifier ma progression pour valider l'objectif. Utiliser des secrets avec Cloud Run Functions

Félicitations !

Dans cet atelier, vous avez configuré une base de données Firestore et développé une fonction Cloud basée sur des événements qui se déclenche lorsqu'un document est créé dans la base de données. Vous avez également développé une fonction permettant d'ajouter un champ à un document lorsque ce dernier est mis à jour. Vous avez aussi créé un secret et y avez accédé à partir d'une fonction Cloud Run, et utilisé des journaux pour vérifier la valeur du secret.

Étapes suivantes et informations supplémentaires

Pour en savoir plus sur Cloud Run Functions pour Firestore et sur d'autres sujets, consultez la documentation :

• Déclencheurs Firestore
• Protocol Buffers
• Cloud Functions for Firebase

Copyright 2026 Google LLC Tous droits réservés. Google et le logo Google sont des marques de Google LLC. Tous les autres noms de société et de produit peuvent être des marques des sociétés auxquelles ils sont associés.