Funktionen aus Ihrer App aufrufen


Mit den Cloud Functions for Firebase-Client-SDKs kannst du Funktionen direkt über eine Firebase-App. Um auf diese Weise eine Funktion aus Ihrer App aufzurufen, schreiben und implementieren Sie eine aufrufbare HTTP-Funktion in Cloud Functions und Fügen Sie dann Clientlogik hinzu, um die Funktion über Ihre App aufzurufen.

Beachten Sie, dass aufrufbare HTTP-Funktionen ähnlich sind, nicht mit HTTP-Funktionen identisch. Um HTTP-Funktionen zu verwenden, müssen Sie Verwenden Sie das Client-SDK für Ihre Plattform zusammen mit dem Back-End-API (oder implementieren Sie das Protokoll). Callables haben diese Schlüssel Unterschied zu HTTP-Funktionen:

  • Bei Callables werden Firebase Authentication-Tokens, FCM-Tokens und App Check-Tokens (sofern verfügbar) automatisch in Anfragen aufgenommen.
  • Der Trigger deserialisiert automatisch den Anfragetext und validiert Authentifizierungstokens.

Das Firebase SDK für Cloud Functions der 2. Generation und höher funktioniert mit diesem Firebase-Client SDK-Mindestversionen zur Unterstützung von aufrufbaren HTTPS-Funktionen:

  • Firebase SDK für Apple-Plattform 11.2.0
  • Firebase SDK für Android 21.0.0
  • Firebase Modular Web SDK Version 9.7.0

Wenn Sie einer App ähnliche Funktionen hinzufügen möchten, die auf einer nicht unterstützten finden Sie in der Protokollspezifikation für https.onCall. Der Rest dieses Leitfadens enthält Anleitungen zum Schreiben, Bereitstellen und Aufrufen eine aufrufbare HTTP-Funktion für Apple-Plattformen, Android, Web, C++ und Unity.

Callable-Funktion schreiben und bereitstellen

functions.https.onCall verwenden um eine aufrufbare HTTPS-Funktion zu erstellen. Diese Methode Für sind zwei Parameter erforderlich: data und optional context:

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

Bei einer aufrufbaren Funktion, die eine Textnachricht in Realtime Database speichert, könnte data beispielsweise den Nachrichtentext enthalten, während context-Parameter Informationen zur Nutzerauthentifizierung darstellen:

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

Der Abstand zwischen dem Speicherort der aufrufbaren Funktion und dem Speicherort des aufrufenden Clients kann zu Netzwerklatenz führen. Zur Leistungsoptimierung Sie sollten den Funktionsstandort angeben, wobei und achten Sie darauf, dass der Standort des Callables wird beim Initialisieren des SDK festgelegt auf der Clientseite.

Optional können Sie eine App Check-Attestierung anhängen, um Ihr wie Abrechnungsbetrug oder Phishing. Weitere Informationen finden Sie unter Erzwingung von App Check für Cloud Functions aktivieren.

Ergebnis zurücksenden

Wenn Sie Daten an den Client zurücksenden möchten, geben Sie Daten zurück, die JSON-codiert werden können. So geben Sie beispielsweise das Ergebnis einer Addition zurück:

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

Um nach einem asynchronen Vorgang Daten zurückzugeben, gib ein Promise zurück. Die Daten vom Promise zurückgegeben, wird an den Client zurückgesendet. Zum Beispiel haben Sie könnte bereinigten Text zurückgeben, den die aufrufbare Funktion in die Realtime Database geschrieben hat:

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

Fehler verarbeiten

Um sicherzustellen, dass der Client nützliche Fehlerdetails erhält, werden Fehler von einem Callable zurückgegeben. indem eine Instanz von functions.https.HttpsError Der Fehler enthält ein code-Attribut, das einer der aufgeführten Werte sein kann. um functions.https.HttpsError. Die Fehler haben auch den String message, der standardmäßig in einen leeren String. Sie können auch ein optionales details-Feld mit einem Beliebiger Wert. Wenn von deinen Funktionen ein anderer Fehler als HttpsError geworfen wird, erhält dein Client stattdessen eine Fehlermeldung mit der Meldung INTERNAL und dem Code internal.

Eine Funktion kann beispielsweise Datenvalidierungs- und Authentifizierungsfehler mit Fehlermeldungen zurückgeben, die an den aufrufenden Client gesendet werden:

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

Callable-Funktion bereitstellen

Nachdem Sie eine fertige aufrufbare Funktion in index.js gespeichert haben, wird sie zusammen mit allen anderen Funktionen bereitgestellt, wenn Sie firebase deploy ausführen. Wenn Sie nur das Callable bereitstellen möchten, verwenden Sie das Argument --only wie gezeigt Teilbereitstellungen:

firebase deploy --only functions:addMessage

Wenn beim Bereitstellen von Funktionen Berechtigungsfehler auftreten, achten Sie darauf, dass Die entsprechenden IAM-Rollen sind die dem Nutzer zugewiesen sind, der die Bereitstellungsbefehle ausführt.

Cliententwicklungsumgebung einrichten

Prüfen Sie, ob Sie alle Voraussetzungen erfüllen, und fügen Sie Ihrer App dann die erforderlichen Abhängigkeiten und Clientbibliotheken hinzu.

iOS+

Folgen Sie der Anleitung unter Firebase zu meiner Apple-App hinzufügen.

Verwenden Sie Swift Package Manager, um Firebase-Abhängigkeiten zu installieren und zu verwalten.

  1. Gehen Sie in Xcode bei geöffnetem App-Projekt zu File > Pakete hinzufügen.
  2. Fügen Sie bei entsprechender Aufforderung das Firebase Apple Platforms SDK-Repository hinzu:
  3.   https://github.com/firebase/firebase-ios-sdk.git
  4. Wählen Sie die Bibliothek Cloud Functions aus.
  5. Fügen Sie in den Build-Einstellungen des Ziels im Bereich Other Linker Flags das Flag -ObjC hinzu.
  6. Wenn Sie fertig, beginnt Xcode automatisch, Ihre Abhängigkeiten im Hintergrund aufzulösen und herunterzuladen.

Web

  1. Folgen Sie der Anleitung unter Firebase zu meiner Webanwendung hinzufügen. Führen Sie den folgenden Befehl in Ihrem Terminal aus:
    npm install firebase@10.13.1 --save
  2. Fordern Sie Firebase Core und Cloud Functions manuell an:

     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

  1. Folgen Sie der Anleitung unter Firebase zu meiner Webanwendung hinzufügen.
  2. Fügen Sie die Firebase Core- und Cloud Functions-Clientbibliotheken zu Ihrem App:
    <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>

Das Cloud Functions-SDK ist auch als npm-Paket verfügbar.

  1. Führen Sie im Terminal den folgenden Befehl aus:
    npm install firebase@8.10.1 --save
  2. Fordern Sie Firebase Core und Cloud Functions manuell an:
    const firebase = require("firebase");
    // Required for side-effects
    require("firebase/functions");

Kotlin+KTX

  1. Folgen Sie der Anleitung, um Firebase zu meiner Android-App hinzufügen

  2. In der Gradle-Datei des Moduls (auf App-Ebene) (normalerweise <project>/<app-module>/build.gradle.kts oder <project>/<app-module>/build.gradle) Fügen Sie die Abhängigkeit für die Cloud Functions-Bibliothek für Android hinzu. Wir empfehlen die Verwendung des Firebase Android BoM um die Versionsverwaltung der Bibliothek zu steuern.

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:33.2.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")
    }

    Mit der Firebase Android BoM haben Sie immer eine kompatible Version der Firebase Android-Bibliotheken in Ihrer App.

    (Alternative) Firebase-Bibliotheksabhängigkeiten ohne BoM hinzufügen

    Wenn Sie Firebase BoM nicht verwenden, müssen Sie jede Firebase-Bibliotheksversion angeben in der Abhängigkeitszeile ein.

    Wenn Sie in Ihrer App mehrere Firebase-Bibliotheken verwenden, empfehlen, Bibliotheksversionen mit der BoM zu verwalten. Dadurch wird sichergestellt, dass alle Versionen kompatibel.

    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")
    }
    Suchen Sie nach einem Kotlin-spezifischen Bibliotheksmodul? Beginnt in Oktober 2023 (Firebase BoM 32.5.0) können sowohl Kotlin- als auch Java-Entwickler sind vom Modul der Hauptbibliothek abhängig (Details finden Sie in der FAQs zu dieser Initiative).

Java

  1. Folgen Sie der Anleitung, um Firebase zu meiner Android-App hinzufügen

  2. In der Gradle-Datei des Moduls (auf App-Ebene) (normalerweise <project>/<app-module>/build.gradle.kts oder <project>/<app-module>/build.gradle) Fügen Sie die Abhängigkeit für die Cloud Functions-Bibliothek für Android hinzu. Wir empfehlen die Verwendung des Firebase Android BoM um die Versionsverwaltung der Bibliothek zu steuern.

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:33.2.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")
    }

    Mit dem Firebase Android BoM Ihre App verwendet immer kompatible Versionen der Firebase Android Libraries.

    Alternative: Firebase-Bibliotheksabhängigkeiten ohne BoM hinzufügen

    Wenn Sie Firebase BoM nicht verwenden, müssen Sie jede Firebase-Bibliotheksversion angeben in der Abhängigkeitszeile ein.

    Wenn Sie in Ihrer App mehrere Firebase-Bibliotheken verwenden, empfehlen, Bibliotheksversionen mit der BoM zu verwalten. Dadurch wird sichergestellt, dass alle Versionen kompatibel.

    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")
    }
    Suchen Sie nach einem Kotlin-spezifischen Bibliotheksmodul? Beginnt in Oktober 2023 (Firebase BoM 32.5.0) können sowohl Kotlin- als auch Java-Entwickler sind vom Modul der Hauptbibliothek abhängig (Details finden Sie in der FAQs zu dieser Initiative).

Dart

  1. Folgen Sie der Anleitung, um Fügen Sie Firebase zu Ihrer Flutter-App hinzu.

  2. Führen Sie im Stammverzeichnis Ihres Flutter-Projekts den folgenden Befehl aus, Installieren Sie das Plug-in:

    flutter pub add cloud_functions
    
  3. Erstellen Sie danach Ihre Flutter-Anwendung neu:

    flutter run
    
  4. Nach der Installation können Sie auf das cloud_functions-Plug-in zugreifen, indem Sie es in Ihren Dart-Code importieren:

    import 'package:cloud_functions/cloud_functions.dart';
    

C++

Für C++ mit Android:

  1. Folgen Sie der Anleitung, um Fügen Sie Firebase zu Ihrem C++-Projekt hinzu.
  2. Fügen Sie der Datei CMakeLists.txt die Bibliothek firebase_functions hinzu.

Für C++ mit Apple-Plattformen:

  1. Folgen Sie der Anleitung, um Fügen Sie Firebase zu Ihrem C++-Projekt hinzu.
  2. Fügen Sie den Pod Cloud Functions zu Ihrem Podfile hinzu:
    pod 'Firebase/Functions'
  3. Speichern Sie die Datei und führen Sie folgenden Befehl aus:
    pod install
  4. Fügen Sie die Firebase Core- und Cloud Functions-Frameworks aus der Firebase C++ SDK in Ihr Xcode-Projekt ein.
    • firebase.framework
    • firebase_functions.framework

Einheit

  1. Folgen Sie der Anleitung, um Fügen Sie Firebase zu Ihrem Unity-Projekt hinzu.
  2. Fügen Sie die FirebaseFunctions.unitypackage aus dem Firebase Unity SDK hinzu, um Ihr Unity-Projekt.

Client-SDK initialisieren

Initialisieren Sie eine Instanz von 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+KTX

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

Einheit

functions = Firebase.Functions.DefaultInstance;

Funktion aufrufen

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+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
        }
}

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

Einheit

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

Fehler auf dem Client verarbeiten

Der Client erhält eine Fehlermeldung, wenn der Server einen Fehler ausgegeben hat oder wenn der das daraus resultierende Versprechen abgelehnt wurde.

Wenn der von der Funktion zurückgegebene Fehler vom Typ function.https.HttpsError ist, erhält der Client die Fehler code, message und details von der Serverfehler. Andernfalls enthält der Fehler die Meldung INTERNAL und den Code INTERNAL. Hier finden Sie eine Anleitung dazu, wie Sie Fehler in der aufrufbaren Funktion verarbeiten.

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+KTX

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

Einheit

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

Bevor Sie Ihre App veröffentlichen, sollten Sie App Check aktivieren So sorgen Sie dafür, dass nur Ihre Apps auf Ihre aufrufbaren Funktionsendpunkte zugreifen können.