Google is committed to advancing racial equity for Black communities. See how.
Cette page a été traduite par l'API Cloud Translation.
Switch to English

Lancez-vous: écrivez, testez et déployez vos premières fonctions

Pour commencer avec Cloud Functions, essayez de suivre ce didacticiel, qui commence par les tâches de configuration requises et fonctionne par la création, le test et le déploiement de deux fonctions associées:

  • addMessage() , qui expose une URL qui accepte une valeur de texte et l'écrit dans Cloud Firestore.
  • makeUppercase() , qui déclenche l'écriture sur Cloud Firestore et transforme le texte en majuscules.

Nous avons choisi Cloud Firestore et les fonctions JavaScript 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 Firebase Local Emulator Suite . Cet ensemble d'outils prend également en charge les déclencheurs appelables Realtime Database, PubSub, Auth et HTTP. D'autres types de déclencheurs d'arrière-plan tels que les déclencheurs Remote Config, TestLab et Analytics peuvent tous être testés de manière interactive à l' aide de jeux d'outils non décrits dans cette page.

Les sections suivantes de ce didacticiel détaillent les étapes requises pour créer, tester et déployer l'exemple. Si vous préférez simplement exécuter le code et l'inspecter, passez à l' examen de l'exemple de code complet .

Créer un projet Firebase

  1. Dans la console Firebase , cliquez sur Ajouter un projet , puis sélectionnez ou entrez un nom de projet .

    Si vous disposez d'un projet Google Cloud Platform (GCP) existant, vous pouvez sélectionner le projet dans le menu déroulant pour ajouter des ressources Firebase à ce projet.

  2. (Facultatif) Si vous créez un nouveau projet, vous pouvez modifier l' ID du projet .

    Firebase attribue automatiquement un ID unique à votre projet Firebase. Consultez Comprendre les projets Firebase pour savoir comment Firebase utilise l'ID de projet.

  3. Cliquez sur Continuer .

  4. (Facultatif) Configurez Google Analytics pour votre projet, ce qui vous permet d'avoir une expérience optimale en utilisant l'un des produits Firebase suivants:

    Lorsque vous y êtes invité, choisissez d'utiliser un compte Google Analytics existant ou de créer un nouveau compte.
    Si vous choisissez de créer un nouveau compte, sélectionnez votre emplacement de rapport Analytics , puis acceptez les paramètres de partage de données et les conditions Google Analytics pour votre projet.

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

Firebase provisionne automatiquement les ressources pour votre projet Firebase. Une fois le processus terminé, vous serez redirigé vers la page de présentation de votre projet Firebase dans la console Firebase.

Configurer Node.js et la CLI Firebase

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

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

npm install -g firebase-tools

Cela installe la commande firebase disponible dans le monde entier. Si la commande échoue, vous devrez peut-être modifier les autorisations npm . Pour mettre à 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 la composition des fonctions. Pour les besoins de ce didacticiel, vous devrez également initialiser Cloud Firestore.

Pour initialiser votre projet:

  1. Exécutez la firebase login pour vous connecter via le navigateur et authentifier l'outil Firebase.
  2. Accédez au répertoire de votre projet Firebase.
  3. Exécutez firebase init firestore . Pour ce didacticiel, vous pouvez accepter les valeurs par défaut lorsque vous êtes invité à entrer 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 Premiers pas avec Cloud Firestore .
  4. Exécutez les firebase init functions . L'outil vous offre la possibilité d'installer des dépendances avec npm. Il est prudent de refuser si vous souhaitez gérer les dépendances d'une autre manière, mais si vous refusez, vous devrez exécuter npm install avant d'émuler ou de déployer vos fonctions.
  5. L'outil vous offre deux options pour la prise en charge des langues:

    Pour ce didacticiel, sélectionnez JavaScript .

Une fois ces commandes terminées avec succès, la structure de votre projet ressemble à ceci:

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 une clé importante: "engines": {"node": "10"} . Cela spécifie votre version Node.js pour l'écriture et le déploiement de fonctions. Vous pouvez sélectionner d'autres versions prises en charge .

Importez les modules requis et initialisez 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 modules Cloud Functions et Admin SDK à l'aide require instructions Node require . Ajoutez des lignes comme celles-ci à votre fichier index.js :

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

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

Ces lignes chargent les firebase-functions et firebase-admin , et initialisent une instance d'application d' admin partir de laquelle des modifications Cloud Firestore peuvent être apportées. Partout où la prise en charge du SDK Admin est disponible, comme pour FCM, l'authentification et la base de données en temps réel Firebase, elle fournit un moyen puissant d'intégrer Firebase à l'aide de Cloud Functions.

L'interface de ligne de commande Firebase installe automatiquement les modules Firebase et Firebase SDK for Cloud Functions Node lorsque vous initialisez votre projet. Pour ajouter des bibliothèques tierces à votre projet, vous pouvez modifier package.json et exécuter npm install . Pour plus d'informations, consultez Gérer les dépendances .

Ajouter la fonction addMessage()

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

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Cloud 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 Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've succesfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

La fonction addMessage() est un point de terminaison HTTP. Toute demande adressée au point de terminaison entraîne des objets Request et Response de style ExpressJS transmis au rappel onRequest() .

Les fonctions HTTP sont synchrones (similaires 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 addMessage() transmet une valeur de texte au point de terminaison HTTP et l'insère dans la base de données sous le chemin /messages/:documentId/original .

Ajoutez la fonction makeUppercase()

Pour la fonction makeUppercase() , ajoutez ces lignes à 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 Cloud 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 Cloud Firestore.
      // Setting an 'uppercase' field in Cloud Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

La fonction makeUppercase() s'exécute lorsque Cloud Firestore est écrit dans. La fonction ref.set définit le document à écouter. Pour des raisons de performances, vous devez être aussi précis que possible.

Accolades - par exemple, {documentId} - "paramètres" environnants, caractères génériques qui exposent leurs données correspondantes dans le rappel.

Cloud Firestore déclenche le rappel onWrite() chaque fois que des données sont écrites ou mises à jour sur le document donné.

Les fonctions événementielles telles que les événements Cloud Firestore sont asynchrones. La fonction de rappel doit retourner un null , un objet ou une promesse . Si vous ne renvoyez rien, la fonction expire, signalant une erreur, et est réessayée. Voir Sync, Async et Promises .

Émulez l'exécution de vos fonctions

Firebase Local Emulator Suite vous permet de créer et de tester des applications sur votre machine locale au lieu de les déployer dans un projet Firebase. Les tests locaux pendant le développement sont fortement recommandés, en partie parce qu'ils réduisent le risque d'erreurs de codage qui pourraient potentiellement entraîner des coûts dans un environnement de production (par exemple, une boucle infinie).

Pour émuler vos fonctions:

  1. Exécutez les firebase emulators:start et vérifiez la sortie pour l'URL de l'interface utilisateur d'Emulator Suite. Il est par défaut localhost: 4000 , mais peut être hébergé sur un port différent de votre machine. Entrez cette URL dans votre navigateur pour ouvrir l'interface utilisateur d'Emulator Suite.

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

    1. MY_PROJECT sera remplacé par votre ID de projet.
    2. Le port peut être différent sur votre machine locale.
  3. Ajoutez la chaîne de requête ?text=uppercaseme à la fin de l'URL de la fonction. Cela devrait ressembler à quelque chose comme: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme . Si vous le souhaitez, vous pouvez changer le message «uppercaseme» en un message personnalisé.

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

  5. Affichez les effets des fonctions dans l'interface utilisateur d'Emulator Suite:

    1. Dans l'onglet Journaux , vous devriez voir de nouveaux journaux indiquant que les fonctions addMessage() et makeUppercase() exécutées:

      Fonctions i: Début de l'exécution de "addMessage"

      Fonctions i: Début de l'exécution de "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 (s'il était à l'origine "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 procéder à leur déploiement, à leur test et à leur exécution dans l'environnement de production. Gardez à l'esprit que pour être déployé dans l'environnement d'exécution Node.js 10 recommandé, votre projet doit être sur le plan de facturation Blaze pay-as-you-go. Voir les tarifs de Cloud Functions .

Pour terminer le didacticiel, déployez vos fonctions puis exécutez addMessage() pour déclencher makeUppercase() .

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

    $ firebase deploy --only functions
    

    Après avoir exécuté cette commande, la CLI Firebase génère l'URL de tous les points de terminaison de fonction HTTP. Dans votre terminal, vous devriez voir une ligne comme celle-ci:

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

    L'URL contient votre ID de projet ainsi qu'une région pour la fonction HTTP. Bien que vous n'ayez pas à vous en soucier maintenant, 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 addMessage() sortie 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 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 majuscule de la chaîne.

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

Examiner l'exemple de code complet

Voici les functions/index.js 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 majuscules tous les caractères de la chaîne.

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

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

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Cloud 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 Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've succesfully 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 Cloud 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 Cloud Firestore.
      // Setting an 'uppercase' field in Cloud Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

Prochaines étapes

Dans cette documentation, vous trouverez plus d'informations sur les concepts généraux de Cloud Functions ainsi que des guides d' écriture de fonctions permettant de gérer 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:

Didacticiel vidéo

Vous pouvez en savoir plus sur Cloud Functions en regardant des didacticiels vidéo. Dans cette vidéo, vous trouverez des conseils détaillés sur la mise en route de Cloud Functions, y compris la configuration de Node.js et de la CLI.