Fonctions d'appel depuis votre application


Les SDK client Cloud Functions pour 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, 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 pas identiques aux fonctions HTTP. Pour utiliser des fonctions appelables HTTP, vous devez utiliser le SDK client pour votre plate-forme avec l'API backend (ou implémenter le protocole). Les callables présentent les principales différences suivantes par rapport aux fonctions HTTP :

  • Avec les callables, les jetons d'authentification Firebase, les jetons FCM et les jetons App Check, lorsqu'ils sont disponibles, sont automatiquement inclus dans les demandes.
  • Le déclencheur désérialise automatiquement le corps de la demande et valide les jetons d'authentification.

Le SDK Firebase pour Cloud Functions 2e génération et versions ultérieures interagit avec ces versions minimales du SDK client Firebase pour prendre en charge les fonctions HTTPS Callable :

  • SDK Firebase pour les plates-formes Apple 10.19.0
  • SDK Firebase pour Android 20.4.0
  • SDK Web modulaire Firebase v.9.7.0

Si vous souhaitez ajouter des fonctionnalités similaires à une application créée sur une plate-forme non prise en charge, consultez la spécification de protocole pour https.onCall . Le reste de ce guide fournit des instructions sur la façon d'écrire, de déployer et d'appeler une fonction appelable HTTP pour les plateformes Apple, Android, Web, C++ et Unity.

Écrire et déployer la fonction appelable

Utilisez functions.https.onCall pour créer une fonction appelable HTTPS. Cette méthode prend deux paramètres : data et facultatif context :

// Saves a message to the Firebase Realtime Database but sanitizes the text by removing swearwords.
exports.addMessage = functions.https.onCall((data, context) => {
  // ...
});
index.js

Pour une fonction appelable qui enregistre un message texte dans la base de données en temps réel, par exemple, data peuvent contenir le texte du message, tandis que les paramètres context représentent les informations d'authentification de l'utilisateur :

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

La 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, pensez à spécifier l' emplacement de la fonction, le cas échéant, et assurez-vous d'aligner l'emplacement de l'appelable avec 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 abus, tels que la fraude à la facturation ou le phishing. Voir Activer l'application d'App Check pour Cloud Functions .

Renvoyer le résultat

Pour renvoyer des données au client, renvoyez des données qui peuvent être codées en 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,
};
index.js

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 le texte nettoyé que la fonction appelable a écrit dans la base de données en temps réel :

// Saving the new message to the Realtime Database.
const sanitizedMessage = sanitizer.sanitizeText(text); // Sanitize the message.
return admin.database().ref('/messages').push({
  text: sanitizedMessage,
  author: { uid, name, picture, email },
}).then(() => {
  console.log('New Message written');
  // Returning the sanitized message to the client.
  return { text: sanitizedMessage };
})
index.js

Gérer les erreurs

Pour garantir que le client obtient des détails d'erreur utiles, renvoyez les erreurs d'un appelable en lançant (ou en renvoyant une promesse rejetée avec) une instance de functions.https.HttpsError . L'erreur a un attribut code qui peut être l'une des valeurs répertoriées dans functions.https.HttpsError . Les erreurs ont également une chaîne message , qui est par défaut une chaîne vide. Ils peuvent également avoir un champ details facultatif avec une valeur arbitraire. Si une erreur autre que HttpsError est renvoyée par vos fonctions, votre client reçoit à la place une erreur avec le message INTERNAL et le code internal .

Par exemple, une fonction pourrait générer des erreurs de validation et d'authentification des données 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 functions.https.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 (!context.auth) {
  // Throwing an HttpsError so that the client gets the error details.
  throw new functions.https.HttpsError('failed-precondition', 'The function must be called ' +
      'while authenticated.');
}
index.js

Déployer la fonction appelable

Après avoir enregistré une fonction appelable terminée dans index.js , elle est déployée avec toutes les autres fonctions lorsque vous exécutez firebase deploy . Pour déployer uniquement l'appelable, utilisez l'argument --only comme indiqué pour effectuer des déploiements partiels :

firebase deploy --only functions:addMessage

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

Configurez votre environnement de développement client

Assurez-vous de remplir toutes les conditions préalables, puis ajoutez les dépendances et les bibliothèques client 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.

  1. Dans Xcode, avec votre projet d'application ouvert, accédez à File > Add Packages .
  2. Lorsque vous y êtes invité, ajoutez le référentiel SDK des plates-formes Apple Firebase :
    3.   https://github.com/firebase/firebase-ios-sdk.git
  3. Choisissez la bibliothèque Cloud Functions.
  4. Ajoutez l'indicateur -ObjC à la section Autres indicateurs de l'éditeur de liens des paramètres de construction de votre cible.
  5. Une fois terminé, Xcode commencera automatiquement à résoudre et à télécharger vos dépendances en arrière-plan.

API modulaire Web

  1. Suivez les instructions pour ajouter Firebase à votre application Web . Assurez-vous d'exécuter la commande suivante depuis votre terminal :
    npm install firebase@10.7.1 --save

  2. Exigez manuellement à la fois le noyau Firebase et les fonctions Cloud :

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

API avec espace de noms Web

  1. Suivez les instructions pour ajouter Firebase à votre application Web .
  2. Ajoutez les bibliothèques client Firebase Core et 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 SDK Cloud Functions est également disponible sous forme de package npm.

  1. Exécutez la commande suivante depuis votre terminal :
    npm install firebase@8.10.1 --save
  2. Exiger manuellement à la fois le noyau Firebase et les fonctions Cloud :
    const firebase = require("firebase");
// Required for side-effects
require("firebase/functions");

Kotlin+KTX

  1. Suivez les instructions pour ajouter 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 les fonctions Cloud. bibliothèque pour Android. Nous vous recommandons d'utiliser la BoM Android Firebase 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:32.7.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 la BoM

    Si vous choisissez de ne pas utiliser la BoM Firebase, 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 fortement d'utiliser la BoM pour gérer les versions de 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:20.4.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 s'appuyer sur le module de bibliothèque principal (pour plus de détails, consultez la FAQ sur cette initiative ).

Java

  1. Suivez les instructions pour ajouter 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 les fonctions Cloud. bibliothèque pour Android. Nous vous recommandons d'utiliser la BoM Android Firebase 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:32.7.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 la BoM

    Si vous choisissez de ne pas utiliser la BoM Firebase, 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 fortement d'utiliser la BoM pour gérer les versions de 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:20.4.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 s'appuyer sur le module de bibliothèque principal (pour plus de détails, consultez la FAQ sur cette initiative ).

Dart

  1. Suivez les instructions pour ajouter Firebase à votre application Flutter .

  2. Depuis la racine de votre projet Flutter, exécutez la commande suivante pour installer le plugin :

    flutter pub add cloud_functions

  3. Une fois terminé, reconstruisez votre application Flutter :

    flutter run

  4. Une fois installé, vous pouvez accéder au plugin cloud_functions en l'important dans votre code Dart :

    import 'package:cloud_functions/cloud_functions.dart';

C++

Pour C++ avec Android :

  1. Suivez les instructions pour ajouter Firebase à votre projet C++ .
  2. Ajoutez la bibliothèque firebase_functions à votre fichier CMakeLists.txt .

Pour le C++ avec les plateformes Apple :

  1. Suivez les instructions pour ajouter Firebase à votre projet C++ .
  2. Ajoutez le pod Cloud Functions à votre Podfile :
    pod 'Firebase/Functions'
  3. Enregistrez le fichier, puis exécutez :
    pod install
  4. Ajoutez le noyau Firebase et les frameworks Cloud Functions du SDK Firebase C++ à votre projet Xcode.
    • firebase.framework
    • firebase_functions.framework

Unité

  1. Suivez les instructions pour ajouter Firebase à votre projet Unity .
  2. Ajoutez le FirebaseFunctions.unitypackage du SDK Firebase Unity à votre projet Unity.

Initialiser le SDK client

Initialisez une instance de Cloud Functions :

Rapide

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

Objectif c

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

API avec espace de noms 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();

API modulaire 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

Dart

final functions = FirebaseFunctions.instance;

C++

firebase::functions::Functions* functions;
// ...
functions = firebase::functions::Functions::GetInstance(app);

Unité

functions = Firebase.Functions.DefaultInstance;

Appeler la fonction

Rapide

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

Objectif 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"];
}];

API avec espace de noms 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

API modulaire 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);
}

Unité

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 a généré une erreur 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 le code d'erreur, message et details de l'erreur du serveur. Sinon, l'erreur contient le message INTERNAL et le code INTERNAL . Consultez les conseils pour savoir comment gérer les erreurs dans votre fonction appelable.

Rapide

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

Objectif 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

API avec espace de noms 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

API modulaire 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);
  // ...

Unité

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

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