Rufen Sie Funktionen aus Ihrer App auf


Mit den Cloud Functions for Firebase-Client-SDKs können Sie Funktionen direkt aus einer Firebase-App aufrufen. Um auf diese Weise eine Funktion aus Ihrer App aufzurufen, schreiben und stellen Sie eine über HTTP aufrufbare Funktion in Cloud Functions bereit und fügen Sie dann Clientlogik hinzu, um die Funktion aus Ihrer App aufzurufen.

Es ist wichtig zu bedenken, dass aufrufbare HTTP-Funktionen HTTP-Funktionen ähneln, aber nicht mit ihnen identisch sind. Um über HTTP aufrufbare Funktionen verwenden zu können, müssen Sie das Client-SDK für Ihre Plattform zusammen mit der Backend-API verwenden (oder das Protokoll implementieren). Callables weisen folgende wesentliche Unterschiede zu HTTP-Funktionen auf:

  • Bei Callables werden Firebase-Authentifizierungs-Tokens, FCM-Tokens und App-Check-Tokens, sofern verfügbar, automatisch in Anfragen einbezogen.
  • Der Trigger deserialisiert automatisch den Anforderungstext und validiert Authentifizierungstoken.

Das Firebase SDK für Cloud Functions der 2. Generation und höher interagiert mit diesen Firebase-Client-SDK-Mindestversionen, um aufrufbare HTTPS-Funktionen zu unterstützen:

  • Firebase SDK für Apple-Plattformen 10.19.0
  • Firebase SDK für Android 20.4.0
  • Firebase Modular Web SDK v. 9.7.0

Wenn Sie einer App, die auf einer nicht unterstützten Plattform erstellt wurde, ähnliche Funktionen hinzufügen möchten, sehen Sie sich die Protokollspezifikation für https.onCall an. Der Rest dieses Handbuchs enthält Anweisungen zum Schreiben, Bereitstellen und Aufrufen einer aufrufbaren HTTP-Funktion für Apple-Plattformen, Android, Web, C++ und Unity.

Schreiben Sie die aufrufbare Funktion und stellen Sie sie bereit

Die Codebeispiele in diesem Abschnitt basieren auf einem vollständigen Schnellstartbeispiel, das zeigt, wie Sie mithilfe eines der Client-SDKs Anforderungen an eine serverseitige Funktion senden und eine Antwort erhalten. Importieren Sie zunächst die erforderlichen Module:

Node.js

// Dependencies for callable functions.
const {onCall, HttpsError} = require("firebase-functions/v2/https");
const {logger} = require("firebase-functions/v2");

// Dependencies for the addMessage function.
const {getDatabase} = require("firebase-admin/database");
const sanitizer = require("./sanitizer");

Python

# Dependencies for callable functions.
from firebase_functions import https_fn, options

# Dependencies for writing to Realtime Database.
from firebase_admin import db, initialize_app

Verwenden Sie den Anforderungshandler für Ihre Plattform ( functions.https.onCall ) oder on_call ), um eine über HTTPS aufrufbare Funktion zu erstellen. Diese Methode benötigt einen Anforderungsparameter:

Node.js

// Saves a message to the Firebase Realtime Database but sanitizes the
// text by removing swearwords.
exports.addmessage = onCall((request) => {
  // ...
});

Python

@https_fn.on_call()
def addmessage(req: https_fn.CallableRequest) -> Any:
    """Saves a message to the Firebase Realtime Database but sanitizes the text
    by removing swear words."""

Der request enthält von der Client-App übergebene Daten sowie zusätzlichen Kontext wie den Authentifizierungsstatus. Für eine aufrufbare Funktion, die beispielsweise eine Textnachricht in der Echtzeitdatenbank speichert, könnten data den Nachrichtentext zusammen mit Authentifizierungsinformationen in auth enthalten:

Node.js

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

Python

# Message text passed from the client.
text = req.data["text"]
# Authentication / user information is automatically added to the request.
uid = req.auth.uid
name = req.auth.token.get("name", "")
picture = req.auth.token.get("picture", "")
email = req.auth.token.get("email", "")

Die Entfernung zwischen dem Standort der aufrufbaren Funktion und dem Standort des aufrufenden Clients kann zu Netzwerklatenz führen. Um die Leistung zu optimieren, sollten Sie ggf. den Standort der Funktion angeben und sicherstellen, dass der Standort des Callables mit dem festgelegten Standort übereinstimmt, wenn Sie das SDK auf der Clientseite initialisieren .

Optional können Sie eine App Check-Bescheinigung anhängen, um Ihre Backend-Ressourcen vor Missbrauch wie Abrechnungsbetrug oder Phishing zu schützen. Siehe Aktivieren der App Check-Erzwingung für Cloud Functions .

Senden Sie das Ergebnis zurück

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:

Node.js

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

Python

return {
    "firstNumber": first_number,
    "secondNumber": second_number,
    "operator": "+",
    "operationResult": first_number + second_number
}

Der bereinigte Text aus dem Nachrichtentextbeispiel wird sowohl an den Client als auch an die Echtzeitdatenbank zurückgegeben. In Node.js kann dies asynchron mithilfe eines JavaScript-Versprechens erfolgen:

Node.js

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

Python

# Saving the new message to the Realtime Database.
sanitized_message = sanitize_text(text)  # Sanitize message.
db.reference("/messages").push({  # type: ignore
    "text": sanitized_message,
    "author": {
        "uid": uid,
        "name": name,
        "picture": picture,
        "email": email
    }
})
print("New message written")

# Returning the sanitized message to the client.
return {"text": sanitized_message}

Konfigurieren Sie CORS (Cross-Origin Resource Sharing)

Verwenden Sie die Option cors , um zu steuern, welche Ursprünge auf Ihre Funktion zugreifen können.

Standardmäßig ist CORS für aufrufbare Funktionen so konfiguriert, dass Anfragen von allen Ursprüngen zugelassen werden. Um einige, aber nicht alle Cross-Origin-Anfragen zuzulassen, übergeben Sie eine Liste spezifischer Domänen oder regulärer Ausdrücke, die zugelassen werden sollen. Zum Beispiel:

Node.js

const { onCall } = require("firebase-functions/v2/https");

exports.getGreeting = onCall(
  { cors: [/firebase\.com$/, "flutter.com"] },
  (request) => {
    return "Hello, world!";
  }
);

Um ursprungsübergreifende Anfragen zu verbieten, setzen Sie die cors Richtlinie auf false .

Behandeln Sie Fehler

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 “ oder https_fn.HttpsError “ auslösen (oder für Node.js ein mit abgelehntes Promise zurückgeben). Der Fehler hat ein code , das einer der in gRPC- Statuscodes aufgeführten 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 Ihre Funktionen einen anderen Fehler als einen HTTPS-Fehler auslösen, erhält Ihr Client stattdessen einen Fehler mit der Meldung 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:

Node.js

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

Python

# Checking attribute.
if not isinstance(text, str) or len(text) < 1:
    # Throwing an HttpsError so that the client gets the error details.
    raise https_fn.HttpsError(code=https_fn.FunctionsErrorCode.INVALID_ARGUMENT,
                              message=('The function must be called with one argument, "text",'
                                       " containing the message text to add."))

# Checking that the user is authenticated.
if req.auth is None:
    # Throwing an HttpsError so that the client gets the error details.
    raise https_fn.HttpsError(code=https_fn.FunctionsErrorCode.FAILED_PRECONDITION,
                              message="The function must be called while authenticated.")

Stellen Sie die aufrufbare Funktion bereit

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. Um nur das Callable bereitzustellen, verwenden Sie das Argument --only wie gezeigt, um Teilbereitstellungen 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 Sie alle Voraussetzungen erfüllen, und fügen Sie dann die erforderlichen Abhängigkeiten und Clientbibliotheken zu Ihrer App hinzu.

iOS+

Befolgen Sie die Anweisungen, um Firebase zu Ihrer Apple-App hinzuzufügen .

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

  1. Navigieren Sie in Xcode bei geöffnetem App-Projekt zu File > Add Packages .
  2. Wenn Sie dazu aufgefordert werden, fügen Sie das Firebase Apple Platforms SDK-Repository hinzu:
  3.   https://github.com/firebase/firebase-ios-sdk.git
  4. Wählen Sie die Cloud Functions-Bibliothek aus.
  5. Fügen Sie das Flag -ObjC zum Abschnitt „Andere Linker-Flags“ der Build-Einstellungen Ihres Ziels hinzu.
  6. Wenn Sie fertig sind, beginnt Xcode automatisch mit der Auflösung und dem Herunterladen Ihrer Abhängigkeiten im Hintergrund.

Modulare Web-API

  1. Befolgen Sie die Anweisungen, um Firebase zu Ihrer Web-App hinzuzufügen . Stellen Sie sicher, dass Sie den folgenden Befehl von Ihrem Terminal aus ausführen:
    npm install firebase@10.7.1 --save
    
  2. Erfordern Sie manuell sowohl den Firebase-Kern als auch die Cloud-Funktionen:

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

Android

  1. Befolgen Sie die Anweisungen, um Firebase zu Ihrer Android-App hinzuzufügen .

  2. Fügen Sie in Ihrer Modul-Gradle-Datei (auf App-Ebene) (normalerweise <project>/<app-module>/build.gradle.kts oder <project>/<app-module>/build.gradle ) die Abhängigkeit für die Cloud Functions hinzu Bibliothek für Android. 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: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")
    }
    

    Durch die Verwendung der Firebase Android BoM verwendet Ihre App immer kompatible Versionen der 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: Wenn Sie mehrere Firebase-Bibliotheken in Ihrer App verwenden, empfehlen wir dringend, die BoM zum Verwalten der Bibliotheksversionen zu verwenden, um sicherzustellen, 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.4.0")
    }
    
    Suchen Sie nach einem Kotlin-spezifischen Bibliotheksmodul? Ab Oktober 2023 (Firebase BoM 32.5.0) können sich sowohl Kotlin- als auch Java-Entwickler auf das Hauptbibliotheksmodul verlassen (Einzelheiten finden Sie in den FAQ zu dieser Initiative ).

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

Modulare Web-API

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

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

var addMessage = firebase.functions().httpsCallable('addMessage');
addMessage({ text: messageText })
  .then((result) => {
    // Read result of the Cloud Function.
    var sanitizedMessage = result.data.text;
  });

Modulare Web-API

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 eine Fehlermeldung, wenn der Server einen Fehler ausgegeben hat oder wenn das resultierende Versprechen abgelehnt wurde.

Wenn der von der Funktion zurückgegebene Fehler vom Typ function.https.HttpsError ist, erhält der Client den code , die 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-Namespace-API

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

Modulare Web-API

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 starten, sollten Sie App Check aktivieren, um sicherzustellen, dass nur Ihre Apps auf Ihre aufrufbaren Funktionsendpunkte zugreifen können.