Premiers pas : écrire, tester et déployer vos premières fonctions

Pour commencer à utiliser Cloud Functions, essayez de suivre ce tutoriel. Il commence par les tâches de configuration requises, puis explique comment créer, tester, et déployer deux fonctions associées :

• Une fonction "add message" (ajouter un message) qui expose une URL acceptant une valeur de texte et l'écrit dans Cloud Firestore.
• Une fonction "make uppercase" (mettre en majuscules) qui se déclenche lors d'une Cloud Firestore écriture et transforme le texte en majuscules.

Voici l'exemple de code complet contenant les fonctions :

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/https");
const {onDocumentCreated} = require("firebase-functions/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await getFirestore()
      .collection("messages")
      .add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()


@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")


@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

À propos de ce tutoriel

Nous avons choisi Cloud Firestore et les fonctions déclenchées par HTTP pour cet exemple, en partie parce que ces déclencheurs d'arrière-plan peuvent être testés de manière approfondie via la Firebase Local Emulator Suite. Cet ensemble d'outils est également compatible avec Realtime Database, Cloud Storage, Pub/Sub, Auth et les déclencheurs HTTP appelables. D'autres types de déclencheurs d'arrière-plan tels que Remote Config et les déclencheurs TestLab peuvent être testés de manière interactive à l'aide d'ensembles d'outils non décrits sur cette page.

Les sections suivantes de ce tutoriel décrivent en détail les étapes requises pour créer, tester et déployer l'exemple.

Créer un projet Firebase

Configurer votre environnement et la CLI Firebase

Initialiser votre projet

Lorsque vous initialisez Firebase SDK pour Cloud Functions, vous créez un projet vide contenant des dépendances et un exemple de code minimal. Si vous utilisez Node.js, vous pouvez choisir TypeScript ou JavaScript pour composer des fonctions. Pour les besoins de ce tutoriel, vous devrez également initialiser Cloud Firestore.

Pour initialiser votre projet :

1. Exécutez firebase login pour vous connecter via le navigateur et authentifier la Firebase CLI.
2. Accédez au répertoire de votre projet Firebase.
3. Exécutez firebase init firestore. Pour ce tutoriel, vous pouvez accepter les valeurs par défaut lorsque vous êtes invité à fournir des règles Firestore et des fichiers d'index. Si vous n'avez pas encore utilisé Cloud Firestore dans ce projet, vous devrez également sélectionner un mode de démarrage et un emplacement pour Firestore, comme décrit dans la section Premiers pas avec Cloud Firestore.
4. Exécutez firebase init functions. La CLI vous invite à choisir une base de code existante ou à en initialiser et à en nommer une nouvelle. Lorsque vous débutez, une seule base de code à l'emplacement par défaut suffit. Plus tard, à mesure que votre implémentation se développe, vous pouvez vouloir organiser les fonctions dans des bases de code.

5. La CLI vous propose les options suivantes pour la compatibilité linguistique :

   • JavaScript
   • TypeScript
   • Python

   Pour ce tutoriel, sélectionnez JavaScript ou Python. Pour créer des fonctions en TypeScript, consultez la section Écrire des fonctions avec TypeScript.

6. La CLI vous permet d'installer des dépendances. Vous pouvez refuser cette option si vous souhaitez gérer les dépendances d'une autre manière.

Une fois ces commandes exécutées, la structure de votre projet se présente comme suit :

myproject
+- .firebaserc    # Hidden file that helps you quickly switch between
|                 # projects with `firebase use`
|
+- firebase.json  # Describes properties for your project
|
+- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # Main source file for your Cloud Functions code
      |
      +- node_modules/ # Directory where your dependencies (declared in
                        # package.json) are installed

myproject
+- .firebaserc    # Hidden file that helps you quickly switch between
|                 # projects with `firebase use`
|
+- firebase.json  # Describes properties for your project
|
+- functions/     # Directory containing all your functions code
      |
      +- main.py      # Main source file for your Cloud Functions code
      |
      +- requirements.txt  #  List of the project's modules and packages 
      |
      +- venv/ # Directory where your dependencies are installed

Importer les modules requis et initialiser une application

Une fois les tâches de configuration terminées, vous pouvez ouvrir le répertoire source et commencer à ajouter du code, comme décrit dans les sections suivantes. Pour cet exemple, votre projet doit importer les Cloud Functions et modules SDK Admin. Ajoutez des lignes semblables aux suivantes à votre fichier source :

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/https");
const {onDocumentCreated} = require("firebase-functions/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();
index.js

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()
main.py

Ces lignes chargent les modules requis et initialisent une instance d'application admin à partir de laquelle des modifications Cloud Firestore peuvent être apportées. Partout où la compatibilité avec le SDK Admin est disponible, comme c'est le cas pour FCM, Authentication, et Firebase Realtime Database, elle offre un moyen puissant d'intégrer Firebase à l'aide de Cloud Functions.

La Firebase CLI installe automatiquement les modules SDK Admin Firebase et Firebase SDK pour Cloud Functions lorsque vous initialisez votre projet. Pour en savoir plus sur l'ajout de bibliothèques tierces à votre projet, consultez la section Gérer les dépendances.

Ajouter la fonction "add message"

Pour la fonction "add message", ajoutez les lignes suivantes à votre fichier source :

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await getFirestore()
      .collection("messages")
      .add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});
index.js

@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")
main.py

La fonction "add message" est un point de terminaison HTTP. Toute requête adressée au point de terminaison génère des objets de requête et de réponse transmis au gestionnaire de requêtes de votre plate-forme (onRequest() ou on_request).

Les fonctions HTTP sont synchrones (semblables aux fonctions appelables). Vous devez donc envoyer une réponse le plus rapidement possible et différer le travail à l'aide de Cloud Firestore. La fonction HTTP "add message" transmet une valeur de texte au point de terminaison HTTP et l'insère dans la base de données sous le chemin d'accès /messages/:documentId/original.

Ajouter la fonction "make uppercase"

Pour la fonction "make uppercase", ajoutez les lignes suivantes à votre fichier source :

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

La fonction "make uppercase" s'exécute lorsque Cloud Firestore est écrit, ce qui définit le document à écouter. Pour des raisons de performances, vous devez être aussi précis que possible.

Les accolades (par exemple, {documentId}) entourent les "paramètres", des caractères génériques qui exposent leurs données correspondantes dans le rappel. Cloud Firestore déclenche le rappel chaque fois que de nouveaux messages sont ajoutés.

Dans Node.js, les fonctions basées sur les événements, telles que les événements Cloud Firestore, sont asynchrones. La fonction de rappel doit renvoyer une valeur null, un objet, ou une promesse. Si vous ne renvoyez rien, la fonction expire, signalant une erreur, et est réessayée. Consultez la section Synchronisation, asynchronisation et promesses.

Émuler l'exécution de vos fonctions

Le Firebase Local Emulator Suite vous permet de créer et de tester des applications sur votre ordinateur local au lieu de les déployer dans un projet Firebase. Nous vous recommandons vivement d'effectuer des tests locaux pendant le développement, en partie parce que cela réduit le risque d'erreurs de codage qui pourraient entraîner des coûts dans un environnement de production (par exemple, une boucle infinie).

Pour émuler vos fonctions :

1. Exécutez firebase emulators:start et vérifiez la sortie pour l'URL de l'Emulator Suite UI. Par défaut, il s'agit de localhost:4000, mais il peut être hébergé sur un autre port de votre ordinateur. Saisissez cette URL dans votre navigateur pour ouvrir le Emulator Suite UI.

2. Vérifiez la sortie de la commande firebase emulators:start pour l'URL de la fonction HTTP. Elle doit ressembler à http://localhost:5001/MY_PROJECT/us-central1/addMessage, sauf que :

   1. MY_PROJECT sera remplacé par l'ID de votre projet.
   2. Le port peut être différent sur votre ordinateur local.

3. Ajoutez la chaîne de requête ?text=uppercaseme à la fin de l'URL de la fonction. Elle doit ressembler à ceci : http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. Vous pouvez éventuellement remplacer le message "uppercaseme" par un message personnalisé.

4. Créez un message en ouvrant l'URL dans un nouvel onglet de votre navigateur.

5. Affichez les effets des fonctions dans le Emulator Suite UI :

   1. Dans l'onglet Logs (Journaux), vous devriez voir de nouveaux journaux indiquant que vos fonctions HTTP se sont exécutées correctement :

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

   2. Dans l'onglet Firestore, vous devriez voir un document contenant votre message d'origine ainsi que la version en majuscules de votre message (si le message d'origine était "uppercaseme", vous verrez "UPPERCASEME").

Déployer des fonctions dans un environnement de production

Une fois que vos fonctions fonctionnent comme vous le souhaitez dans l'émulateur, vous pouvez les déployer, les tester et les exécuter dans l'environnement de production. N'oubliez pas que pour effectuer un déploiement en production, votre projet doit bénéficier du forfait Blaze. Consultez la page Tarifs Cloud Functions.

Pour terminer le tutoriel, déployez vos fonctions, puis exécutez-les.

1. Exécutez la commande suivante pour déployer vos fonctions :

    firebase deploy --only functions
    

   Une fois cette commande exécutée, la Firebase CLI génère l'URL de tous les points de terminaison de fonction HTTP. Dans votre terminal, vous devriez voir une ligne semblable à la suivante :

   Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
   

   L'URL contient l'ID de votre projet ainsi qu'une région pour la fonction HTTP. Bien que vous n'ayez pas à vous en soucier pour le moment, certaines fonctions HTTP de production doivent spécifier un emplacement pour minimiser la latence du réseau.

   Si vous rencontrez des erreurs d'accès telles que "Impossible d'autoriser l'accès au projet", essayez de vérifier l'alias de votre projet.

2. À l'aide de l'URL générée par la CLI, ajoutez un paramètre de requête de texte, et ouvrez-le dans un navigateur :

   https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
   

   La fonction s'exécute et redirige le navigateur vers la Firebase console à l'emplacement de la base de données où la chaîne de texte est stockée. Cet événement d'écriture déclenche la fonction "make uppercase", qui écrit une version en majuscules de la chaîne.

Après avoir déployé et exécuté des fonctions, vous pouvez afficher les journaux dans la Google Cloud console. Si vous devez supprimer des fonctions en développement ou en production, utilisez la Firebase CLI.

En production, vous pouvez optimiser les performances des fonctions et contrôler les coûts en définissant un nombre minimal et maximal d'instances à exécuter. Pour en savoir plus sur ces options d'exécution, consultez la section Contrôler le comportement de scaling.

Étapes suivantes

Dans cette documentation, vous pouvez en savoir plus sur la façon de gérer les fonctions pour Cloud Functions, ainsi que sur la façon de gérer tous les types d'événements pris en charge par Cloud Functions.

Pour en savoir plus sur Cloud Functions, vous pouvez également effectuer les opérations suivantes :

• Consultez les cas d'utilisation de Cloud Functions.
• Essayez l'atelier de programmation Cloud Functionscodelab.
• Consultez et exécutez des exemples de code sur GitHub.