Chiama le funzioni dalla tua app

Gli SDK client Cloud Functions for Firebase ti consentono di chiamare le funzioni direttamente da un'app Firebase. Per chiamare una funzione dalla tua app in questo modo, scrivi e distribuisci una funzione richiamabile HTTPS in Cloud Functions, quindi aggiungi la logica client per chiamare la funzione dalla tua app.

E 'importante tenere a mente che HTTPS funzioni richiamabili sono funzioni simili, ma non identici a HTTP. Per utilizzare HTTPS funzioni richiamabili è necessario utilizzare l'SDK client per la piattaforma insieme ai functions.https backend API (o implementare il protocollo). I callable hanno queste differenze chiave dalle funzioni HTTP:

  • Con i callable, i token di autenticazione Firebase, i token FCM e i token App Check, quando disponibili, vengono inclusi automaticamente nelle richieste.
  • Il functions.https.onCall grilletto deserializza automaticamente il corpo della richiesta e convalida auth token.

L'SDK Firebase per Cloud Functions v0.9.1 e versioni successive interagisce con queste versioni minime dell'SDK client Firebase per supportare le funzioni HTTPS Callable:

  • SDK Firebase per iOS 8.4.0
  • Firebase SDK per Android 20.0.0
  • Firebase JavaScript SDK 8.8.0
  • Firebase Modular Web SDK v. 9.0

Se si desidera aggiungere una funzionalità simile a un app costruito su una piattaforma non supportata, vedere la specifica di protocollo per https.onCall . Il resto di questa guida fornisce istruzioni su come scrivere, distribuire e chiamare una funzione richiamabile HTTPS per iOS, Android, Web, C++ e Unity.

Scrivi e distribuisci la funzione richiamabile

Utilizzare functions.https.onCall per creare una funzione di HTTPS callable. Questo metodo richiede due parametri: data , e facoltativi context :

// Saves a message to the Firebase Realtime Database but sanitizes the text by removing swearwords.
exports.addMessage = functions.https.onCall((data, context) => {
  // ...
});
index.js

Per una funzione richiamabile che salva un messaggio di testo al database in tempo reale, ad esempio, data potrebbero contenere il testo del messaggio, mentre context parametri rappresentano le informazioni di autenticazione dell'utente:

// 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;
index.js

La distanza tra la posizione della funzione richiamabile e la posizione del client chiamante può creare latenza di rete. Per ottimizzare le prestazioni, si consideri che specifica la posizione funzione , se del caso, e assicurarsi di allineare la posizione del richiamabile con il set posizione quando si inizializza l'SDK sul lato client.

Facoltativamente, puoi allegare un'attestazione di App Check per proteggere le tue risorse di backend da abusi, come frodi di fatturazione o phishing. Vedere Abilita App Verificare l'applicazione per le funzioni cloud .

Restituire il risultato

Per inviare i dati al client, restituire i dati che possono essere codificati JSON. Ad esempio, per restituire il risultato di un'operazione di addizione:

// returning result.
return {
  firstNumber: firstNumber,
  secondNumber: secondNumber,
  operator: '+',
  operationResult: firstNumber + secondNumber,
};
index.js

Per restituire dati dopo un'operazione asincrona, restituire una promessa. I dati restituiti dalla promessa vengono rispediti al cliente. Ad esempio, potresti restituire il testo sterilizzato che la funzione richiamabile ha scritto nel database in tempo reale:

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

Gestire gli errori

Per garantire il cliente ottiene i dettagli errore utili, gli errori di ritorno da un richiamabile lanciando (o di ritorno una promessa respinto con) un'istanza di functions.https.HttpsError . L'errore ha un code attributo che può essere uno dei valori elencati functions.https.HttpsError . Gli errori hanno anche una stringa di message , che per impostazione predefinita una stringa vuota. Essi possono anche avere un optional details campo con un valore arbitrario. Se un altro errore di HttpsError è gettato dalle vostre funzioni, il cliente riceve invece un errore con il messaggio INTERNAL ed il codice internal .

Ad esempio, una funzione potrebbe generare errori di convalida e autenticazione dei dati con messaggi di errore da restituire al client chiamante:

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

Distribuire la funzione richiamabile

Dopo aver salvato una funzione callable completato entro index.js , che viene distribuito insieme a tutte le altre funzioni quando si esegue firebase deploy . Per distribuire solo il richiamabile, utilizzare la --only argomento come mostrato effettuare implementa parziali :

$ firebase deploy --only functions:addMessage

Se si verificano errori di autorizzazioni durante la distribuzione di funzioni, assicurarsi che le appropriate ruoli IAM vengono assegnati per l'utente che esegue i comandi di distribuzione.

Configura il tuo ambiente di sviluppo client

Assicurati di soddisfare tutti i prerequisiti, quindi aggiungi le dipendenze richieste e le librerie client alla tua app.

iOS

  1. Seguire le istruzioni per aggiungere la Firebase al tuo iOS .
  2. Aggiungere il Funzioni pod Cloud per il vostro Podfile :
    pod 'Firebase/Functions'
  3. Salvare il file, quindi eseguire:
    pod install

Web v9

  1. Seguire le istruzioni per aggiungere la Firebase al vostro Web App .
  2. Aggiungere il nucleo Firebase e cloud librerie funzioni client per la vostra applicazione:
    <script src="https://www.gstatic.com/firebasejs/8.8.0/firebase.js"></script>
<script src="https://www.gstatic.com/firebasejs/8.8.0/firebase-functions.js"></script>

L'SDK di Cloud Functions è disponibile anche come pacchetto npm.

  1. Eseguire il seguente comando da terminale:
    npm install firebase@8.8.0 --save

  2. Richiedere manualmente sia nucleo Firebase e funzioni cloud:

    import { initializeApp } from 'firebase/app';
import { initializeFunctions } from 'firebase/functions';
    


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

Web v8

  1. Seguire le istruzioni per aggiungere la Firebase al vostro Web App .
  2. Aggiungere il nucleo Firebase e cloud librerie funzioni client per la vostra applicazione:
    <script src="https://www.gstatic.com/firebasejs/8.8.0/firebase.js"></script>
<script src="https://www.gstatic.com/firebasejs/8.8.0/firebase-functions.js"></script>

L'SDK di Cloud Functions è disponibile anche come pacchetto npm.

  1. Eseguire il seguente comando da terminale:
    npm install firebase@8.8.0 --save
  2. Richiedere manualmente sia nucleo Firebase e funzioni cloud:
    const firebase = require("firebase");
// Required for side-effects
require("firebase/functions");

Giava

  1. Seguire le istruzioni per aggiungere la Firebase per la vostra applicazione Android .

  2. Utilizzando la Firebase Android BoM , dichiarare la dipendenza per le funzioni cloud libreria Android nel modulo (a livello di app) File Gradle (di solito app/build.gradle ).

    dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:28.3.0')

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

    Usando il Firebase Android BoM , la vostra applicazione sarà sempre utilizzare versioni compatibili delle librerie Firebase Android.

    (Alternativa) Dichiarare Firebase dipendenze delle librerie senza utilizzare la distinta

    Se scegli di non utilizzare Firebase BoM, devi specificare ogni versione della libreria Firebase nella relativa riga di dipendenza.

    Si noti che se si utilizzano più librerie Firebase nella vostra app, ti consigliamo di utilizzare la distinta di gestire versioni della libreria, che assicura che tutte le versioni sono compatibili.

    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.0'
}

Kotlin+KTX

  1. Seguire le istruzioni per aggiungere la Firebase per la vostra applicazione Android .

  2. Utilizzando la Firebase Android BoM , dichiarare la dipendenza per le funzioni cloud libreria Android nel modulo (a livello di app) File Gradle (di solito app/build.gradle ).

    dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:28.3.0')

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

    Usando il Firebase Android BoM , la vostra applicazione sarà sempre utilizzare versioni compatibili delle librerie Firebase Android.

    (Alternativa) Dichiarare Firebase dipendenze delle librerie senza utilizzare la distinta

    Se scegli di non utilizzare Firebase BoM, devi specificare ogni versione della libreria Firebase nella relativa riga di dipendenza.

    Si noti che se si utilizzano più librerie Firebase nella vostra app, ti consigliamo di utilizzare la distinta di gestire versioni della libreria, che assicura che tutte le versioni sono compatibili.

    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.0'
}

C++

Per C ++ con Android:

  1. Seguire le istruzioni per aggiungere la Firebase al progetto C ++ .
  2. Aggiungere la firebase_functions libreria al CMakeLists.txt file.

Per C ++ con iOS:

  1. Seguire le istruzioni per aggiungere la Firebase al progetto C ++ .
  2. Aggiungere il Funzioni pod Cloud per il vostro Podfile :
    pod 'Firebase/Functions'
  3. Salvare il file, quindi eseguire:
    pod install
  4. Aggiungere il nucleo Firebase e cloud funzioni quadri dal Firebase SDK C ++ al progetto Xcode.
    • firebase.framework
    • firebase_functions.framework

Unità

  1. Seguire le istruzioni per aggiungere la Firebase al progetto Unity .
  2. Aggiungere il FirebaseFunctions.unitypackage dal Firebase Unity SDK al progetto Unity.

Inizializzare l'SDK client client

Inizializza un'istanza di Cloud Functions:

Swift

lazy var functions = Functions.functions()
CloudAddCell.swift

Obiettivo-C

@property(strong, nonatomic) FIRFunctions *functions;
// ...
self.functions = [FIRFunctions functions];
CloudAddCell.m

Web v8

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 v9

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

Giava

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

Kotlin+KTX

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

C++

firebase::functions::Functions* functions;
// ...
functions = firebase::functions::Functions::GetInstance(app);

Unità

functions = Firebase.Functions.DefaultInstance;

Chiama la funzione

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
  }
}
CommentCell.swift

Obiettivo-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"];
}];

Web v8

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

Web v9

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

Giava

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

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
            }
}
MainActivity.kt

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

Unità

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

Gestire gli errori sul client

Il client riceve un errore se il server ha generato un errore o se la promessa risultante è stata rifiutata.

Se l'errore restituito dalla funzione è di tipo function.https.HttpsError , il client riceve l'errore code , message , e details dal errore del server. In caso contrario, l'errore contiene il messaggio INTERNAL ed il codice INTERNAL . Vedere una guida su come gestire gli errori nella funzione callable.

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]
  }
  // ...
}
CloudAddCell.swift

Obiettivo-C

if (error) {
  if (error.domain == FIRFunctionsErrorDomain) {
    FIRFunctionsErrorCode code = error.code;
    NSString *message = error.localizedDescription;
    NSObject *details = error.userInfo[FIRFunctionsErrorDetailsKey];
  }
  // ...
}
CloudAddCell.m

Web v8

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

Web v9

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

Giava

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

                    // ...
                }

                // ...
            }
        });
MainActivity.java

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
                }

                // ...
            }

            // ...
        })
MainActivity.kt

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

Unità

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

Prima di lanciare la vostra applicazione, è necessario attivare App controllare per garantire che solo le applicazioni possono accedere gli endpoint funzioni richiamabili.