Catch up on everthing we announced at this year's Firebase Summit. Learn more

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 passe 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 Cloud Firestore.
  • makeUppercase() , qui déclenche sur le Cloud Firestore écriture et transforme le texte en majuscules.

Nous avons choisi Nuage Firestore et les fonctions JavaScript déclenchées HTTP pour cet échantillon en partie parce que ces déclencheurs de fond peuvent être testés à fond grâce à l' émulateur local Firebase 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 de fond tels que Config à distance, TestLab et déclencheurs Analytics peuvent tous être testés de manière interactive en utilisant des jeux d' outils ne sont pas décrites 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 inspectez, saut Code de l' échantillon 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, entrez son nom du projet ou sélectionnez dans le menu déroulant.

    • Pour créer un nouveau projet, entrez le nom du projet souhaité. Vous pouvez également éventuellement modifier l'ID du projet affiché sous le nom du projet.

  2. Le cas échéant, examiner et accepter les termes Firebase .

  3. Cliquez sur Continuer.

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

    Vous pouvez soit sélectionner un existant compte Google Analytics ou de créer un nouveau compte.

    Si vous créez un nouveau compte, sélectionnez votre Analytics reporting emplacement , puis accepter les paramètres de partage des données et des termes Google Analytics pour votre projet.

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

Firebase provisionne automatiquement les ressources de 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 Node.js environnement aux fonctions d'écriture, et vous aurez besoin du CLI Firebase aux fonctions de Déployez aux fonctions de Cloud Runtime. Pour l' installation Node.js et NPM , version Node Manager est recommandé.

Une fois que vous avez Node.js et NPM installé, installer la CLI Firebase 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 d'MNP . Pour mettre à jour à la dernière version de firebase-tools , exécutez à nouveau 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 quelques exemples de code minimaux, 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 firebase login à se connecter via le navigateur et d' authentifier l'outil firebase.
  2. Accédez au répertoire de votre projet Firebase.
  3. Exécuter firebase init firestore . Pour ce didacticiel, vous pouvez accepter les valeurs par défaut lorsque vous y êtes invité pour les règles Firestore et les fichiers d'index. Si vous ne l' avez pas utilisé Nuage Firestore dans ce projet encore, vous aurez également besoin de sélectionner un mode de démarrage et un emplacement pour Firestore comme décrit dans Commencez avec Cloud Firestore .
  4. Exécuter firebase init functions d' firebase init functions . L'outil vous donne la possibilité d'installer des dépendances avec npm. Il est sûr de diminuer si vous souhaitez gérer les dépendances d'une autre manière, mais si vous ne fléchissent vous devez exécuter npm install avant émulant ou le déploiement de vos fonctions.
  5. L'outil vous offre deux options pour la prise en charge linguistique :

    Pour ce tutoriel, 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 package.json fichier créé lors de l' initialisation contient une clé importante: "engines": {"node": "10"} . Cela spécifie votre version de 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 fonctions de Cloud et des modules d' administration SDK en utilisant Node require des déclarations. Ajouter des lignes comme suit à votre index.js fichier:

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

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

Ces lignes de charge les firebase-functions et firebase-admin modules et initialiser une admin instance d'application à partir de laquelle les changements Nuage FireStore peuvent être faites. Chaque fois que l' administrateur SDK support est disponible, comme pour la FCM, l' authentification et Firebase en temps réel la base de données, il est un moyen puissant pour intégrer Firebase en utilisant des fonctions Cloud.

La CLI Firebase installe automatiquement les modules Firebase et Firebase SDK for Cloud Functions Node lorsque vous initialisez votre projet. Pour ajouter des bibliothèques 3ème partie à votre projet, vous pouvez modifier package.json et exécuter npm install . Pour plus d' informations, voir Dépendances poignée .

Ajouter la addMessage() fonction

Pour la addMessage() fonction, ajoutez ces lignes à 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.`});
});

Le addMessage() fonction est un point de terminaison HTTP. Toute demande aux résultats finaux dans express.js style demande et réponse des objets transmis à la onRequest() rappel.

Fonctions HTTP sont synchrones (similaire à des fonctions appelables ), vous devez donc envoyer une réponse aussi rapidement que possible les travaux et defer en utilisant Nuage Firestore. Le addMessage() fonction HTTP transmet une valeur de texte au point final HTTP et l' insère dans la base de données sous le chemin /messages/:documentId/original .

Ajouter la makeUppercase() fonction

Pour la makeUppercase() fonction, 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 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});
    });

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

Contreventements par exemple, {documentId} -Surround « paramètres » wildcards qui exposent leurs données appariées dans le rappel.

Cloud Firestore déclenche la onWrite() rappel à chaque fois que les 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 soit un null , d' un objet ou d' une promesse . Si vous ne retournez rien, la fonction expire, signalant une erreur, et est réessayée. Voir Sync, Async et promesses .

Émulez l'exécution de vos fonctions

L' émulateur local Firebase Suite vous permet de construire et des applications de test sur votre machine locale au lieu de déployer 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 firebase emulators:start et vérifier la sortie de l'URL de l'émulateur Suite UI. Sa valeur par défaut localhost: 4000 , mais ils peuvent être hébergés sur un autre port sur votre machine. Entrez cette URL dans votre navigateur pour ouvrir l'interface utilisateur de Emulator Suite.

  2. Vérifiez la sortie des firebase emulators:start commande 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 numéro de projet.
    2. Le port peut être différent sur votre machine locale.
  3. Ajouter la chaîne de requête ?text=uppercaseme à la fin de l'URL de la fonction. Cela devrait ressembler à : http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme . En option, vous pouvez changer le message "majuscule" 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 les nouveaux journaux indiquant que les fonctions addMessage() et makeUppercase() RAN:

      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 de votre message en majuscule (si elle é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 déployer à l'environnement d'exécution Node.js 14 recommandé, votre projet doit être sur le plan tarifaire Blaze . Voir les prix Functions Nuage .

Pour compléter le tutoriel, déployer 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 la 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 ne devez pas vous inquiéter à ce sujet 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 votre aliasing de projet .

  2. Utilisation de la addMessage() sortie URL par la CLI, ajoutez un paramètre de requête de texte, et l' ouvrir dans un navigateur:

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

    La fonction 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 en majuscule de la chaîne.

Après le déploiement et l' exécution des fonctions, vous pouvez afficher les journaux dans la console Firebase pour les fonctions de Cloud . Si vous devez supprimer des fonctions dans le développement ou la production, utilisez la CLI Firebase.

En production, vous souhaiterez peut-être optimiser les performances des fonctions et contrôler les coûts en définissant des nombres minimum et maximum d'instances à exécuter. Voir le comportement de mise à l' échelle de contrôle pour plus d' informations sur ces options d'exécution.

Examiner l'exemple de code complet

Voici les terminés 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 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');

// 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});
    });

Prochaines étapes

Dans cette documentation, vous pouvez trouver plus d' informations sur les concepts généraux pour les fonctions Cloud ainsi que des guides pour l' écriture des fonctions pour gérer les types d'événements pris en charge par des fonctions Cloud.

Pour en savoir plus sur Cloud Functions, vous pouvez également procéder comme suit :

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 prise en main de Cloud Functions, y compris la configuration de Node.js et de la CLI.