Fonctions d'appel depuis votre application

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

Les SDK client Cloud Functions for Firebase vous permettent d'appeler des fonctions directement à partir de une application Firebase. Pour appeler une fonction de cette manière à partir de votre application, écrivez et déployez Une fonction HTTP Callable dans Cloud Functions puis ajoutez une logique client pour appeler la fonction depuis votre application.

Il est important de garder à l'esprit que les fonctions appelables HTTP sont similaires, mais différentes des fonctions HTTP. Pour utiliser des fonctions appelables HTTP, vous devez utiliser le SDK client de votre plate-forme avec l'API backend (ou implémenter le protocole). Les fonctions appelables présentent les principales différences suivantes par rapport aux fonctions HTTP :

• Avec les fonctions appelables, les jetons Firebase Authentication, FCM et App Check, le cas échéant, sont automatiquement inclus dans les requêtes.
• Le déclencheur désérialise automatiquement le corps de la requête et valide les jetons d'authentification.

Le SDK Firebase pour Cloud Functions 2e génération et les versions ultérieures interagissent avec ce client Firebase Versions minimales du SDK compatibles avec les fonctions HTTPS Appelables:

• SDK Firebase pour les plates-formes Apple 11.2.0
• SDK Firebase pour Android 21.0.0
• SDK Web modulaire Firebase version 9.7.0

Si vous souhaitez ajouter une fonctionnalité similaire à une application compilée sur une plate-forme non prise en charge, consultez la spécification du protocole pour https.onCall. Le reste de ce guide fournit des instructions pour écrire, déployer et appeler Une fonction HTTP appelable pour les plates-formes Apple, Android, le Web, C++ et Unity.

Écrire et déployer la fonction appelable

Les exemples de code présentés dans cette section sont basés sur un exemple de démarrage rapide qui montre comment envoyer des requêtes à une fonction côté serveur et obtenir à l'aide de l'un des SDK clients. Pour commencer, importez les modules requis :

Node.js

// Dependencies for callable functions.
const {onCall, HttpsError} = require("firebase-functions/v2/https");
const {logger} = require("firebase-functions/v2");

// Dependencies for the addMessage function.
const {getDatabase} = require("firebase-admin/database");
const sanitizer = require("./sanitizer");
index.js

Python

# Dependencies for callable functions.
from firebase_functions import https_fn, options

# Dependencies for writing to Realtime Database.
from firebase_admin import db, initialize_app
main.py

Utilisez le gestionnaire de requêtes de votre plate-forme (functions.https.onCall) ou on_call pour créer une fonction appelable HTTPS. Cette méthode utilise un paramètre de requête :

Node.js

// Saves a message to the Firebase Realtime Database but sanitizes the
// text by removing swearwords.
exports.addmessage = onCall((request) => {
  // ...
});
index.js

Python

@https_fn.on_call()
def addmessage(req: https_fn.CallableRequest) -> Any:
    """Saves a message to the Firebase Realtime Database but sanitizes the text
    by removing swear words."""
main.py

Le paramètre request contient les données transmises par l'application cliente, ainsi que des contextes supplémentaires tels que l'état d'authentification. Pour une fonction appelable qui enregistre un message texte dans Realtime Database, par exemple, data peut contenir le texte du message, ainsi que des informations d'authentification dans auth :

Node.js

// Message text passed from the client.
const text = request.data.text;
// Authentication / user information is automatically added to the request.
const uid = request.auth.uid;
const name = request.auth.token.name || null;
const picture = request.auth.token.picture || null;
const email = request.auth.token.email || null;
index.js

Python

# Message text passed from the client.
text = req.data["text"]
main.py
# Authentication / user information is automatically added to the request.
uid = req.auth.uid
name = req.auth.token.get("name", "")
picture = req.auth.token.get("picture", "")
email = req.auth.token.get("email", "")
main.py

Distance entre l'emplacement de la fonction appelable et l'emplacement du client appelant peut créer une latence du réseau. Pour optimiser les performances, envisagez de spécifier l'emplacement de la fonction le cas échéant et veillez à aligner l'emplacement de l'appelable sur l'emplacement défini lorsque vous initialisez le SDK côté client.

Vous pouvez éventuellement joindre une attestation App Check pour protéger vos ressources backend contre les utilisations abusives, telles que la fraude à la facturation ou l'hameçonnage. Voir Activer l'application forcée de App Check pour Cloud Functions

Remarque : N'utilisez que les API backend functions.https ou firebase_functions.https_fn pour écrire des fonctions appelables. La L'API du déclencheur HTTP est entièrement distincts et non interopérables avec les fonctions appelables.

Renvoi du résultat

Pour renvoyer des données au client, renvoyez des données pouvant être encodées au format JSON. Par exemple, pour renvoyer le résultat d'une opération d'addition :

Node.js

// returning result.
return {
  firstNumber: firstNumber,
  secondNumber: secondNumber,
  operator: "+",
  operationResult: firstNumber + secondNumber,
};
index.js

Python

return {
    "firstNumber": first_number,
    "secondNumber": second_number,
    "operator": "+",
    "operationResult": first_number + second_number
}
main.py

Le texte nettoyé de l'exemple de texte du message est renvoyé à la fois au client et au Realtime Database. Dans Node.js, cela peut être fait de manière asynchrone à l'aide d'une promesse JavaScript :

Node.js

// Saving the new message to the Realtime Database.
const sanitizedMessage = sanitizer.sanitizeText(text); // Sanitize message.

return getDatabase().ref("/messages").push({
  text: sanitizedMessage,
  author: {uid, name, picture, email},
}).then(() => {
  logger.info("New Message written");
  // Returning the sanitized message to the client.
  return {text: sanitizedMessage};
})
index.js

Python

# Saving the new message to the Realtime Database.
sanitized_message = sanitize_text(text)  # Sanitize message.
db.reference("/messages").push({  # type: ignore
    "text": sanitized_message,
    "author": {
        "uid": uid,
        "name": name,
        "picture": picture,
        "email": email
    }
})
print("New message written")

# Returning the sanitized message to the client.
return {"text": sanitized_message}
main.py

Configurer CORS (Cross-Origin Resource Sharing)

Utilisez l'option cors pour contrôler les origines qui peuvent accéder à votre fonction.

Par défaut, le protocole CORS est configuré pour autoriser les requêtes provenant de toutes les origines dans les fonctions appelables. Pour autoriser certaines requêtes inter-origines, mais pas toutes, transmettez une liste de domaines ou d'expressions régulières spécifiques à autoriser. Exemple :

Node.js

const { onCall } = require("firebase-functions/v2/https");

exports.getGreeting = onCall(
  { cors: [/firebase\.com$/, "https://flutter.com"] },
  (request) => {
    return "Hello, world!";
  }
);

Pour interdire les demandes d'origines multiples, définissez la règle cors sur false.

Gérer les erreurs

Pour vous assurer que le client reçoit des informations d'erreur utiles, renvoyez les erreurs d'un appelable en générant (ou pour Node.js en renvoyant une promesse rejetée avec) une instance de functions.https.HttpsError ou https_fn.HttpsError. L'erreur comporte un attribut code qui peut correspondre à l'une des valeurs répertoriées dans gRPC Codes d'état : Les erreurs comportent également une chaîne message, qui est par défaut une chaîne vide. Ils peuvent également comporter un champ details facultatif avec une valeur arbitraire. Si une erreur autre qu'une erreur HTTPS est générée par vos fonctions, votre client reçoit à la place une erreur avec le message INTERNAL et le code internal

Par exemple, une fonction peut générer des erreurs de validation des données et d'authentification avec des messages d'erreur à renvoyer au client appelant :

Node.js

// Checking attribute.
if (!(typeof text === "string") || text.length === 0) {
  // Throwing an HttpsError so that the client gets the error details.
  throw new HttpsError("invalid-argument", "The function must be called " +
          "with one arguments \"text\" containing the message text to add.");
}
// Checking that the user is authenticated.
if (!request.auth) {
  // Throwing an HttpsError so that the client gets the error details.
  throw new HttpsError("failed-precondition", "The function must be " +
          "called while authenticated.");
}
index.js

Python

# Checking attribute.
if not isinstance(text, str) or len(text) < 1:
    # Throwing an HttpsError so that the client gets the error details.
    raise https_fn.HttpsError(code=https_fn.FunctionsErrorCode.INVALID_ARGUMENT,
                              message=('The function must be called with one argument, "text",'
                                       " containing the message text to add."))

# Checking that the user is authenticated.
if req.auth is None:
    # Throwing an HttpsError so that the client gets the error details.
    raise https_fn.HttpsError(code=https_fn.FunctionsErrorCode.FAILED_PRECONDITION,
                              message="The function must be called while authenticated.")
main.py

Déployer la fonction appelable

Une fois que vous avez enregistré une fonction appelable terminée dans index.js, elle est déployé avec toutes les autres fonctions lorsque vous exécutez firebase deploy. Pour ne déployer que le fonctionnable, utilisez l'argument --only comme indiqué pour effectuer des déploiements partiels :

firebase deploy --only functions:addMessage

Si vous rencontrez des erreurs d'autorisation lors du déploiement de fonctions, assurez-vous que les rôles IAM appropriés sont attribués à l'utilisateur qui exécute les commandes de déploiement.

Configurer l'environnement de développement de votre client

Assurez-vous de remplir toutes les conditions préalables, puis ajoutez les dépendances requises bibliothèques clientes à votre application.

iOS+

Suivez les instructions pour ajouter Firebase à votre application Apple.

Utilisez Swift Package Manager pour installer et gérer les dépendances Firebase.

Consultez notre guide d'installation pour découvrir les différentes façons d'ajouter des SDK Firebase à votre projet Apple, y compris l'importation directe des frameworks et l'utilisation de CocoaPods.

1. Dans Xcode, à partir de votre projet d'application ouvert, accédez à File > Add Packages (Fichier > Ajouter des packages).
2. Lorsque vous y êtes invité, ajoutez le dépôt du SDK des plates-formes Firebase pour Apple :

  https://github.com/firebase/firebase-ios-sdk.git

Remarque : Les nouveaux projets utilisent la version par défaut du SDK (la plus récente), mais vous pouvez choisir une version plus ancienne si nécessaire.
3. Sélectionnez la bibliothèque Cloud Functions.
4. Ajoutez l'indicateur -ObjC à la section Other Linker Flags (Autres indicateurs Linker) des paramètres de compilation de votre cible.
5. Lorsque vous avez terminé, Xcode commence à résoudre et à télécharger automatiquement vos dépendances en arrière-plan.

Web

1. Suivez les instructions pour ajouter Firebase à votre application Web. Veillez à exécuter la commande suivante à partir de votre terminal :

   npm install firebase@10.13.2 --save

2. Exigez manuellement le noyau Firebase et Cloud Functions :

    import { initializeApp } from 'firebase/app';
    import { getFunctions } from 'firebase/functions';
   
    const app = initializeApp({
        projectId: '### CLOUD FUNCTIONS PROJECT ID ###',
        apiKey: '### FIREBASE API KEY ###',
        authDomain: '### FIREBASE AUTH DOMAIN ###',
      });
    const functions = getFunctions(app);

Android

1. Suivez les instructions pour Ajoutez Firebase à votre application Android.

2. Dans le fichier Gradle de votre module (au niveau de l'application) (généralement <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), ajoutez la dépendance pour la bibliothèque Cloud Functions pour Android. Nous vous recommandons d'utiliser Firebase Android BoM pour contrôler la gestion des versions des bibliothèques.

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:33.3.0"))
   
       // Add the dependency for the Cloud Functions library
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-functions")
   }

   En utilisant Firebase Android BoM, votre application utilisera toujours des versions compatibles des bibliothèques Firebase Android.

   (Alternative) Ajouter des dépendances de la bibliothèque Firebase sans utiliser l'BoM

   Si vous choisissez de ne pas utiliser Firebase BoM, vous devez spécifier chaque version de la bibliothèque Firebase dans sa ligne de dépendance.

   Notez que si vous utilisez plusieurs bibliothèques Firebase dans votre application, recommandent d'utiliser BoM pour gérer les versions de la bibliothèque, ce qui garantit que toutes les versions sont compatibles.

   dependencies {
       // Add the dependency for the Cloud Functions library
       // When NOT using the BoM, you must specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-functions:21.0.0")
   }

   Vous recherchez un module de bibliothèque spécifique à Kotlin ? À partir d'octobre 2023 (Firebase BoM 32.5.0), les développeurs Kotlin et Java peuvent dépendre du module de bibliothèque principal (pour en savoir plus, consultez les questions fréquentes sur cette initiative).

Initialiser le SDK client

Initialisez une instance de Cloud Functions:

Swift

lazy var functions = Functions.functions()
CloudAddCell.swift

Objective-C

@property(strong, nonatomic) FIRFunctions *functions;
// ...
self.functions = [FIRFunctions functions];
CloudAddCell.m

Web

const app = initializeApp({
  projectId: '### CLOUD FUNCTIONS PROJECT ID ###',
  apiKey: '### FIREBASE API KEY ###',
  authDomain: '### FIREBASE AUTH DOMAIN ###',
});
const functions = getFunctions(app);

Kotlin+KTX

private lateinit var functions: FirebaseFunctions
// ...
functions = Firebase.functions
MainActivity.kt

Java

private FirebaseFunctions mFunctions;
// ...
mFunctions = FirebaseFunctions.getInstance();
MainActivity.java

Remarque : Pour appeler une fonction exécutée dans un emplacement autre que l'us-central1 par défaut, vous devez définir la valeur appropriée lors de l'initialisation. Par exemple, sur Android, vous devez initialiser avec getInstance(FirebaseApp app, String region).

Appeler la fonction

Swift

functions.httpsCallable("addMessage").call(["text": inputField.text]) { result, error in
  if let error = error as NSError? {
    if error.domain == FunctionsErrorDomain {
      let code = FunctionsErrorCode(rawValue: error.code)
      let message = error.localizedDescription
      let details = error.userInfo[FunctionsErrorDetailsKey]
    }
    // ...
  }
  if let data = result?.data as? [String: Any], let text = data["text"] as? String {
    self.resultField.text = text
  }
}
CommentCell.swift

Objective-C

[[_functions HTTPSCallableWithName:@"addMessage"] callWithObject:@{@"text": _inputField.text}
                                                      completion:^(FIRHTTPSCallableResult * _Nullable result, NSError * _Nullable error) {
  if (error) {
    if ([error.domain isEqual:@"com.firebase.functions"]) {
      FIRFunctionsErrorCode code = error.code;
      NSString *message = error.localizedDescription;
      NSObject *details = error.userInfo[@"details"];
    }
    // ...
  }
  self->_resultField.text = result.data[@"text"];
}];

Web

var addMessage = firebase.functions().httpsCallable('addMessage');
addMessage({ text: messageText })
  .then((result) => {
    // Read result of the Cloud Function.
    var sanitizedMessage = result.data.text;
  });
callable.js

Web

import { getFunctions, httpsCallable } from "firebase/functions";

const functions = getFunctions();
const addMessage = httpsCallable(functions, 'addMessage');
addMessage({ text: messageText })
  .then((result) => {
    // Read result of the Cloud Function.
    /** @type {any} */
    const data = result.data;
    const sanitizedMessage = data.text;
  });
fb_functions_call_add_message.js

Kotlin+KTX

private fun addMessage(text: String): Task<String> {
    // Create the arguments to the callable function.
    val data = hashMapOf(
        "text" to text,
        "push" to true,
    )

    return functions
        .getHttpsCallable("addMessage")
        .call(data)
        .continueWith { task ->
            // This continuation runs on either success or failure, but if the task
            // has failed then result will throw an Exception which will be
            // propagated down.
            val result = task.result?.data as String
            result
        }
}
MainActivity.kt

Java

private Task<String> addMessage(String text) {
    // Create the arguments to the callable function.
    Map<String, Object> data = new HashMap<>();
    data.put("text", text);
    data.put("push", true);

    return mFunctions
            .getHttpsCallable("addMessage")
            .call(data)
            .continueWith(new Continuation<HttpsCallableResult, String>() {
                @Override
                public String then(@NonNull Task<HttpsCallableResult> task) throws Exception {
                    // This continuation runs on either success or failure, but if the task
                    // has failed then getResult() will throw an Exception which will be
                    // propagated down.
                    String result = (String) task.getResult().getData();
                    return result;
                }
            });
}
MainActivity.java

Dart

    final result = await FirebaseFunctions.instance.httpsCallable('addMessage').call(
      {
        "text": text,
        "push": true,
      },
    );
    _response = result.data as String;

C++

firebase::Future<firebase::functions::HttpsCallableResult> AddMessage(
    const std::string& text) {
  // Create the arguments to the callable function.
  firebase::Variant data = firebase::Variant::EmptyMap();
  data.map()["text"] = firebase::Variant(text);
  data.map()["push"] = true;

  // Call the function and add a callback for the result.
  firebase::functions::HttpsCallableReference doSomething =
      functions->GetHttpsCallable("addMessage");
  return doSomething.Call(data);
}

Unity

private Task<string> addMessage(string text) {
  // Create the arguments to the callable function.
  var data = new Dictionary<string, object>();
  data["text"] = text;
  data["push"] = true;

  // Call the function and extract the operation from the result.
  var function = functions.GetHttpsCallable("addMessage");
  return function.CallAsync(data).ContinueWith((task) => {
    return (string) task.Result.Data;
  });
}

Gérer les erreurs sur le client

Le client reçoit une erreur si le serveur génère une erreur ou si le la promesse qui en résulte a été rejetée.

Si l'erreur renvoyée par la fonction est de type function.https.HttpsError, le client reçoit les erreurs code, message et details de l'erreur du serveur. Sinon, l'erreur contient le message INTERNAL et code INTERNAL. Découvrez comment gérer les erreurs dans votre fonction appelable.

Swift

if let error = error as NSError? {
  if error.domain == FunctionsErrorDomain {
    let code = FunctionsErrorCode(rawValue: error.code)
    let message = error.localizedDescription
    let details = error.userInfo[FunctionsErrorDetailsKey]
  }
  // ...
}
CloudAddCell.swift

Objective-C

if (error) {
  if ([error.domain isEqual:@"com.firebase.functions"]) {
    FIRFunctionsErrorCode code = error.code;
    NSString *message = error.localizedDescription;
    NSObject *details = error.userInfo[@"details"];
  }
  // ...
}
CloudAddCell.m

Web

var addMessage = firebase.functions().httpsCallable('addMessage');
addMessage({ text: messageText })
  .then((result) => {
    // Read result of the Cloud Function.
    var sanitizedMessage = result.data.text;
  })
  .catch((error) => {
    // Getting the Error details.
    var code = error.code;
    var message = error.message;
    var details = error.details;
    // ...
  });
callable.js

Web

import { getFunctions, httpsCallable } from "firebase/functions";

const functions = getFunctions();
const addMessage = httpsCallable(functions, 'addMessage');
addMessage({ text: messageText })
  .then((result) => {
    // Read result of the Cloud Function.
    /** @type {any} */
    const data = result.data;
    const sanitizedMessage = data.text;
  })
  .catch((error) => {
    // Getting the Error details.
    const code = error.code;
    const message = error.message;
    const details = error.details;
    // ...
  });
fb_functions_call_add_message_error.js

Kotlin+KTX

addMessage(inputMessage)
    .addOnCompleteListener { task ->
        if (!task.isSuccessful) {
            val e = task.exception
            if (e is FirebaseFunctionsException) {
                val code = e.code
                val details = e.details
            }
        }
    }
MainActivity.kt

Java

addMessage(inputMessage)
        .addOnCompleteListener(new OnCompleteListener<String>() {
            @Override
            public void onComplete(@NonNull Task<String> task) {
                if (!task.isSuccessful()) {
                    Exception e = task.getException();
                    if (e instanceof FirebaseFunctionsException) {
                        FirebaseFunctionsException ffe = (FirebaseFunctionsException) e;
                        FirebaseFunctionsException.Code code = ffe.getCode();
                        Object details = ffe.getDetails();
                    }
                }
            }
        });
MainActivity.java

Dart

try {
  final result =
      await FirebaseFunctions.instance.httpsCallable('addMessage').call();
} on FirebaseFunctionsException catch (error) {
  print(error.code);
  print(error.details);
  print(error.message);
}

C++

void OnAddMessageCallback(
    const firebase::Future<firebase::functions::HttpsCallableResult>& future) {
  if (future.error() != firebase::functions::kErrorNone) {
    // Function error code, will be kErrorInternal if the failure was not
    // handled properly in the function call.
    auto code = static_cast<firebase::functions::Error>(future.error());

    // Display the error in the UI.
    DisplayError(code, future.error_message());
    return;
  }

  const firebase::functions::HttpsCallableResult* result = future.result();
  firebase::Variant data = result->data();
  // This will assert if the result returned from the function wasn't a string.
  std::string message = data.string_value();
  // Display the result in the UI.
  DisplayResult(message);
}

// ...

// ...
  auto future = AddMessage(message);
  future.OnCompletion(OnAddMessageCallback);
  // ...

Unity

 addMessage(text).ContinueWith((task) => {
  if (task.IsFaulted) {
    foreach (var inner in task.Exception.InnerExceptions) {
      if (inner is FunctionsException) {
        var e = (FunctionsException) inner;
        // Function error code, will be INTERNAL if the failure
        // was not handled properly in the function call.
        var code = e.ErrorCode;
        var message = e.ErrorMessage;
      }
    }
  } else {
    string result = task.Result;
  }
});

Recommandation : Éviter les abus avec App Check

Avant de lancer votre application, vous devez activer App Check pour vous assurer que seules vos applications peuvent accéder à vos points de terminaison de fonction appelables.