Mit den Cloud Functions for Firebase-Client-SDKs können Sie Funktionen direkt über eine Firebase-App aufrufen. Wenn Sie eine Funktion auf diese Weise über Ihre App aufrufen möchten, schreiben und stellen Sie eine HTTP-aufrufbare Funktion in Cloud Functions bereit und fügen Sie dann Clientlogik hinzu, um die Funktion über Ihre App aufzurufen.
HTTP-aufrufbare Funktionen ähneln HTTP-Funktionen, sind aber nicht identisch mit ihnen. Wenn Sie HTTP-aufrufbare Funktionen verwenden möchten, müssen Sie das Client-SDK für Ihre Plattform zusammen mit der Backend-API verwenden (oder das Protokoll implementieren). Aufrufbare Funktionen unterscheiden sich von HTTP-Funktionen durch folgende Hauptmerkmale:
- Bei Aufrufbaren werden Firebase Authentication-, FCM- und App Check-Tokens, sofern verfügbar, automatisch in Anfragen eingeschlossen.
- 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-Plattformen 11.2.0
- Firebase SDK für Android 21.0.0
- Firebase Modular Web SDK Version 9.7.0
Wenn Sie einer App, die auf einer nicht unterstützten Plattform erstellt wurde, ähnliche Funktionen hinzufügen möchten, lesen Sie die Protokollspezifikation für https.onCall
. Im restlichen Teil dieses Leitfadens erfahren Sie, wie Sie eine HTTP-aufrufbare Funktion für Apple-Plattformen, Android, Web, C++ und Unity schreiben, bereitstellen und aufrufen.
Aufrufbare Funktion schreiben und bereitstellen
Verwenden Sie functions.https.onCall
, um eine HTTPS-aufrufbare 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) => { // ... });
Für eine aufrufbare Funktion, die eine Textnachricht im Realtime Database speichert,
Beispielsweise könnte data
den Nachrichtentext enthalten, während context
-Parameter stehen für Informationen zur Nutzerauthentifizierung:
// 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 Ihre Backend-Ressourcen vor Missbrauch wie Abrechnungsbetrug oder Phishing zu schützen. Weitere Informationen finden Sie unter Erzwingung von App Check für Cloud Functions aktivieren.
Ergebnis zurücksenden
Wenn du Daten an den Client zurücksenden möchtest, musst du Daten zurückgeben, die JSON-codiert werden können. Für Beispiel, um das Ergebnis eines Additionsvorgangs zurückzugeben:
// returning result.
return {
firstNumber: firstNumber,
secondNumber: secondNumber,
operator: "+",
operationResult: firstNumber + secondNumber,
};
Wenn Sie Daten nach einem asynchronen Vorgang zurückgeben möchten, geben Sie ein Promise zurück. Die vom Promise zurückgegebenen Daten werden an den Client zurückgesendet. Sie können beispielsweise gefilterten 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 weist ein code
-Attribut auf, 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 die aufrufbare Funktion bereitstellen möchten, verwenden Sie das Argument --only
, um teilweise Bereitstellungen durchzuführen:
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-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
-ObjC
dem Abschnitt Other Linker Flags (Weitere Verknüpfungsmerker) in den Build-Einstellungen des 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, um
Fügen Sie Firebase zu Ihrer Web-App hinzu. Führen Sie auf jeden Fall
den folgenden Befehl über Ihr Terminal:
npm install firebase@10.13.2 --save
Fordere sowohl Firebase Core als auch 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, um Fügen Sie Firebase zu Ihrer Web-App hinzu.
- 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 im Terminal den folgenden Befehl 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+KTX
Folgen Sie der Anleitung unter Firebase zu meiner Android-Anwendung hinzufügen.
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.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") }
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 mehrere Firebase-Bibliotheken in Ihrer App verwenden, empfehlen wir Ihnen dringend, die Bibliotheksversionen mithilfe der BoM 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:21.0.0") }
Java
Folgen Sie der Anleitung unter Firebase zu meiner Android-Anwendung hinzufügen.
Fügen Sie in der Gradle-Datei des Moduls (auf Anwendungsebene) (in der Regel
<project>/<app-module>/build.gradle.kts
oder<project>/<app-module>/build.gradle
) 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.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") }
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") }
Dart
Folgen Sie der Anleitung unter Firebase zu Ihrer Flutter-App hinzufügen.
Führen Sie im Stammverzeichnis Ihres Flutter-Projekts den folgenden Befehl aus, Installieren Sie das Plug-in:
flutter pub add cloud_functions
Erstellen Sie anschließend Ihre Flutter-Anwendung neu:
flutter run
Nach der Installation hast du Zugriff auf die
cloud_functions
indem Sie es in Ihren Dart-Code importieren:import 'package:cloud_functions/cloud_functions.dart';
C++
Für C++ mit Android:
- Folgen Sie der Anleitung, um Fügen Sie Firebase zu Ihrem C++-Projekt hinzu.
- Fügen Sie der
CMakeLists.txt
-Datei die Bibliothekfirebase_functions
hinzu.
Für C++ mit Apple-Plattformen:
- Folgen Sie der Anleitung unter Firebase zu einem C++-Projekt hinzufügen.
- Fügen Sie dem
Podfile
den Cloud Functions-Pod hinzu:pod 'Firebase/Functions'
- Speichern Sie die Datei und führen Sie 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.framework
firebase_functions.framework
Einheit
- Folgen Sie der Anleitung, um Fügen Sie Firebase zu Ihrem Unity-Projekt hinzu.
- Fügen Sie
FirebaseFunctions.unitypackage
aus dem Firebase Unity SDK hinzu: 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
vom 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;
}
});
Empfohlen: Missbrauch mit App Check verhindern
Bevor Sie Ihre App veröffentlichen, sollten Sie App Check aktivieren, damit nur Ihre Apps auf Ihre Endpunkte für aufrufbare Funktionen zugreifen können.