Watch demos on how to build & run AI-powered apps with Firebase at Demo Day '24. Watch now.

本頁面由 Cloud Translation API 翻譯而成。

透過應用程式呼叫函式

Cloud Functions for Firebase 用戶端 SDK 可讓您直接從 Firebase 應用程式呼叫函式。如要透過這種方式從應用程式呼叫函式，請在 Cloud Functions 中編寫並部署 HTTP 可呼叫函式，然後新增用戶端邏輯，以便從應用程式呼叫函式。

請務必注意，HTTP 可呼叫函式與 HTTP 函式相似，但不相同。如要使用 HTTP 可呼叫函式，您必須使用平台的用戶端 SDK 搭配後端 API (或實作通訊協定)。可呼叫項與 HTTP 函式的主要差異如下：

使用可呼叫項時，系統會自動將 Firebase Authentication 權杖、FCM 權杖和 App Check 權杖 (如有) 納入要求。
觸發條件會自動對要求主體進行去序列化，並驗證驗證權杖。

Cloud Functions 第 2 代以上版本的 Firebase SDK 與下列 Firebase 用戶端 SDK 最低版本互通，以支援 HTTPS 可呼叫函式：

Firebase SDK for Apple platforms 11.5.0
Firebase SDK for Android 21.1.0
Firebase Modular Web SDK 9.7.0 版

如果您想在未支援的平台上建構的應用程式中加入類似的功能，請參閱 https.onCall 的通訊協定規格。本指南的其餘部分會提供如何為 Apple 平台、Android、網頁、C++ 和 Unity 編寫、部署及呼叫 HTTP 可呼叫函式的操作說明。

編寫及部署可呼叫的函式

本節的程式碼範例是根據完整的快速入門範例編寫，說明如何傳送要求至伺服器端函式，並使用其中一個用戶端 SDK 取得回應。如要開始使用，請匯入必要的模組：

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

Python

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

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

使用平台的請求處理常式 (functions.https.onCall) 或 on_call) 建立 HTTPS 可呼叫函式。這個方法會接收要求參數：

Node.js

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

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."""main.py

request 參數包含從用戶端應用程式傳遞的資料，以及驗證狀態等其他背景資訊。舉例來說，如果可呼叫函式將文字訊息儲存至 Realtime Database，data 可包含訊息文字，以及 auth 中的驗證資訊：

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

Python

# Message text passed from the client.
text = req.data["text"]main.py
# 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", "")main.py

可呼叫函式的位置與呼叫用戶端的位置之間的距離，可能會造成網路延遲。為提升效能，建議您在適用情況下指定函式位置，並確保在用戶端初始化 SDK時，呼叫端位置與設定的位置一致。

您可以選擇附加 App Check 認證，以保護後端資源，避免發生帳單詐欺或網路釣魚等濫用行為。請參閱「為 Cloud Functions 啟用 App Check 強制執行功能」。

傳回結果

如要將資料傳回至用戶端，請傳回可進行 JSON 編碼的資料。舉例來說，如要傳回加法運算的結果：

Node.js

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

Python

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

訊息文字範例經過淨化的文字會傳回給用戶端和 Realtime Database。在 Node.js 中，您可以使用 JavaScript 承諾以非同步方式執行這項操作：

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

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}main.py

設定 CORS (跨源資源共享)

使用 cors 選項控管哪些來源可以存取函式。

根據預設，可呼叫的函式會將 CORS 設為允許來自所有來源的要求。如要允許部分跨來源要求 (但不是全部)，請傳遞應允許的特定網域或規則運算式清單。例如：

Node.js

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

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

如要禁止跨來源要求，請將 cors 政策設為 false。

處理錯誤

為確保用戶端能取得實用的錯誤詳細資料，請擲回 (或在 Node.js 傳回遭拒絕的 Promise) functions.https.HttpsError 或 https_fn.HttpsError 的例項，藉此從可呼叫的項目傳回錯誤。錯誤包含 code 屬性，可為 gRPC 狀態碼中列出的其中一個值。錯誤也包含字串 message，預設為空字串。也可以含有選用的 details 欄位，其中含有任意值。如果函式擲回的不是 HTTPS 錯誤，則客戶端會收到錯誤訊息，其中包含訊息 INTERNAL 和代碼 internal。

舉例來說，函式可以擲回資料驗證和驗證錯誤，並傳回錯誤訊息給呼叫端用戶端：

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

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.")main.py

部署可呼叫的函式

在 index.js 中儲存完成的呼叫函式後，執行 firebase deploy 時，系統會將該函式與所有其他函式一併部署。如要只部署可呼叫項目，請使用 --only 引數，如圖所示，執行部分部署：

firebase deploy --only functions:addMessage

如果在部署函式時遇到權限錯誤，請務必將適當的 IAM 角色指派給執行部署指令的使用者。

設定用戶端開發環境

請確認您已符合所有先決條件，然後將必要的依附元件和用戶端程式庫新增至應用程式。

iOS+

按照操作說明將 Firebase 新增至 Apple 應用程式。

使用 Swift Package Manager 安裝及管理 Firebase 依附元件。

在 Xcode 中保持開啟應用程式專案，然後依序點選「File」>「Add Packages」。
系統顯示提示訊息時，請新增 Firebase Apple 平台 SDK 存放區：

  https://github.com/firebase/firebase-ios-sdk.git

選擇 Cloud Functions 程式庫。
將 -ObjC 標記新增至目標的建構設定「Other Linker Flags」部分。
完成後，Xcode 就會自動開始在背景中解析並下載依附元件。

Web

按照操作說明將 Firebase 新增至您的網路應用程式。請務必透過終端機執行下列指令：
```
npm install firebase@11.0.2 --save
```

手動要求 Firebase 核心和 Cloud Functions：

 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

按照操作說明將 Firebase 新增至 Android 應用程式。
在模組 (應用程式層級) Gradle 檔案 (通常為 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle) 中，加入 Android 的 Cloud Functions 程式庫依附元件。建議您使用 Firebase Android BoM 來控制程式庫版本。
```
dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.6.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")
}
```
只要使用 Firebase Android BoM，應用程式就會一律使用相容的 Firebase Android 程式庫版本。
(替代做法) 不使用 BoM 新增 Firebase 程式庫依附元件

如果您選擇不使用 Firebase BoM，則必須在依附元件行中指定每個 Firebase 程式庫版本。

請注意，如果您在應用程式中使用多個 Firebase 程式庫，強烈建議您使用 BoM 來管理程式庫版本，確保所有版本皆相容。
```
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.1.0")
}
```
想找 Kotlin 專屬的程式庫模組嗎？自 2023 年 10 月 (Firebase BoM 32.5.0)起，Kotlin 和 Java 開發人員皆可依賴主要程式庫模組 (詳情請參閱這項計畫的常見問題)。

初始化用戶端 SDK

初始化 Cloud Functions 的例項：

Swift

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

Objective-C

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

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.functionsMainActivity.kt

Java

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

呼叫函式

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

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

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

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

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

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

Unity

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

處理用戶端的錯誤

如果伺服器擲回錯誤，或是產生的承諾遭到拒絕，用戶端就會收到錯誤。

如果函式傳回的錯誤為 function.https.HttpsError 類型，用戶端會從伺服器錯誤收到 code、message 和 details 錯誤。否則，錯誤會包含訊息 INTERNAL 和代碼 INTERNAL。請參閱指南，瞭解如何在可呼叫的函式中處理錯誤。

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

Objective-C

if (error) {
  if ([error.domain isEqual:@"com.firebase.functions"]) {
    FIRFunctionsErrorCode code = error.code;
    NSString *message = error.localizedDescription;
    NSObject *details = error.userInfo[@"details"];
  }
  // ...
}CloudAddCell.m

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

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

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

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

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

Unity

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

建議做法：使用 App Check 防範濫用行為

在發布應用程式之前，請啟用 App Check，確保只有您的應用程式可以存取可呼叫的函式端點。