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

2e génération 1re génération

Pour commencer à utiliser Cloud Functions, suivez ce tutoriel, qui 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" qui expose une URL qui accepte une valeur textuelle et l'écrit dans Cloud Firestore.
• Une fonction "mettre en majuscules" qui se déclenche lors d'une écriture Cloud Firestore et transforme le texte en majuscules.

Voici l'exemple de code complet contenant les fonctions:

Node.js

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/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

Python

# 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 en arrière-plan peuvent être testés de manière approfondie via Firebase Local Emulator Suite. Cet ensemble d'outils est également compatible avec les déclencheurs Realtime Database, Cloud Storage, PubSub, Auth et HTTP callable. D'autres types de déclencheurs en arrière-plan, tels que les déclencheurs Remote Config et TestLab, peuvent être testés de manière interactive à l'aide d'ensembles d'outils non décrits sur cette page.

Remarque : Vous pouvez émuler des fonctions dans n'importe quel projet Firebase, mais pour les déployer, votre projet doit bénéficier du forfait Blaze. Consultez les tarifs de Cloud Functions.

Les sections suivantes de ce tutoriel détaillent les étapes nécessaires pour compiler, et déployer l'exemple.

Créer un projet Firebase

1. Dans la console Firebase, cliquez sur Ajouter un projet.

   • Pour ajouter des ressources Firebase à un projet Google Cloud existant, saisissez son nom ou sélectionnez-le dans le menu déroulant.

   • Pour créer un projet, saisissez son nom. Vous pouvez également modifier l'ID du projet affiché sous le nom du projet.

     Firebase génère un ID unique pour votre projet Firebase en fonction du nom que vous lui attribuez. Si vous souhaitez modifier cet ID de projet, vous devez le faire maintenant, car il ne peut plus être modifié une fois que Firebase a provisionné des ressources pour votre projet. Consultez Comprendre les projets Firebase pour découvrir comment Firebase utilise l'ID de projet.

2. Si vous y êtes invité, lisez et acceptez les Conditions d'utilisation de Firebase.

3. Cliquez sur Continuer.

4. (Facultatif) Configurez Google Analytics pour votre projet afin de afin de bénéficier d'une expérience optimale avec l'un des produits Firebase suivants:

   Firebase Crashlytics Firebase Cloud Messaging

   Firebase In-App Messaging Firebase Remote Config

   Personnalisation Remote Config Firebase A/B Testing

   Sélectionnez un compte Google Analytics existant ou créez-en un.

   Si vous créez un compte, sélectionnez votre Analytics : signaler la position, puis accepter les paramètres de partage des données et les conditions d'utilisation de Google Analytics pour votre projet.

   Vous pourrez toujours configurer Google Analytics plus tard dans l'onglet Intégrations de vos paramètres du projet .

5. Cliquez sur Créer un projet (ou sur Ajouter Firebase si vous utilisez un projet Google Cloud existant).

Firebase provisionne automatiquement des ressources pour votre projet Firebase. Quand ? le processus est terminé, vous êtes redirigé vers la page de présentation de votre dans la console Firebase.

Configurer votre environnement et la CLI Firebase

Node.js

Pour écrire des fonctions, vous avez besoin d'un environnement Node.js. Vous aurez besoin de la CLI Firebase pour déployer des fonctions l'environnement d'exécution Cloud Functions. Pour installer Node.js et npm, nous vous recommandons d'utiliser Node Version Manager.

Important :Cloud Functions et la CLI Firebase sont entièrement compatibles avec Node.js. versions 18 et 20, avec une compatibilité en version preview pour la version 22. Les versions 14 et 16 sont obsolètes et seront mises hors service début 2025 (actuellement, le déploiement avec ces versions obsolètes est désactivé). Voir Définir les options d'exécution pour des informations importantes concernant la compatibilité continue de ces versions de Node.js.

Une fois Node.js et npm installés, installez la CLI Firebase à l'aide de la méthode de votre choix. Pour installer la CLI via npm, utilisez:

npm install -g firebase-tools

Cette action installe la commande Firebase disponible dans le monde entier. Si la commande échoue, vous devrez peut-être modifier les autorisations npm. Pour passer à la dernière version de firebase-tools, exécutez à nouveau la même commande.

Dans de nombreux cas, les nouvelles fonctionnalités et les corrections de bugs sont disponible uniquement avec la dernière version de la CLI Firebase et la SDK firebase-functions. Il est conseillé de consulter fréquemment Mettez à jour la CLI Firebase et le SDK à l'aide de ces commandes dans le dossier functions de votre projet Firebase:

npm install firebase-functions@latest firebase-admin@latest --save
npm install -g firebase-tools

Python

Vous aurez besoin d'un environnement Python pour écrire des fonctions, et de la CLI Firebase pour les déployer dans l'environnement d'exécution Cloud Functions. Nous vous recommandons d'utiliser venv pour isoler les dépendances. Les versions Python 3.10 et 3.11 sont compatibles.

Une fois Python installé, Installez la CLI Firebase. via votre méthode préférée.

Dans de nombreux cas, les nouvelles fonctionnalités et les corrections de bugs sont disponible uniquement avec la dernière version de la CLI Firebase et la SDK firebase-functions. Il est conseillé de consulter fréquemment mettre à jour à la fois la CLI Firebase et le SDK situé dans le dossier functions de votre projet Firebase.

Initialisez votre projet

Lorsque vous initialisez le SDK Firebase pour Cloud Functions, vous créez un projet vide contenant des dépendances et quelques exemples de code minimal. Si vous utilisez à l'aide de Node.js, vous pouvez choisir TypeScript ou JavaScript pour la rédaction de 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 CLI Firebase.
2. Accédez au répertoire de votre projet Firebase.
3. Exécutez firebase init firestore. Pour ce tutoriel, vous pouvez accepter lorsque vous êtes invité à spécifier des règles et des fichiers d'index Firestore. Si vous n'avez pas encore utilisé Cloud Firestore dans ce projet, vous devez é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 un ou initialisez et nommez-en un nouveau. Lorsque vous commencez à peine, une seule base de code à l'emplacement par défaut est suffisante. Plus tard, à mesure que votre implémentation se développe, vous pouvez organiser les fonctions dans des bases de code.

5. La CLI vous propose les options suivantes pour la prise en charge des langages:

   • 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 donne la possibilité d'installer des dépendances. C'est sans danger refuser si vous souhaitez gérer les dépendances d'une autre manière.

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

Node.js

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

Pour Node.js, le fichier package.json créé lors de l'initialisation contient une clé importante : "engines": {"node": "18"}. Ce champ spécifie votre version de Node.js pour l'écriture et le déploiement de fonctions. Vous pouvez sélectionnez d'autres versions compatibles.

Python

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 ouvrez le répertoire source et commencez à ajouter du code comme décrit dans les dans les sections suivantes. Pour cet exemple, votre projet doit importer Cloud Functions et les modules SDK Admin. Ajoutez des lignes comme celles-ci à votre fichier source :

Node.js

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

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

initializeApp();
index.js

Python

# 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 et initialiser une instance d'application admin à partir de laquelle des modifications de Cloud Firestore peuvent être effectuées. Partout où le SDK Admin est disponible, en l'état pour FCM, Authentication et Firebase Realtime Database, il fournit efficace pour intégrer Firebase à l'aide de Cloud Functions.

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

Ajouter la fonction "Ajouter un message"

Pour l'option "Ajouter un message" , ajoutez les lignes suivantes à votre fichier source:

Node.js

// 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

Python

@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 envoyé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 fonctions appelables), vous devez donc envoyer une réponse le plus rapidement possible et différez le travail en utilisant Cloud Firestore. L'option "Ajouter un message" La fonction HTTP transmet une valeur textuelle au point de terminaison HTTP et l'insère dans le base de données sous le chemin d'accès /messages/:documentId/original.

Ajouter la fonction "mettre en majuscules"

Pour l'option « mettre des majuscules », , ajoutez les lignes suivantes à votre fichier source:

Node.js

// 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

Python

@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

L'opérateur « mettre des majuscules » s'exécute lorsque Cloud Firestore est écrit. définissant le document à écouter. Pour des raisons de performances, doit être aussi précis que possible.

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

Attention : Veillez à éviter toute situation dans laquelle le résultat de la fonction déclenche à nouveau la fonction, créant ainsi une boucle infinie. Par exemple, une fonction déclenchée par des écritures dans un document Cloud Firestore spécifique qui se termine par l'écriture dans ce même chemin. Veillez également à écrire des fonctions de manière idempotente, afin qu'elles produisent le même résultat si elles s'exécutent plusieurs fois pour un même événement.

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

Émuler l'exécution de vos fonctions

Firebase Local Emulator Suite vous permet de compiler 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 en local en partie parce qu'elle réduit le risque d'erreurs de codage qui pourraient entraîner des frais dans un environnement de production (par exemple, une boucle infinie) ;

Pour émuler vos fonctions :

1. Exécutez firebase emulators:start et vérifiez le résultat de l'URL. de Emulator Suite UI. La valeur par défaut est localhost:4000, mais il peut être hébergé sur une autre sur votre machine. Saisissez cette URL dans votre navigateur pour ouvrir le Emulator Suite UI

2. Vérifiez l'URL de la fonction HTTP dans la sortie de la commande firebase emulators:start. Il ressemble à http://localhost:5001/MY_PROJECT/us-central1/addMessage, à l'exception des points suivants :

   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. Si vous le souhaitez, vous pouvez 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 Emulator Suite UI :

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

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

   2. Dans l'onglet Firestore, vous devriez voir un document contenant votre ainsi que sa version en majuscules (s'il s'agissait à l'origine "uppercaseme", vous verrez "MAJUSCULES").

Déployer des fonctions dans un environnement de production

Une fois que vos fonctions fonctionnent comme prévu dans l'émulateur, vous pouvez les déployer, les tester et les exécuter dans l'environnement de production. À retenir à déployer en production, votre projet doit être inclus dans le forfait Blaze. Voir Tarifs de 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
    

   Après avoir exécuté cette commande, la CLI Firebase affiche l'URL de tous les points de terminaison de fonction HTTP. Dans votre terminal, une ligne semblable à la suivante devrait s'afficher :

   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 le protocole . Bien que vous n'ayez pas à vous en préoccuper pour le moment, certaines fonctions HTTP de production doivent spécifier une emplacement pour réduire la latence réseau.

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

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

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

   La fonction s'exécute et redirige le navigateur vers la console Firebase à 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 "mettre en majuscules", 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 console Google Cloud. Si vous devez supprimer des fonctions en développement ou en production, utilisez la CLI Firebase.

En production, vous souhaiterez peut-être optimiser les performances et le contrôle en définissant le nombre minimal et maximal d'instances à exécuter. Pour en savoir plus sur ces options d'exécution, consultez la page Contrôler le comportement du scaling.

Remarque : Le déploiement de fonctions à partir de la CLI Firebase est soumis à des limites de débit. Consultez la section Limites de quota pour le déploiement de la CLI Firebase.

Étapes suivantes

Dans cette documentation, vous découvrirez comment gérer les fonctions pour Cloud Functions, ainsi que comment gérer tous les types d'événements compatibles avec Cloud Functions.

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

• Découvrez les cas d'utilisation de Cloud Functions.
• Suivez l'atelier de programmation Cloud Functions.
• Examiner et exécuter des exemples de code sur GitHub