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


Pour commencer à utiliser Cloud Functions, essayez de suivre ce tutoriel, qui commence par les tâches de configuration requises et passe par la création, le test, et déployer deux fonctions associées:

  • Un "ajouter un message" Fonction qui expose une URL qui accepte une valeur textuelle et l'écrit à Cloud Firestore.
  • Une mise en majuscule Fonction qui se déclenche lors d'une opération d'écriture et de transformation Cloud Firestore mettre le texte en majuscules.

Pour cela, nous avons choisi Cloud Firestore et les fonctions JavaScript déclenchées par HTTP. car ces déclencheurs d'arrière-plan peuvent être testés de façon approfondie via Firebase Local Emulator Suite. Cet ensemble d'outils est également compatible avec Realtime Database, Déclencheurs Pub/Sub, Auth et HTTP appelable. Autres types de déclencheurs d'arrière-plan comme Remote Config, TestLab et les déclencheurs Analytics peuvent tous être testés de façon interactive à l'aide d'ensembles d'outils décrites sur cette page.

Les sections suivantes de ce tutoriel détaillent les étapes nécessaires pour compiler, et déployer l'exemple. Si vous préférez simplement exécuter le code et l'inspecter, passez à Examiner l'exemple de code complet.

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 du projet ou sélectionnez-le dans le menu déroulant.

    • Pour créer un projet, saisissez son nom. Vous pouvez aussi, si vous le souhaitez, modifier l'ID de projet affiché sous le nom du 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, ce qui vous permet de profiter d'une expérience optimale avec l'un des produits Firebase suivants :

    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.

  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. Une fois le processus terminé, vous êtes redirigé vers la page de présentation de votre projet Firebase dans la console Firebase.

Configurer Node.js et la CLI Firebase

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, Outil de gestion de versions de nœuds est recommandé.

Une fois Node.js et npm installés, Installez la CLI Firebase. via votre méthode préférée. Pour installer la CLI via npm, utilisez:

npm install -g firebase-tools

Cette opération installe la commande firebase disponible à l'échelle mondiale. Si la commande échoue, vous devrez peut-être modifier les autorisations npm. Pour effectuer la mise à jour vers la dernière version de firebase-tools, réexécutez la même commande.

Initialisez votre projet

Lorsque vous initialisez le SDK Firebase pour Cloud Functions, vous créez un projet vide contenant des dépendances et un exemple de code minimal, et vous choisissez TypeScript ou JavaScript pour composer des fonctions. Dans le cadre de ce tutoriel, vous devez é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 utilisé Cloud Firestore dans ce projet, vous ferez également devez sélectionner un mode de démarrage et un emplacement pour Firestore, comme décrit dans 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 débutez, un codebase unique à l'emplacement par défaut suffit ; au fur et à mesure que votre implémentation se développe, Organiser les fonctions dans du codebase

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

    Pour ce tutoriel, sélectionnez JavaScript.

  6. La CLI vous donne la possibilité d’installer des dépendances avec npm. C'est sans danger refuser si vous voulez gérer les dépendances d'une autre manière, Toutefois, si vous refusez, vous devrez exécuter npm install avant d'émuler ou le déploiement de vos fonctions.

Une fois ces commandes terminé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

Le fichier package.json créé lors de l'initialisation contient un élément clé: "engines": {"node": "16"}. Cette valeur spécifie votre version de Node.js pour l'écriture et le déploiement de fonctions. Vous pouvez sélectionnez d'autres versions compatibles.

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 utilisant le nœud require . Ajoutez des lignes comme celles-ci à votre fichier index.js :

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();
index.js

Ces lignes chargent les modules firebase-functions et firebase-admin, et initialisent une instance d'application admin à partir de laquelle des modifications Cloud Firestore peuvent être apporté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 automatiquement installe les SDK Firebase et Firebase pour les modules Node Cloud Functions lors de l'initialisation votre projet. Ajouter des bibliothèques tierces à votre projet, vous pouvez modifier package.json et exécuter npm install. Pour en savoir plus, consultez la section Gérer les dépendances.

Ajouter la fonction addMessage()

Pour la fonction addMessage(), ajoutez les lignes suivantes à index.js :

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.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 admin
    .firestore()
    .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

La fonction addMessage() est un point de terminaison HTTP. Toute requête envoyée au point de terminaison résultats dans le style ExpressJS Requête et réponse d'objets transmis à Rappel onRequest().

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. addMessage() 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 makeUppercase()

Pour la fonction makeUppercase(), ajoutez les lignes suivantes à index.js :

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

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

    const uppercase = original.toUpperCase();

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

La fonction makeUppercase() s'exécute lorsque Cloud Firestore est écrit. La fonction ref.set définit le document à écouter. Pour des raisons de performances, doit ê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 onCreate() chaque fois que de nouveaux messages sont ajoutés.

Les fonctions basées sur des événements, telles que les événements Cloud Firestore, sont asynchrone. La fonction de rappel doit renvoyer un null, un objet, ou une promesse. Si vous ne renvoyez rien, la fonction expire, signalant une erreur et fait l'objet d'une nouvelle tentative. Consultez la section Synchronisation, synchronisation et promesses.

Émuler l'exécution de vos fonctions

La Firebase Local Emulator Suite vous permet de créer et de tester des applications sur votre ordinateur local au lieu de les déployer 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 la sortie de firebase emulators:start. pour l'URL de la fonction HTTP addMessage(). Il se présentera comme suit : 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. Le résultat devrait 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 les fonctions addMessage() et makeUppercase() ont été 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 vous le souhaitez dans l'émulateur, vous pouvez passer à les déployer, les tester et les exécuter dans l'environnement de production. À retenir que pour le déploiement dans l'environnement d'exécution recommandé Node.js 14, 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 addMessage() pour déclencher makeUppercase().

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

     firebase deploy --only functions

    Une fois cette commande exécutée, la CLI Firebase génère l'URL de toutes les Fonction HTTP les points de terminaison. Dans votre terminal, une ligne semblable à celle-ci doit 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 . Vous n'avez pas à vous en soucier pour l'instant, doivent spécifier un emplacement réduire la latence du réseau.

    Si vous rencontrez des erreurs d'accès telles que "Impossible d'autoriser l'accès à projet ». essayez de vérifier la création d'alias de votre projet.

  2. À l'aide de l'URL addMessage() 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 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 makeUppercase(), 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 de la fonction en définissant le nombre minimal et maximal d'instances à exécuter. Voir Contrôler le comportement du scaling pour en savoir plus sur ces options d'exécution.

Examiner l'exemple de code complet

Voici le functions/index.js terminé contenant les fonctions addMessage() et makeUppercase(). Ces fonctions vous permettent de transmettre un paramètre à un point de terminaison HTTP qui écrit une valeur dans Cloud Firestore, puis la transforme en mettant en majuscule tous les caractères de la chaîne.

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

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

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.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 admin
    .firestore()
    .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 creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

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

    const uppercase = original.toUpperCase();

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

Étapes suivantes

Cette documentation vous explique comment gérer les fonctions pour Cloud Functions ainsi que la façon de pour 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: