Mit den Client-SDKs von Cloud Functions for Firebase können Sie Funktionen direkt aus einer Firebase-App aufrufen. Um eine Funktion von Ihrer App auf diese Weise aufzurufen, schreiben und stellen Sie eine aufrufbare HTTPS-Funktion in Cloud Functions bereit und fügen Sie dann Clientlogik hinzu, um die Funktion von Ihrer App aufzurufen.
Beachten Sie, dass aufrufbare HTTPS-Funktionen ähnlich, aber nicht identisch mit HTTP-Funktionen sind. Um aufrufbare HTTPS-Funktionen zu verwenden, müssen Sie das Client-SDK für Ihre Plattform zusammen mit der functions.https
Back-End-API verwenden (oder das Protokoll implementieren). Callables unterscheiden sich grundlegend von HTTP-Funktionen:
- Bei Callables werden Firebase-Authentifizierungstoken, FCM-Token und App-Check-Token, sofern verfügbar, automatisch in Anfragen eingeschlossen.
- Der Auslöser
functions.https.onCall
deserialisiert automatisch den Anfragetext und validiert Authentifizierungstoken.
Das Firebase SDK for Cloud Functions v0.9.1 und höher arbeitet mit diesen Firebase Client SDK-Mindestversionen zusammen, um aufrufbare HTTPS-Funktionen zu unterstützen:
- Firebase SDK für Apple-Plattformen 10.6.0
- Firebase-SDK für Android 20.2.2
- Firebase-JavaScript-SDK 8.10.1
- Firebase Modular Web SDK Version 9.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
. Der Rest dieses Handbuchs enthält Anweisungen zum Schreiben, Bereitstellen und Aufrufen einer aufrufbaren HTTPS-Funktion für Apple-Plattformen, Android, Web, C++ und Unity.
Schreiben Sie die aufrufbare Funktion und stellen Sie sie bereit
Verwenden Sie functions.https.onCall
um eine aufrufbare HTTPS-Funktion zu erstellen. Diese Methode benötigt 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) => {
// ...
});
Für eine aufrufbare Funktion, die beispielsweise eine Textnachricht in der Echtzeitdatenbank speichert, könnten data
den Nachrichtentext enthalten, während context
Benutzerauthentifizierungsinformationen darstellen:
// 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;
Die Entfernung zwischen dem Standort der aufrufbaren Funktion und dem Standort des aufrufenden Clients kann zu einer Netzwerklatenz führen. Um die Leistung zu optimieren, sollten Sie ggf. den Speicherort der Funktion angeben und sicherstellen, dass der Speicherort des aufrufbaren Elements mit dem festgelegten Speicherort übereinstimmt, wenn Sie das SDK auf der Clientseite initialisieren .
Optional können Sie eine App Check-Bescheinigung anhängen, um Ihre Back-End-Ressourcen vor Missbrauch wie Abrechnungsbetrug oder Phishing zu schützen. Siehe Durchsetzung der App-Prüfung für Cloud Functions aktivieren .
Rücksendung des Ergebnisses
Um Daten an den Client zurückzusenden, geben Sie Daten zurück, die JSON-codiert werden können. Um beispielsweise das Ergebnis einer Additionsoperation zurückzugeben:
// returning result.
return {
firstNumber: firstNumber,
secondNumber: secondNumber,
operator: '+',
operationResult: firstNumber + secondNumber,
};
Um Daten nach einem asynchronen Vorgang zurückzugeben, geben Sie ein Promise zurück. Die vom Promise zurückgegebenen Daten werden an den Client zurückgesendet. Beispielsweise könnten Sie bereinigten Text zurückgeben, den die aufrufbare Funktion in die Echtzeitdatenbank geschrieben hat:
// 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 };
})
Fehler behandeln
Um sicherzustellen, dass der Client nützliche Fehlerdetails erhält, geben Sie Fehler von einem Callable zurück, indem Sie eine Instanz von functions.https.HttpsError
auslösen (oder ein Promise zurückgeben, das mit abgelehnt wurde). Der Fehler hat ein code
, das einer der unter functions.https.HttpsError
aufgelisteten Werte sein kann. Die Fehler haben auch eine Zeichenfolge message
, die standardmäßig eine leere Zeichenfolge ist. Sie können auch ein optionales details
mit einem beliebigen Wert haben. Wenn von Ihren Funktionen ein anderer Fehler als HttpsError
ausgegeben wird, erhält Ihr Client stattdessen einen Fehler mit der Nachricht INTERNAL
und dem Code internal
.
Beispielsweise könnte eine Funktion Datenvalidierungs- und Authentifizierungsfehler mit Fehlermeldungen auslösen, die an den aufrufenden Client zurückgegeben werden:
// 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.');
}
Stellen Sie die aufrufbare Funktion bereit
Nachdem Sie eine abgeschlossene aufrufbare Funktion in index.js
gespeichert haben, wird sie zusammen mit allen anderen Funktionen bereitgestellt, wenn Sie firebase deploy
ausführen. Um nur das aufrufbare bereitzustellen, verwenden Sie das Argument --only
wie gezeigt, um teilweise Bereitstellungen durchzuführen:
firebase deploy --only functions:addMessage
Wenn beim Bereitstellen von Funktionen Berechtigungsfehler auftreten, stellen Sie sicher, dass dem Benutzer, der die Bereitstellungsbefehle ausführt, die entsprechenden IAM-Rollen zugewiesen sind.
Richten Sie Ihre Client-Entwicklungsumgebung ein
Stellen Sie sicher, dass alle Voraussetzungen erfüllt sind, und fügen Sie Ihrer App dann die erforderlichen Abhängigkeiten und Clientbibliotheken hinzu.
iOS+
Befolgen Sie die Anweisungen zum Hinzufügen von Firebase zu Ihrer Apple-App .
Verwenden Sie Swift Package Manager, um Firebase-Abhängigkeiten zu installieren und zu verwalten.
- Navigieren Sie in Xcode bei geöffnetem App-Projekt zu File > Add Packages .
- Wenn Sie dazu aufgefordert werden, fügen Sie das Firebase Apple-Plattform-SDK-Repository hinzu:
- Wählen Sie die Cloud Functions-Bibliothek aus.
- Wenn Sie fertig sind, beginnt Xcode automatisch mit dem Auflösen und Herunterladen Ihrer Abhängigkeiten im Hintergrund.
https://github.com/firebase/firebase-ios-sdk
Web version 9
- Befolgen Sie die Anweisungen zum Hinzufügen von Firebase zu Ihrer Web-App . Stellen Sie sicher, dass Sie den folgenden Befehl von Ihrem Terminal aus ausführen:
npm install firebase@9.17.2 --save
Erfordern Sie sowohl Firebase Core als auch Cloud Functions manuell:
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 version 8
- Befolgen Sie die Anweisungen zum Hinzufügen von Firebase zu Ihrer Web-App .
- 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 von Ihrem Terminal aus:
npm install firebase@8.10.1 --save
- Erfordert manuell sowohl Firebase Core als auch Cloud Functions:
const firebase = require("firebase"); // Required for side-effects require("firebase/functions");
Kotlin+KTX
Befolgen Sie die Anweisungen zum Hinzufügen von Firebase zu Ihrer Android-App .
Fügen Sie in Ihrer Modul-Gradle-Datei (auf App-Ebene) (normalerweise
<project>/<app-module>/build.gradle
) die Abhängigkeit für die Cloud Functions-Android-Bibliothek hinzu. Wir empfehlen die Verwendung der Firebase Android BoM zur Steuerung der Bibliotheksversionierung.dependencies { // Import the BoM for the Firebase platform implementation platform('com.google.firebase:firebase-bom:31.2.3') // 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-ktx' }
Durch die Verwendung der Firebase Android BoM verwendet Ihre App immer kompatible Versionen von Firebase Android-Bibliotheken.
(Alternative) Fügen Sie Firebase-Bibliotheksabhängigkeiten hinzu , ohne die Stückliste zu verwenden
Wenn Sie die Firebase-Stückliste nicht verwenden möchten, müssen Sie jede Firebase-Bibliotheksversion in ihrer Abhängigkeitszeile angeben.
Beachten Sie, dass wir bei Verwendung mehrerer Firebase-Bibliotheken in Ihrer App dringend empfehlen, die BoM zum Verwalten von Bibliotheksversionen zu verwenden, wodurch sichergestellt wird, 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-ktx:20.2.2' }
Java
Befolgen Sie die Anweisungen zum Hinzufügen von Firebase zu Ihrer Android-App .
Fügen Sie in Ihrer Modul-Gradle-Datei (auf App-Ebene) (normalerweise
<project>/<app-module>/build.gradle
) die Abhängigkeit für die Cloud Functions-Android-Bibliothek hinzu. Wir empfehlen die Verwendung der Firebase Android BoM zur Steuerung der Bibliotheksversionierung.dependencies { // Import the BoM for the Firebase platform implementation platform('com.google.firebase:firebase-bom:31.2.3') // 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' }
Durch die Verwendung der Firebase Android BoM verwendet Ihre App immer kompatible Versionen von Firebase Android-Bibliotheken.
(Alternative) Fügen Sie Firebase-Bibliotheksabhängigkeiten hinzu , ohne die Stückliste zu verwenden
Wenn Sie die Firebase-Stückliste nicht verwenden möchten, müssen Sie jede Firebase-Bibliotheksversion in ihrer Abhängigkeitszeile angeben.
Beachten Sie, dass wir bei Verwendung mehrerer Firebase-Bibliotheken in Ihrer App dringend empfehlen, die BoM zum Verwalten von Bibliotheksversionen zu verwenden, wodurch sichergestellt wird, 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:20.2.2' }
Dart
Befolgen Sie die Anweisungen zum Hinzufügen von Firebase zu Ihrer Flutter-App .
Führen Sie im Stammverzeichnis Ihres Flutter-Projekts den folgenden Befehl aus, um das Plugin zu installieren:
flutter pub add cloud_functions
Wenn Sie fertig sind, erstellen Sie Ihre Flutter-Anwendung neu:
flutter run
Nach der Installation können Sie auf das
cloud_functions
-Plugin zugreifen, indem Sie es in Ihren Dart-Code importieren:import 'package:cloud_functions/cloud_functions.dart';
C++
Für C++ mit Android :
- Befolgen Sie die Anweisungen zum Hinzufügen von Firebase zu Ihrem C++-Projekt .
- Fügen Sie Ihrer
CMakeLists.txt
Datei diefirebase_functions
Bibliothek hinzu.
Für C++ mit Apple-Plattformen :
- Befolgen Sie die Anweisungen zum Hinzufügen von Firebase zu Ihrem C++-Projekt .
- Fügen Sie den Cloud Functions-Pod Ihrer
Podfile
hinzu:pod 'Firebase/Functions'
- Speichern Sie die Datei und führen Sie dann Folgendes aus:
pod install
- Fügen Sie Ihrem Xcode-Projekt den Firebase Core und die Cloud Functions-Frameworks aus dem Firebase C++ SDK hinzu.
-
firebase.framework
-
firebase_functions.framework
-
Einheit
- Befolgen Sie die Anweisungen zum Hinzufügen von Firebase zu Ihrem Unity-Projekt .
- Fügen Sie das
FirebaseFunctions.unitypackage
aus dem Firebase Unity SDK zu Ihrem Unity-Projekt hinzu.
Initialisieren Sie das Client-SDK
Initialisieren Sie eine Instanz von Cloud Functions:
Schnell
lazy var functions = Functions.functions()
Ziel c
@property(strong, nonatomic) FIRFunctions *functions;
// ...
self.functions = [FIRFunctions functions];
Web version 8
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 version 9
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;
Rufen Sie die Funktion auf
Schnell
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
}
}
Ziel 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 version 8
var addMessage = firebase.functions().httpsCallable('addMessage');
addMessage({ text: messageText })
.then((result) => {
// Read result of the Cloud Function.
var sanitizedMessage = result.data.text;
});
Web version 9
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;
});
}
Behandeln Sie Fehler auf dem Client
Der Client erhält einen Fehler, wenn der Server einen Fehler ausgegeben hat oder wenn das resultierende Promise zurückgewiesen wurde.
Wenn der von der Funktion zurückgegebene Fehler vom Typ function.https.HttpsError
ist, erhält der Client den code
, message
und details
vom Serverfehler. Andernfalls enthält der Fehler die Meldung INTERNAL
und den Code INTERNAL
. Sehen Sie sich die Anleitung zum Umgang mit Fehlern in Ihrer aufrufbaren Funktion an.
Schnell
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]
}
// ...
}
Ziel c
if (error) {
if ([error.domain isEqual:@"com.firebase.functions"]) {
FIRFunctionsErrorCode code = error.code;
NSString *message = error.localizedDescription;
NSObject *details = error.userInfo[@"details"];
}
// ...
}
Web version 8
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 version 9
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;
}
});
Empfehlung: Missbrauch verhindern mit App Check
Bevor Sie Ihre App starten, sollten Sie App Check aktivieren, um sicherzustellen, dass nur Ihre Apps auf Ihre Endpunkte für aufrufbare Funktionen zugreifen können.