Mit den Cloud Functions for Firebase Client-SDKs können Sie Funktionen direkt über eine Firebase-App aufrufen. Dazu müssen Sie eine HTTP-Funktion erstellen und bereitstellen in Cloud Functions, und dann Clientlogik hinzufügen, um die Funktion aus Ihrer App aufzurufen.
Es ist wichtig zu beachten, dass HTTP-Funktionen ähnlich, aber nicht identisch mit HTTP-Funktionen sind. Wenn Sie HTTP-Funktionen verwenden möchten, müssen Sie das Client-SDK für Ihre Plattform zusammen mit der Backend-API verwenden (oder das Protokoll implementieren). Es gibt folgende Hauptunterschiede zwischen HTTP-Funktionen und Funktionen:
- Bei Funktionen werden Firebase Authentication Tokens, FCM Tokens und App Check Tokens, sofern verfügbar, automatisch in Anfragen eingefügt.
- Der Trigger deserialisiert den Anfragetext automatisch und validiert Authentifizierungstokens.
Das Firebase SDK für Cloud Functions der 2. Generation und höher ist mit den folgenden Mindestversionen des Firebase-Client SDK kompatibel, um HTTPS-Funktionen zu unterstützen:
- Firebase SDK for Apple platforms 12.11.0
- Firebase SDK for Android 22.1.0
- Firebase Modular Web SDK, Version 9.7.0
Wenn Sie einer App, die auf einer nicht unterstützten
Plattform basiert, ähnliche Funktionen hinzufügen möchten, lesen Sie die Protokollspezifikation für https.onCall. Im Rest dieser Anleitung erfahren Sie, wie Sie eine HTTP-Funktion für Apple-Plattformen, Android, Web, C++ und Unity schreiben, bereitstellen und aufrufen.
Funktion schreiben und bereitstellen
Verwenden Sie functions.https.onCall
, um eine HTTPS-Funktion zu erstellen. Diese Methode verwendet zwei Parameter: 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 Funktion, die eine Textnachricht in der 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;
Die Entfernung zwischen dem Standort der Funktion und dem Standort des aufrufenden Clients kann zu Netzwerklatenz führen. Um die Leistung zu optimieren, geben Sie gegebenenfalls den Funktionsstandort an und richten Sie den Standort der Funktion an dem Standort aus, der beim Initialisieren des SDK auf der Clientseite festgelegt wurde.
Optional können Sie eine App Check Bestätigung anhängen, um Ihre Backend-Ressourcen vor Missbrauch wie Abrechnungsbetrug oder Phishing zu schützen. Weitere Informationen finden Sie unter App Check Erzwingung für Cloud Functions.
Ergebnis zurücksenden
Wenn Sie Daten an den Client zurücksenden möchten, geben Sie Daten zurück, die im JSON-Format codiert werden können. Beispiel: So geben Sie das Ergebnis einer Additionsoperation zurück:
// returning result.
return {
firstNumber: firstNumber,
secondNumber: secondNumber,
operator: "+",
operationResult: firstNumber + secondNumber,
};
Wenn Sie Daten nach einer asynchronen Operation zurückgeben möchten, geben Sie ein Promise zurück. Die vom Promise zurückgegebenen Daten werden an den Client zurückgesendet. Beispielsweise können Sie bereinigten Text zurückgeben, den die 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
Damit der Client nützliche Fehlerdetails erhält, geben Sie Fehler von einer Funktion zurück, indem Sie eine Instanz von functions.https.HttpsError auslösen (oder ein Promise zurückgeben, das mit dieser Instanz abgelehnt wurde).
Der Fehler hat ein code Attribut, das einen der unter functions.https.HttpsError aufgeführten Werte haben kann.
Die Fehler haben auch eine String-message, die standardmäßig ein leerer String ist. Sie können auch ein optionales details-Feld mit einem beliebigen Wert haben. Wenn in Ihren Funktionen ein anderer Fehler als HttpsError ausgelöst wird, erhält der Client stattdessen einen Fehler mit der Meldung INTERNAL und dem Code internal.
Beispielsweise kann eine Funktion Datenvalidierungs- und Authentifizierungsfehler mit Fehlermeldungen auslösen, die an den aufrufenden Client zurückgegeben werden sollen:
// 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.");
}
Funktion bereitstellen
Nachdem Sie eine vollständige Funktion in index.js gespeichert haben, wird sie zusammen mit allen anderen Funktionen bereitgestellt, wenn Sie firebase deploy ausführen.
Wenn Sie nur die Funktion bereitstellen möchten, verwenden Sie das --only Argument, wie unten gezeigt, um
teilweise Bereitstellungen auszuführen:
firebase deploy --only functions:addMessage
Wenn beim Bereitstellen von Funktionen Berechtigungsfehler auftreten, prüfen Sie, ob dem Nutzer, der die Bereitstellungsbefehle ausführt, die entsprechenden IAM-Rollen zugewiesen sind.
Cliententwicklungsumgebung einrichten
Prüfen Sie, ob alle Voraussetzungen erfüllt sind, und fügen Sie Ihrer App die erforderlichen Abhängigkeiten und Clientbibliotheken hinzu.
iOS+
Folgen Sie der Anleitung unter Firebase zu meiner Apple-Anwendung hinzufügen.
Verwenden Sie Swift Package Manager, um Firebase-Abhängigkeiten zu installieren und zu verwalten.
- Öffnen Sie Ihr App-Projekt und gehen Sie in Xcode zu File > Add Packages (Datei > Pakete hinzufügen).
- Fügen Sie bei entsprechender Aufforderung das Firebase Apple Platforms SDK-Repository hinzu:
- Wählen Sie die Cloud Functions Bibliothek aus.
- Fügen Sie das Flag
-ObjCim Bereich Other Linker Flags (Weitere Verknüpfungsmerker) der Build-Einstellungen Ihres Ziels hinzu. - Wenn Sie fertig, beginnt Xcode automatisch, Ihre Abhängigkeiten im Hintergrund aufzulösen und herunterzuladen.
https://github.com/firebase/firebase-ios-sdk.git
Web
- Folgen Sie der Anleitung unter
Firebase zu meiner Webanwendung hinzufügen. Führen Sie dazu
den folgenden Befehl über das Terminal aus:
npm install firebase@12.11.0 --save
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
- Folgen Sie der Anleitung unter Firebase zu meiner Webanwendung hinzufügen.
- Fügen Sie Ihrer
App die Firebase Core- und Cloud Functions Clientbibliotheken hinzu:
<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.
- Führen Sie den folgenden Befehl über das Terminal aus:
npm install firebase@8.10.1 --save
- Fordern Sie Firebase Core und Cloud Functions manuell an:
const firebase = require("firebase"); // Required for side-effects require("firebase/functions");
Kotlin
Folgen Sie der Anleitung unter Firebase zu meiner Android-Anwendung hinzufügen.
Fügen Sie in der Gradle-Datei Ihres Moduls (auf Anwendungsebene) (in der Regel
<project>/<app-module>/build.gradle.ktsoder<project>/<app-module>/build.gradle) die Abhängigkeit für die Cloud Functions Bibliothek für Android hinzu. Wir empfehlen, die Firebase Android BoM zu verwenden, um die Bibliotheksversionierung zu steuern.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") }
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 die Firebase BoM nicht verwenden möchten, müssen Sie die Version jeder Firebase-Bibliothek in der entsprechenden Abhängigkeitszeile angeben.
Wenn Sie mehrere Firebase-Bibliotheken in Ihrer App verwenden, empfehlen wir dringend, die BoM zu verwenden, um die Bibliotheksversionen zu verwalten. So wird sichergestellt, dass alle Versionen kompatibel sind.
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
Folgen Sie der Anleitung unter Firebase zu meiner Android-Anwendung hinzufügen.
Fügen Sie in der Gradle-Datei Ihres Moduls (auf Anwendungsebene) (in der Regel
<project>/<app-module>/build.gradle.ktsoder<project>/<app-module>/build.gradle) die Abhängigkeit für die Cloud Functions Bibliothek für Android hinzu. Wir empfehlen, die Firebase Android BoM zu verwenden, um die Bibliotheksversionierung zu steuern.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") }
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 die Firebase BoM nicht verwenden möchten, müssen Sie die Version jeder Firebase-Bibliothek in der entsprechenden Abhängigkeitszeile angeben.
Wenn Sie mehrere Firebase-Bibliotheken in Ihrer App verwenden, empfehlen wir dringend, die BoM zu verwenden, um die Bibliotheksversionen zu verwalten. So wird sichergestellt, dass alle Versionen kompatibel sind.
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
Folgen Sie der Anleitung unter Firebase zu meiner Flutter-Anwendung hinzufügen.
Führen Sie im Stammverzeichnis Ihres Flutter-Projekts den folgenden Befehl aus, um das Plug-in zu installieren:
flutter pub add cloud_functionsErstellen Sie nach Abschluss der Installation Ihre Flutter-Anwendung neu:
flutter runNach der Installation können Sie auf das
cloud_functions-Plug-in zugreifen, indem Sie es in Ihrem Dart-Code importieren:import 'package:cloud_functions/cloud_functions.dart';
C++
Für C++ mit Android:
- Folgen Sie der Anleitung unter Firebase zu einem C++-Projekt hinzufügen.
- Fügen Sie die Bibliothek
firebase_functionsder DateiCMakeLists.txthinzu.
Für C++ mit Apple-Plattformen:
- Folgen Sie der Anleitung unter Firebase zu einem C++-Projekt hinzufügen.
- Fügen Sie das Cloud Functions-Pod der Datei
Podfilehinzu:pod 'Firebase/Functions'
- Speichern Sie die Datei und führen Sie den folgenden Befehl aus:
pod install
- Fügen Sie Ihrem Xcode-Projekt die Firebase Core- und Cloud Functions Frameworks aus dem
Firebase C++ SDK hinzu.
firebase.frameworkfirebase_functions.framework
Einheit
- Folgen Sie der Anleitung unter Firebase zu einem Unity-Projekt hinzufügen.
- Fügen Sie Ihrem Unity-Projekt
FirebaseFunctions.unitypackageaus dem Firebase Unity SDK hinzu.
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
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
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 einen Fehler, wenn der Server einen Fehler ausgelöst hat oder wenn das resultierende Promise abgelehnt wurde.
Wenn der von der Funktion zurückgegebene Fehler vom Typ function.https.HttpsError,
ist, erhält der Client den Fehler code, message, und details aus dem
Serverfehler. Andernfalls enthält der Fehler die Meldung INTERNAL und den Code INTERNAL. Weitere Informationen zum Umgang mit
Fehlern in Ihrer Funktion finden Sie hier.
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);
// ...
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;
}
});
Empfehlung: Missbrauch mit App Check verhindern
Bevor Sie Ihre App starten, sollten Sie App Check aktivieren, um sicherzustellen, dass nur Ihre Apps auf Ihre Endpunkte für Funktionen zugreifen können.