Catch up on everything we announced at this year's Firebase Summit. Learn more

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 eine Funktion auf diese Weise aus Ihrer App aufzurufen, schreiben Sie eine HTTPS Callable-Funktion, stellen Sie sie in Cloud Functions bereit und fügen Sie dann Clientlogik hinzu, um die Funktion aus Ihrer App aufzurufen.

Es ist wichtig , im Auge zu behalten , dass HTTPS aufrufbaren Funktionen sind ähnlich , aber nicht identisch mit HTTP - Funktionen. So verwenden HTTPS aufrufbaren Funktionen müssen Sie den Client SDK für Ihre Plattform verwenden zusammen mit den functions.https Backend - API (oder das Protokoll implementieren). Callables haben diese wesentlichen Unterschiede zu HTTP-Funktionen:

  • Bei Callables werden Firebase Authentication Tokens, FCM Tokens und App Check Tokens, sofern verfügbar, automatisch in Anfragen eingeschlossen.
  • Die functions.https.onCall Trigger deserialisiert die Anforderung automatisch Körper und validiert AUTH Token.

Das Firebase SDK for Cloud Functions v0.9.1 und höher arbeitet mit diesen Mindestversionen des Firebase-Client-SDK zusammen, um aufrufbare HTTPS-Funktionen zu unterstützen:

  • Firebase SDK für Apple-Plattformen 8.10.0
  • Firebase-SDK für Android 20.0.1
  • Firebase JavaScript-SDK 8.10.0
  • Firebase Modular Web SDK v. 9.0

Wenn Sie eine ähnliche Funktionalität wie eine App auf einer nicht unterstützten Plattform hinzufügen möchten, finden Sie in der Protokoll - Spezifikation 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 und implementieren Sie die aufrufbare Funktion

Verwenden functions.https.onCall eine HTTPS - aufrufbare Funktion zu erstellen. Diese Methode hat 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 eine Textnachricht an die Echtzeit - Datenbank speichert zum Beispiel data könnten den Nachrichtentext enthalten, während context Parameter Benutzer - Auth Informationen 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 Netzwerklatenz erzeugen. Zur Optimierung der Leistung, sollten Sie die Angabe der Funktion Ort , wo anwendbar, und stellen Sie sicher , dass die abrufbaren Standort mit dem Standortsatz auszurichten , wenn Sie das SDK initialisieren auf der Client - Seite.

Optional können Sie eine App-Check-Bestätigung anhängen, um Ihre Back-End-Ressourcen vor Missbrauch wie Abrechnungsbetrug oder Phishing zu schützen. Siehe Aktivieren App Überprüfen Durchsetzung für Cloud - Funktionen .

Ergebnis zurücksenden

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. Sie können beispielsweise 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 bekommt, Rückgabe Fehler von einem aufrufbar durch das Werfen (oder Rückkehr ein Versprechen abgelehnt mit) eine Instanz von functions.https.HttpsError . Der Fehler hat ein code - Attribut, das einer des Wertes bei aufgelistet werden kann functions.https.HttpsError . Die Fehler haben auch eine String - message , die standardmäßig auf eine leere Zeichenfolge. Sie können auch ein optionales haben details Feld mit einem beliebigen Wert. Wenn ein anderer Fehler als HttpsError von Ihren Funktionen geworfen wird, Ihr Kunde erhält stattdessen einen Fehler mit der Meldung INTERNAL und dem Code internal .

Zum Beispiel 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 innerhalb speichern index.js wird zusammen mit allen anderen Funktionen eingesetzt , wenn Sie laufen firebase deploy . Um nur das aufrufbare bereitstellen, verwenden , um das --only Argument wie gezeigt auszuführen Teil entfaltet :

$ firebase deploy --only functions:addMessage

Wenn Sie die Berechtigungen Fehler auftreten , wenn Funktionen bereitstellen, stellen Sie sicher , dass die entsprechenden IAM Rollen dem Benutzer zugeordnet sind , laufen die Bereitstellungsbefehle.

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+

Folgen Sie den Anweisungen auf Firebase zu Ihrem Apple App hinzufügen .

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

  1. In Xcode, mit Ihrem App - Projekt zu öffnen, navigieren Sie zu Datei> Swift Packages> Paket hinzufügen Abhängigkeit.
  2. Wenn Sie dazu aufgefordert werden, fügen Sie das SDK-Repository der Firebase Apple Platforms hinzu:
  3.   https://github.com/firebase/firebase-ios-sdk
      
  4. Wählen Sie die Cloud Functions-Bibliothek aus.
  5. Wenn Sie fertig sind, beginnt Xcode automatisch, Ihre Abhängigkeiten im Hintergrund aufzulösen und herunterzuladen.

Webversion 9

  1. Folgen Sie den Anweisungen auf Firebase zu Ihrem Web - App hinzufügen . Stellen Sie sicher , den folgenden Befehl von Ihrem Terminal auszuführen:
    npm install firebase@9.6.0 --save
    
  2. Benötigen 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);
    

Webversion 8

  1. Folgen Sie den Anweisungen auf Firebase zu Ihrem Web - App hinzufügen .
  2. Fügen Sie die Firebase Kern und Cloud - Funktionen Client - Bibliotheken , um Ihre Anwendung:
    <script src="https://www.gstatic.com/firebasejs/8.10.0/firebase.js"></script>
    <script src="https://www.gstatic.com/firebasejs/8.10.0/firebase-functions.js"></script>
    

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

  1. Führen Sie den folgenden Befehl von Ihrem Terminal:
    npm install firebase@8.10.0 --save
    
  2. Firebase erfordert manuell sowohl Kern und Cloud - Funktionen:
    const firebase = require("firebase");
    // Required for side-effects
    require("firebase/functions");
    

Java

  1. Folgen Sie den Anweisungen auf Firebase zu Ihrer Android - App hinzufügen .

  2. Mit Hilfe der Firebase Android BoM , erklärt die Abhängigkeit für die Cloud - Funktionen Android - Bibliothek in Ihrem Modul (app-Ebene) Gradle Datei ( in der Regel app/build.gradle ).

    dependencies {
        // Import the BoM for the Firebase platform
        implementation platform('com.google.firebase:firebase-bom:29.0.1')
    
        // Declare 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 des Firebase Android BoM werden, Ihre App immer kompatible Versionen der Firebase Android - Bibliotheken verwenden.

    (Alternative) Deklarieren Firebase Bibliothek Abhängigkeiten , ohne die BoM mit

    Wenn Sie die Firebase-Stückliste nicht verwenden möchten, müssen Sie jede Firebase-Bibliotheksversion in ihrer Abhängigkeitszeile angeben.

    Beachten Sie, dass , wenn Sie mehrere Firebase Bibliotheken in Ihrer Anwendung verwenden wir mit der BoM empfehlen Bibliothek Versionen zu verwalten, die sicherstellt , dass alle Versionen kompatibel sind.

    dependencies {
        // Declare 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.0.1'
    }
    

Kotlin+KTX

  1. Folgen Sie den Anweisungen auf Firebase zu Ihrer Android - App hinzufügen .

  2. Mit Hilfe der Firebase Android BoM , erklärt die Abhängigkeit für die Cloud - Funktionen Android - Bibliothek in Ihrem Modul (app-Ebene) Gradle Datei ( in der Regel app/build.gradle ).

    dependencies {
        // Import the BoM for the Firebase platform
        implementation platform('com.google.firebase:firebase-bom:29.0.1')
    
        // Declare 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 des Firebase Android BoM werden, Ihre App immer kompatible Versionen der Firebase Android - Bibliotheken verwenden.

    (Alternative) Deklarieren Firebase Bibliothek Abhängigkeiten , ohne die BoM mit

    Wenn Sie die Firebase-Stückliste nicht verwenden möchten, müssen Sie jede Firebase-Bibliotheksversion in ihrer Abhängigkeitszeile angeben.

    Beachten Sie, dass , wenn Sie mehrere Firebase Bibliotheken in Ihrer Anwendung verwenden wir mit der BoM empfehlen Bibliothek Versionen zu verwalten, die sicherstellt , dass alle Versionen kompatibel sind.

    dependencies {
        // Declare 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.0.1'
    }
    

C++

Für C ++ mit Android:

  1. Folgen Sie den Anweisungen auf Firebase zu Ihrem C ++ Projekt hinzufügen .
  2. Fügen Sie die firebase_functions Bibliothek zu Ihrer CMakeLists.txt Datei.

Für C ++ mit Apple - Plattformen:

  1. Folgen Sie den Anweisungen auf Firebase zu Ihrem C ++ Projekt hinzufügen .
  2. Fügen Sie die Cloud - Funktionen Pod mit der Podfile :
    pod 'Firebase/Functions'
  3. Speichern Sie die Datei, dann führen:
    pod install
  4. Fügen Sie die Firebase Kern und Cloud - Funktionen Frameworks von der Firebase C ++ SDK zu Ihrem Xcode - Projekt.
    • firebase.framework
    • firebase_functions.framework

Einheit

  1. Folgen Sie den Anweisungen auf Firebase zu Ihrem Unity - Projekt hinzufügen .
  2. Fügen Sie die FirebaseFunctions.unitypackage von der Firebase Unity SDK zu Ihrem Unity - Projekt.

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

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

Webversion 9

const app = initializeApp({
  projectId: '### CLOUD FUNCTIONS PROJECT ID ###',
  apiKey: '### FIREBASE API KEY ###',
  authDomain: '### FIREBASE AUTH DOMAIN ###',
});
const functions = getFunctions(app);

Java

private FirebaseFunctions mFunctions;
// ...
mFunctions = FirebaseFunctions.getInstance();

Kotlin+KTX

private lateinit var functions: FirebaseFunctions
// ...
functions = Firebase.functions

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 == FIRFunctionsErrorDomain) {
      FIRFunctionsErrorCode code = error.code;
      NSString *message = error.localizedDescription;
      NSObject *details = error.userInfo[FIRFunctionsErrorDetailsKey];
    }
    // ...
  }
  self->_resultField.text = result.data[@"text"];
}];

Webversion 8

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

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

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

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

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 ausgibt oder das resultierende Promise abgelehnt wurde.

Wenn der Fehler von der Funktion zurück vom Typ function.https.HttpsError , dann erhält der Kunde den Fehler - code , message und details aus den Server - Fehlern. Ansonsten enthält der Fehler die Meldung INTERNAL und den Code INTERNAL . Siehe Anleitung für , wie man Fehler behandelt in Ihrer aufrufbare Funktion.

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 == FIRFunctionsErrorDomain) {
    FIRFunctionsErrorCode code = error.code;
    NSString *message = error.localizedDescription;
    NSObject *details = error.userInfo[FIRFunctionsErrorDetailsKey];
  }
  // ...
}

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

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

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

                    // ...
                }

                // ...
            }
        });

Kotlin+KTX

addMessage(inputMessage)
        .addOnCompleteListener(OnCompleteListener { task ->
            if (!task.isSuccessful) {
                val e = task.exception
                if (e is FirebaseFunctionsException) {
                    val code = e.code
                    val details = e.details
                }

                // ...
            }

            // ...
        })

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 ermöglichen App überprüfen , um sicherzustellen , dass nur Ihre Anwendungen Ihre aufrufbare Funktion Endpunkte zugreifen können.