Les SDK clients Cloud Functions for Firebase vous permettent d'appeler des fonctions directement à partir d'une application Firebase. Pour appeler une fonction depuis votre application de cette manière, écrivez et déployez une fonction HTTP Callable dans Cloud Functions, et ajoutez ensuite une logique client pour appeler la fonction depuis votre application.
Il est important de garder à l'esprit que les fonctions HTTP Callable sont similaires, mais pas identiques aux fonctions HTTP. Pour utiliser des fonctions HTTP Callable, vous devez utiliser le SDK client pour votre plate-forme avec l'API backend (ou implémenter le protocole). Les fonctions Callable présentent les différences clés suivantes par rapport aux fonctions HTTP :
- Avec les fonctions Callable, les jetons Firebase Authentication, les jetons FCM et les jetons App Check, lorsqu'ils sont disponibles, 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 Firebase SDK pour Cloud Functions (2e génération et versions ultérieures) interagit avec les versions minimales suivantes du SDK client Firebase pour prendre en charge les fonctions HTTPS Callable :
- Firebase SDK pour les plates-formes Apple 12.11.0
- Firebase SDK pour Android 22.1.0
- SDK Web modulaire Firebase v. 9.7.0
Si vous souhaitez ajouter une fonctionnalité similaire à une application créée sur une plate-forme non compatible, consultez la spécification du protocole pour https.onCall. Le reste de ce guide fournit des instructions sur l'écriture, le déploiement et l'appel d'une fonction HTTP Callable pour les plates-formes Apple, Android, le Web, C++ et Unity.
Écrire et déployer la fonction Callable
Utilisez functions.https.onCall
pour créer une fonction HTTPS Callable. Cette méthode comporte deux paramètres : data et context facultatif :
// Saves a message to the Firebase Realtime Database but sanitizes the // text by removing swearwords. exports.addMessage = functions.https.onCall((data, context) => { // ... });
Pour une fonction Callable qui enregistre un message texte dans la Realtime Database,
par exemple, data peut contenir le texte du message, tandis que les context
paramètres représentent les informations d'authentification de l'utilisateur :
// 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;
La distance entre l'emplacement de la fonction Callable et celui du client appelant peut créer une latence réseau. Pour optimiser les performances, envisagez de spécifier l'emplacement de la fonction, le cas échéant, et assurez-vous d'aligner l'emplacement de la fonction Callable sur celui défini lors de l'initialisation du SDK côté client.
Vous pouvez également joindre une attestation App Check pour protéger vos ressources backend contre les utilisations abusives, telles que la fraude à la facturation ou le hameçonnage. Consultez Activer App Check l'application pour Cloud Functions.
Renvoyer le résultat
Pour renvoyer des données au client, renvoyez des données qui peuvent être encodées au format JSON. Par exemple, pour renvoyer le résultat d'une opération d'addition :
// returning result.
return {
firstNumber: firstNumber,
secondNumber: secondNumber,
operator: "+",
operationResult: firstNumber + secondNumber,
};
Pour renvoyer des données après une opération asynchrone, renvoyez une promesse. Les données renvoyées par la promesse sont renvoyées au client. Par exemple, vous pouvez renvoyer du texte nettoyé que la fonction Callable a écrit dans la Realtime Database :
// 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};
})
Gérer les erreurs
Pour vous assurer que le client reçoit des informations utiles sur les erreurs, renvoyez les erreurs d'une fonction Callable en générant (ou en renvoyant une promesse rejetée avec) une instance de functions.https.HttpsError.
L'erreur comporte un attribut code qui peut être l'une des valeurs listées
dans functions.https.HttpsError.
Les erreurs comportent également un message de chaîne, qui est défini par défaut sur une chaîne vide. Elles peuvent également comporter un champ details facultatif avec une valeur arbitraire. Si une erreur autre que HttpsError est générée à partir de vos fonctions, votre client reçoit 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 :
// 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.");
}
Déployer la fonction Callable
Une fois que vous avez enregistré une fonction Callable terminée dans index.js, elle est déployée avec toutes les autres fonctions lorsque vous exécutez firebase deploy.
Pour ne déployer que la fonction Callable, 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 votre environnement de développement client
Assurez-vous de respecter les prérequis, puis ajoutez les dépendances et les bibliothèques clientes requises à 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.
- Dans Xcode, à partir de votre projet d'application ouvert, accédez à File > Add Packages (Fichier > Ajouter des packages).
- Lorsque vous y êtes invité, ajoutez le dépôt du SDK des plates-formes Firebase pour Apple :
- Choisissez la Cloud Functions bibliothèque.
- Ajoutez l'indicateur
-ObjCà la section Other Linker Flags (Autres indicateurs Linker) des paramètres de compilation de votre cible. - Lorsque vous avez terminé, Xcode commence à résoudre et à télécharger automatiquement vos dépendances en arrière-plan.
https://github.com/firebase/firebase-ios-sdk.git
Web
- Suivez les instructions pour
ajouter Firebase à votre application Web. Assurez-vous d'exécuter
la commande suivante à partir de votre terminal :
npm install firebase@12.11.0 --save
Chargez manuellement le cœur de 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);
Web
- Suivez les instructions pour ajouter Firebase à votre application Web.
- Ajoutez les bibliothèques clientes du cœur de Firebase et de Cloud Functions à votre
application :
<script src="https://www.gstatic.com/firebasejs/8.10.1/firebase.js"></script> <script src="https://www.gstatic.com/firebasejs/8.10.1/firebase-functions.js"></script>
Le Cloud Functions SDK est également disponible en tant que package npm.
- Exécutez la commande suivante à partir de votre terminal :
npm install firebase@8.10.1 --save
- Chargez manuellement le cœur de Firebase et Cloud Functions :
const firebase = require("firebase"); // Required for side-effects require("firebase/functions");
Kotlin
Suivez les instructions pour ajouter Firebase à votre application Android.
Dans le fichier Gradle de votre module (au niveau de l'application) (généralement
<project>/<app-module>/build.gradle.ktsou<project>/<app-module>/build.gradle), ajoutez la dépendance pour la bibliothèque Cloud Functions pour Android. Nous vous recommandons d'utiliser la Firebase Android BoM pour contrôler la gestion des versions de la bibliothèque.dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:34.11.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 les Firebase Android BoM, votre application utilisera toujours des versions compatibles des bibliothèques Firebase Android.
(Autre solution) Ajouter des dépendances de bibliothèque Firebase sans utiliser la BoM
Si vous choisissez de ne pas utiliser la 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, nous vous recommandons vivement d'utiliser la BoM pour gérer les versions des bibliothèques, 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:22.1.0") }
Java
Suivez les instructions pour ajouter Firebase à votre application Android.
Dans le fichier Gradle de votre module (au niveau de l'application) (généralement
<project>/<app-module>/build.gradle.ktsou<project>/<app-module>/build.gradle), ajoutez la dépendance pour la bibliothèque Cloud Functions pour Android. Nous vous recommandons d'utiliser la Firebase Android BoM pour contrôler la gestion des versions de la bibliothèque.dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:34.11.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 les Firebase Android BoM, votre application utilisera toujours des versions compatibles des bibliothèques Firebase Android.
(Autre solution) Ajouter des dépendances de bibliothèque Firebase sans utiliser la BoM
Si vous choisissez de ne pas utiliser la 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, nous vous recommandons vivement d'utiliser la BoM pour gérer les versions des bibliothèques, 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:22.1.0") }
Dart
Suivez les instructions pour ajouter Firebase à votre application Flutter.
À la racine de votre projet Flutter, exécutez la commande suivante pour installer le plug-in :
flutter pub add cloud_functionsUne fois l'opération terminée, recréez votre application Flutter :
flutter runUne fois installé, vous pouvez accéder au plug-in
cloud_functionsen l'important dans votre code Dart :import 'package:cloud_functions/cloud_functions.dart';
C++
Pour C++ avec Android :
- Suivez les instructions pour ajouter Firebase à votre projet C++.
- Ajoutez la bibliothèque
firebase_functionsà votre fichierCMakeLists.txt.
Pour C++ avec les plates-formes Apple :
- Suivez les instructions pour ajouter Firebase à votre projet C++.
- Ajoutez le Cloud Functions pod à votre
Podfile:pod 'Firebase/Functions'
- Enregistrez le fichier, puis exécutez :
pod install
- Ajoutez les frameworks du cœur de Firebase et Cloud Functions à partir du
Firebase C++ SDK à votre projet Xcode.
firebase.frameworkfirebase_functions.framework
Unity
- Suivez les instructions pour ajouter Firebase à votre projet Unity.
- Ajoutez le
FirebaseFunctions.unitypackagedu Firebase Unity SDK à votre projet Unity.
Initialiser le SDK client
Initialisez une instance de Cloud Functions :
Swift
lazy var functions = Functions.functions()
Objective-C
@property(strong, nonatomic) FIRFunctions *functions;
// ...
self.functions = [FIRFunctions functions];
Web
firebase.initializeApp({
apiKey: '### FIREBASE API KEY ###',
authDomain: '### FIREBASE AUTH DOMAIN ###',
projectId: '### CLOUD FUNCTIONS PROJECT ID ###'
databaseURL: 'https://### YOUR DATABASE NAME ###.firebaseio.com',
});
// Initialize Cloud Functions through Firebase
var functions = firebase.functions();
Web
const app = initializeApp({
projectId: '### CLOUD FUNCTIONS PROJECT ID ###',
apiKey: '### FIREBASE API KEY ###',
authDomain: '### FIREBASE AUTH DOMAIN ###',
});
const functions = getFunctions(app);
Kotlin
private lateinit var functions: FirebaseFunctions // ... functions = Firebase.functions
Java
private FirebaseFunctions mFunctions; // ... mFunctions = FirebaseFunctions.getInstance();
Dart
final functions = FirebaseFunctions.instance;
C++
firebase::functions::Functions* functions;
// ...
functions = firebase::functions::Functions::GetInstance(app);
Unity
functions = Firebase.Functions.DefaultInstance;
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
}
}
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;
});
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;
});
Kotlin
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 } }
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; } }); }
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 en a généré une ou si la promesse résultante a été rejetée.
Si l'erreur renvoyée par la fonction est de type function.https.HttpsError,
le client reçoit l'erreur code, message, et details de l'erreur du
serveur. Sinon, l'erreur contient le message INTERNAL et le code INTERNAL. Consultez les conseils sur la gestion des erreurs dans votre fonction Callable.
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]
}
// ...
}
Objective-C
if (error) {
if ([error.domain isEqual:@"com.firebase.functions"]) {
FIRFunctionsErrorCode code = error.code;
NSString *message = error.localizedDescription;
NSObject *details = error.userInfo[@"details"];
}
// ...
}
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;
// ...
});
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;
// ...
});
Kotlin
addMessage(inputMessage) .addOnCompleteListener { task -> if (!task.isSuccessful) { val e = task.exception if (e is FirebaseFunctionsException) { val code = e.code val details = e.details } } }
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(); } } } });
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 : Empêcher les utilisations abusives avec App Check
Avant de lancer votre application, vous devez activer App Check pour vous assurer que seules vos applications peuvent accéder aux points de terminaison de votre fonction Callable.