Connecter votre application à l'émulateur Cloud Functions

Avant de connecter votre application à l'émulateur Cloud Functions, assurez-vous de comprendre le workflow global de Firebase Local Emulator Suite, d'installer et de configurer Local Emulator Suite, et de consulter ses commandes CLI.

Choisir un projet Firebase

Firebase Local Emulator Suite émule des produits pour un seul projet Firebase.

Pour sélectionner le projet à utiliser, avant de démarrer les émulateurs, exécutez firebase use dans votre répertoire de travail dans la CLI. Vous pouvez également transmettre l'option --project à chaque commande de l'émulateur.

Local Emulator Suite est compatible avec l'émulation de projets Firebase réels et de projets de démonstration.

Type de projet Fonctionnalités Utiliser avec des émulateurs
Situation réelle

Un projet Firebase réel est celui que vous avez créé et configuré (le plus souvent via la console Firebase).

Les projets réels disposent de ressources en ligne, comme des instances de base de données, des buckets de stockage, des fonctions ou toute autre ressource que vous configurez pour ce projet Firebase.

Lorsque vous travaillez avec de véritables projets Firebase, vous pouvez exécuter des émulateurs pour tous les produits compatibles ou certains d'entre eux.

Pour tous les produits que vous n'émulez pas, vos applications et votre code interagissent avec la ressource en direct (instance de base de données, bucket de stockage, fonction, etc.).

Démo

Un projet Firebase de démonstration ne comporte aucune configuration réelle de Firebase et aucune ressource en ligne. Pour accéder à ces projets, vous devez généralement suivre des ateliers de programmation ou d'autres tutoriels.

Les ID de projet des projets de démonstration portent le préfixe demo-.

Lorsque vous travaillez avec des projets Firebase de démonstration, vos applications et votre code n'interagissent qu'avec des émulateurs. Si votre application tente d'interagir avec une ressource pour laquelle aucun émulateur n'est en cours d'exécution, ce code échouera.

Dans la mesure du possible, nous vous recommandons d'utiliser des projets de démonstration. Voici quelques-uns de ses avantages :

  • Configuration plus simple, car vous pouvez exécuter les émulateurs sans avoir à créer un projet Firebase
  • Sécurité renforcée, car si votre code appelle accidentellement des ressources non émulées (de production), il n'y a aucune chance de modification, d'utilisation et de facturation des données.
  • Meilleure prise en charge hors connexion, car vous n'avez pas besoin d'accéder à Internet pour télécharger la configuration de votre SDK.

Instrumenter votre application pour qu'elle communique avec les émulateurs

Instrumenter votre application pour les fonctions appelables

Si vos activités de prototypage et de test impliquent des fonctions backend appelables, configurez l'interaction avec l'émulateur Cloud Functions for Firebase comme suit:

Kotlin+KTX
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val functions = Firebase.functions
functions.useEmulator("10.0.2.2", 5001)
MainActivity.kt
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFunctions functions = FirebaseFunctions.getInstance();
functions.useEmulator("10.0.2.2", 5001);
MainActivity.java
Swift
Functions.functions().useFunctionsEmulator(origin: "http://127.0.0.1:5001")
ViewController.swift

Web

import { getApp } from "firebase/app";
import { getFunctions, connectFunctionsEmulator } from "firebase/functions";

const functions = getFunctions(getApp());
connectFunctionsEmulator(functions, "127.0.0.1", 5001);
fb_functions_emulator_connect.js

Web

firebase.functions().useEmulator("127.0.0.1", 5001);
emulator-suite.js

Instrumenter votre application pour l'émulation des fonctions HTTPS

Chaque fonction HTTPS de votre code sera diffusée à partir de l'émulateur local à l'aide du format d'URL suivant:

http://$HOST:$PORT/$PROJECT/$REGION/$NAME

Par exemple, une fonction helloWorld simple avec le port et la région d'hôte par défaut est diffusée à l'adresse suivante:

https://localhost:5001/$PROJECT/us-central1/helloWorld

Instrumenter votre application pour l'émulation des fonctions de file d'attente de tâches

L'émulateur configure automatiquement les files d'attente de tâches émulées en fonction des définitions de déclencheur, et le SDK Admin redirige les requêtes mises en file d'attente vers l'émulateur s'il détecte qu'il s'exécute via la variable d'environnement CLOUD_TASKS_EMULATOR_HOST.

Notez que le système de distribution utilisé en production est plus complexe que celui implémenté dans l'émulateur. Vous ne devez donc pas vous attendre à ce que le comportement émulé reflète précisément les environnements de production. Les paramètres de l'émulateur fournissent des limites supérieures au débit auquel les tâches sont distribuées et réessayées.

Instrumenter votre application pour l'émulation des fonctions déclenchées en arrière-plan

L'émulateur Cloud Functions est compatible avec les fonctions déclenchées en arrière-plan à partir des sources suivantes:

  • Émulateur Realtime Database
  • Émulateur Cloud Firestore
  • Émulateur Authentication
  • Émulateur Pub/Sub
  • Émulateur Firebase Alerts

Pour déclencher des événements en arrière-plan, modifiez les ressources de backend à l'aide de Emulator Suite UI ou en connectant votre application ou votre code de test aux émulateurs à l'aide du SDK de votre plate-forme.

Tester les gestionnaires d'événements personnalisés émis par les extensions

Pour les fonctions que vous implémentez pour gérer les événements personnalisés Firebase Extensions avec la version 2 de Cloud Functions, l'émulateur Cloud Functions s'associe à l'émulateur Eventarc pour prendre en charge les déclencheurs Eventarc.

Pour tester les gestionnaires d'événements personnalisés des extensions qui émettent des événements, vous devez installer les émulateurs Cloud Functions et Eventarc.

L'environnement d'exécution Cloud Functions définit la variable d'environnement EVENTARC_EMULATOR sur localhost:9299 dans le processus en cours si l'émulateur Eventarc est en cours d'exécution. Les Firebase Admin SDK se connectent automatiquement à l'émulateur Eventarc lorsque la variable d'environnement EVENTARC_EMULATOR est définie. Vous pouvez modifier le port par défaut, comme indiqué dans la section Configurer Local Emulator Suite.

Lorsque les variables d'environnement sont correctement configurées, Firebase Admin SDK envoie automatiquement des événements à l'émulateur Eventarc. À son tour, l'émulateur Eventarc appelle l'émulateur Cloud Functions pour déclencher les gestionnaires enregistrés.

Vous pouvez consulter les journaux Functions dans Emulator Suite UI pour en savoir plus sur l'exécution du gestionnaire.

Configurer un environnement de test local

Si vos fonctions reposent sur une configuration d'environnement basée sur dotenv, vous pouvez émuler ce comportement dans votre environnement de test local.

Lorsque vous utilisez un émulateur Cloud Functions local, vous pouvez remplacer les variables d'environnement de votre projet en configurant un fichier .env.local. Le contenu de .env.local est prioritaire sur .env et le fichier .env spécifique au projet.

Par exemple, un projet peut inclure ces trois fichiers contenant des valeurs légèrement différentes pour le développement et les tests locaux:

.env .env.dev .env.local
PLANET=Earth

AUDIENCE=Humans

AUDIENCE=Dev Humans AUDIENCE=Local Humans

Lorsqu'il est démarré dans le contexte local, l'émulateur charge les variables d'environnement comme indiqué:

  $ firebase emulators:start
  i  emulators: Starting emulators: functions
  # Starts emulator with following environment variables:
  #  PLANET=Earth
  #  AUDIENCE=Local Humans

Secrets et identifiants dans l'émulateur Cloud Functions

L'émulateur Cloud Functions prend en charge l'utilisation de secrets pour stocker et accéder à des informations de configuration sensibles. Par défaut, l'émulateur tente d'accéder à vos secrets de production à l'aide des identifiants par défaut de l'application. Dans certains cas, comme les environnements de CI, l'émulateur peut ne pas réussir à accéder aux valeurs secrètes en raison de restrictions d'autorisation.

Comme pour la compatibilité de l'émulateur Cloud Functions avec les variables d'environnement, vous pouvez remplacer les valeurs des secrets en configurant un fichier .secret.local. Vous pouvez ainsi tester facilement vos fonctions localement, en particulier si vous n'avez pas accès à la valeur secrète.

Quels sont les autres outils de test de Cloud Functions ?

L'émulateur Cloud Functions est complété par d'autres outils de prototypage et de test:

  • Le shell Cloud Functions, qui permet de prototyper et de développer des fonctions interactives et itératifs. Le shell utilise l'émulateur Cloud Functions avec une interface de type REPL pour le développement. Aucune intégration avec les émulateurs Cloud Firestore ou Realtime Database n'est fournie. À l'aide du shell, vous simulez des données et effectuez des appels de fonction pour simuler l'interaction avec des produits que Local Emulator Suite n'est pas compatible avec pour le moment: Analytics, Remote Config et Crashlytics.
  • Le SDK de test Firebase pour Cloud Functions, un framework Node.js avec Mocha pour le développement de fonctions. En effet, le SDK de test Cloud Functions fournit une automatisation au-dessus du shell Cloud Functions.

Pour en savoir plus sur le shell Cloud Functions et le SDK de test Cloud Functions, consultez Tester des fonctions de manière interactive et Tests unitaires de Cloud Functions.

Différences entre l'émulateur Cloud Functions et la production

L'émulateur Cloud Functions est assez proche de l'environnement de production pour la plupart des cas d'utilisation. Nous avons déployé d'importants efforts pour nous assurer que tout dans l'environnement d'exécution de Node est aussi proche de la production que possible. Toutefois, l'émulateur ne reproduit pas l'environnement de production conteneurisé complet. Par conséquent, même si le code de votre fonction s'exécute de manière réaliste, d'autres aspects de votre environnement (fichiers locaux, comportement après les plantages de fonctions, etc.) seront différents.

Cloud IAM

La suite d'émulateurs Firebase ne tente pas de reproduire ni de respecter le comportement lié à l'IAM pour l'exécution. Les émulateurs respectent les règles de sécurité Firebase fournies, mais dans les cas où IAM est normalement utilisé, par exemple pour définir le compte de service d'invocation de Cloud Functions et donc les autorisations, l'émulateur n'est pas configurable et utilisera le compte disponible dans le monde entier sur votre ordinateur de développement, comme si vous exécutiez directement un script local.

Restrictions liées à la mémoire et au processeur

L'émulateur n'applique pas de restrictions de mémoire ni de processeur à vos fonctions. Toutefois, l'émulateur prend en charge les fonctions de délai avant expiration via l'argument d'environnement d'exécution timeoutSeconds.

Notez que le temps d'exécution des fonctions peut différer de la production lorsque les fonctions sont exécutées dans l'émulateur. Une fois que vous avez conçu et testé des fonctions avec l'émulateur, nous vous recommandons d'exécuter des tests limités en production pour confirmer les temps d'exécution.

Planifier les différences entre les environnements locaux et de production

Étant donné que l'émulateur s'exécute sur votre ordinateur local, il dépend de votre environnement local pour les applications, les programmes et les utilitaires intégrés.

Sachez que votre environnement local de développement Cloud Functions peut différer de l'environnement de production Google:

  • Le comportement des applications que vous installez localement pour simuler l'environnement de production (par exemple, ImageMagick de ce tutoriel) peut différer de celui de la production, en particulier si vous avez besoin de versions différentes ou si vous développez dans un environnement autre que Linux. Envisagez de déployer votre propre copie binaire du programme manquant avec le déploiement de votre fonction.

  • De même, les utilitaires intégrés (par exemple, les commandes shell telles que ls, mkdir) peuvent différer des versions disponibles en production, en particulier si vous développez dans un environnement autre que Linux (par exemple, macOS). Pour résoudre ce problème, vous pouvez utiliser des alternatives Node uniquement aux commandes natives ou créer des binaires Linux à regrouper avec votre déploiement.

Nouvelle tentative

L'émulateur Cloud Functions ne permet pas de réessayer les fonctions en cas d'échec.

Et maintenant ?