開始使用：編寫、測試及部署第一個函式

第 2 代 第 1 代

如要開始使用 Cloud Functions，請嘗試完成本教學課程，從必要的設定工作開始，然後建立、測試及部署兩個相關的函式：

• 「add message」函式會公開可接受文字值的網址，並將該值寫入 Cloud Firestore。
• 這個「make uppercase」函式會在 Cloud Firestore 寫入時觸發，並將文字轉換為大寫。

以下是包含函式的完整程式碼範例：

Node.js

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await getFirestore()
      .collection("messages")
      .add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

Python

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()


@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")


@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

關於本教學課程

我們選擇使用 Cloud Firestore 和 HTTP 觸發函式做為本範例的一部分，是因為這些背景觸發事件可透過 Firebase Local Emulator Suite 進行徹底測試。這個工具組也支援 Realtime Database、Cloud Storage、PubSub、Auth 和 HTTP 可呼叫的觸發條件。您可以使用本頁未提及的工具組以互動方式測試其他類型的背景觸發事件，例如 Remote Config 和 TestLab 觸發事件。

注意： 您可以在任何 Firebase 專案中模擬函式，但如要部署函式，專案必須採用 Blaze 定價方案。請參閱 Cloud Functions 定價。

本教學課程的後續章節將詳細說明建構、測試及部署範例所需的步驟。

建立 Firebase 專案

1. 在 Firebase 控制台中，按一下「新增專案」。

   • 如要將 Firebase 資源新增至現有 Google Cloud 專案，請輸入專案名稱，或從下拉式選單中選取。

   • 如要建立新專案，請輸入所需的專案名稱。您也可以視需要編輯專案名稱下方顯示的專案 ID。

     Firebase 會根據您指定的名稱，為 Firebase 專案產生專屬 ID。如果您想編輯這個專案 ID，請務必立即執行，因為 Firebase 為專案配置資源後，就無法再變更。請參閱「瞭解 Firebase 專案」，瞭解 Firebase 如何使用專案 ID。

2. 系統提示時，請詳閱並接受 Firebase 條款。

3. 按一下「繼續」。

4. (選用) 為專案設定 Google Analytics，即可在使用下列任何 Firebase 產品時，獲得最佳體驗：

   Firebase Crashlytics Firebase Cloud Messaging

   Firebase In-App Messaging Firebase Remote Config

   Remote Config 個人化 Firebase A/B Testing

   選取現有的 Google Analytics 帳戶或建立新帳戶。

   如果您建立新帳戶，請選取Analytics報表位置，然後接受專案的資料共用設定和 Google Analytics 條款。

   您稍後可以前往 「專案設定」分頁的「整合」分頁標籤，設定 Google Analytics。

5. 按一下「建立專案」 (如果您使用的是現有的 Google Cloud 專案，請按一下「新增 Firebase」)。

Firebase 會自動為 Firebase 專案佈建資源。程序完成後，您會前往 Firebase 主控台的 Firebase 專案總覽頁面。

設定環境和 Firebase CLI

Node.js

您需要 Node.js 環境才能編寫函式，並需要 Firebase CLI 才能將函式部署至 Cloud Functions 執行階段。如要安裝 Node.js 和 npm，建議使用 Node Version Manager。

重要事項： Cloud Functions 和 Firebase CLI 完全支援 Node.js 18 和 20 版，並提供 22 版的預覽版支援。14 和 16 已淘汰，並將於 2025 年初停用 (目前已停用這些已淘汰版本的部署作業)。如要瞭解這些 Node.js 版本的持續支援服務，請參閱「設定執行階段選項」一文。

安裝 Node.js 和 npm 後，請透過偏好的方法安裝 Firebase CLI。如要透過 npm 安裝 CLI，請使用以下指令：

npm install -g firebase-tools

這樣就會安裝全球適用的 firebase 指令。如果指令失敗，您可能需要變更 npm 權限。如要更新至最新版的 firebase-tools，請重新執行相同的指令。

在許多情況下，新功能和錯誤修正只能透過最新版本的 Firebase CLI 和 firebase-functions SDK 取得。建議您經常使用 Firebase 專案 functions 資料夾中的這些指令，同時更新 Firebase CLI 和 SDK：

npm install firebase-functions@latest firebase-admin@latest --save
npm install -g firebase-tools

Python

您需要 Python 環境來編寫函式，並使用 Firebase CLI 將函式部署至 Cloud Functions 執行階段。建議您使用 venv 隔離依附元件。支援 Python 版本 3.10 和 3.11。

安裝 Python 後，請使用偏好的方法安裝 Firebase CLI。

在許多情況下，新功能和錯誤修正只能透過最新版本的 Firebase CLI 和 firebase-functions SDK 取得。建議您經常更新 Firebase 專案 functions 資料夾中的 Firebase CLI 和 SDK。

初始化您的專案

為 Cloud Functions 初始化 Firebase SDK 時，您會建立空專案，其中包含依附元件和一些最少的程式碼範例。如果您使用的是 Node.js，可以選擇使用 TypeScript 或 JavaScript 來組合函式。為了配合本教學課程，您還需要初始化 Cloud Firestore。

如要初始化專案，請按照下列步驟操作：

1. 執行 firebase login 即可透過瀏覽器登入，並驗證 Firebase CLI。
2. 前往 Firebase 專案目錄。
3. 執行 firebase init firestore。 在本教學課程中，當系統提示您設定 Firestore 規則和索引檔案時，您可以接受預設值。如果您尚未在這個專案中使用 Cloud Firestore，也需要選取 Firestore 的啟動模式和位置，如開始使用 Cloud Firestore 所述。
4. 執行 firebase init functions。 CLI 會提示您選擇現有的程式碼集，或是初始化並命名新的程式碼集。剛開始時，只要在預設位置建立單一程式碼集即可；日後隨著實作內容擴增，您可能需要在程式碼集中整理函式。

5. CLI 提供下列語言支援選項：

   • JavaScript
   • TypeScript
   • Python

   在本教學課程中，請選取「JavaScript」或「Python」。如要使用 TypeScript 撰寫內容，請參閱「使用 TypeScript 編寫函式」。

6. CLI 提供安裝依附元件的選項。如果您想以其他方式管理依附元件，可以放心拒絕。

這些指令順利完成後，專案結構會如下所示：

Node.js

myproject
+- .firebaserc    # Hidden file that helps you quickly switch between
|                 # projects with `firebase use`
|
+- firebase.json  # Describes properties for your project
|
+- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # Main source file for your Cloud Functions code
      |
      +- node_modules/ # Directory where your dependencies (declared in
                        # package.json) are installed

就 Node.js 而言，初始化期間建立的 package.json 檔案包含一個重要索引鍵："engines": {"node": "18"}。這會指定 Node.js 版本，用於編寫及部署函式。您可以選取其他支援的版本。

Python

myproject
+- .firebaserc    # Hidden file that helps you quickly switch between
|                 # projects with `firebase use`
|
+- firebase.json  # Describes properties for your project
|
+- functions/     # Directory containing all your functions code
      |
      +- main.py      # Main source file for your Cloud Functions code
      |
      +- requirements.txt  #  List of the project's modules and packages 
      |
      +- venv/ # Directory where your dependencies are installed

匯入必要模組並初始化應用程式

完成設定工作後，您可以開啟來源目錄，並開始新增程式碼，如以下各節所述。對於這個範例，專案必須匯入 Cloud Functions 和 Admin SDK 模組。在來源檔案中加入以下類似的程式碼行：

Node.js

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();
index.js

Python

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()
main.py

這些行會載入必要的模組，並初始化 admin 應用程式執行個體，以便進行 Cloud Firestore 變更。Admin SDK 支援的 FCM、Authentication 和 Firebase Realtime Database 皆提供強大的整合方式，可使用 Cloud Functions 整合 Firebase。

Firebase CLI 會在您初始化專案時，自動為 Cloud Functions 模組安裝 Firebase Admin SDK 和 Firebase SDK。如要進一步瞭解如何將第三方程式庫新增至專案，請參閱「處理依附元件」。

新增「add message」函式

針對「add message」函式，請在來源檔案中加入下列幾行內容：

Node.js

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await getFirestore()
      .collection("messages")
      .add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});
index.js

Python

@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")
main.py

「add message」函式是 HTTP 端點。任何對端點的要求，都會導致要求和回應物件傳遞至平台的要求處理常式 (onRequest() 或 on_request)。

HTTP 函式為同步 (類似於可呼叫的函式)，因此您應盡快傳送回應，並使用 Cloud Firestore 延後工作。「add message」HTTP 函式會將文字值傳遞至 HTTP 端點，並將其插入 /messages/:documentId/original 路徑下的資料庫中。

新增「大寫」函式

針對「將字母轉為大寫」函式，請在來源檔案中加入下列程式碼行：

Node.js

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

Python

@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

當 Cloud Firestore 寫入時，「make uppercase」函式會執行，定義要監聽的文件。基於效能考量，請盡可能具體說明。

大括號 (例如 {documentId}) 會包圍「參數」(萬用字元)，這些參數會在回呼中公開相符的資料。Cloud Firestore 會在新增新訊息時觸發回呼。

注意： 請小心避免任何函式結果實際重新觸發函式，進而產生無限迴圈的情況，例如透過寫入特定 Cloud Firestore 文件觸發函式，然後透過寫入相同路徑終止函式。此外，請務必以冪等的方式編寫函式，這樣一來，如果函式針對單一事件執行多次，就會產生相同的結果。

在 Node.js 中，事件驅動函式 (例如 Cloud Firestore 事件) 為非同步。回呼函式應傳回 null、物件或承諾。如果您沒有傳回任何內容，函式就會逾時，並傳送錯誤信號，然後重試。請參閱「同步、非同步和承諾」。

模擬函式的執行作業

Firebase Local Emulator Suite 可讓您在本機電腦上建構及測試應用程式，而非部署至 Firebase 專案。我們強烈建議您在開發期間進行本機測試，部分原因是因為這麼做可降低程式碼錯誤的風險，這些錯誤可能會在實際執行環境中造成成本 (例如無限迴圈)。

如要模擬函式，請按照下列步驟操作：

1. 執行 firebase emulators:start，並檢查輸出內容的 Emulator Suite UI 網址。預設為 localhost:4000，但可能會在電腦上的其他通訊埠上託管。在瀏覽器中輸入該網址，即可開啟 Emulator Suite UI。

2. 請檢查 firebase emulators:start 指令的輸出內容，找出 HTTP 函式的網址。除了以下幾點之外，其餘都與 http://localhost:5001/MY_PROJECT/us-central1/addMessage 類似：

   1. MY_PROJECT 會替換為您的專案 ID。
   2. 本機電腦上的通訊埠可能不同。

3. 將查詢字串 ?text=uppercaseme 新增至函式的網址結尾。應該會像這樣：http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme。您可以視需要將訊息「uppercaseme」變更為自訂訊息。

4. 在瀏覽器的新分頁中開啟網址，即可建立新訊息。

5. 查看 Emulator Suite UI 中的函式效果：

   1. 在「Logs」分頁中，您應該會看到新的記錄，指出 HTTP 函式已成功執行：

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

   2. 在「Firestore」分頁中，您應該會看到包含原始訊息和大寫訊息的文件 (如果原始訊息是「uppercaseme」，您會看到「UPPERCASEME」)。

將函式部署至實際工作環境

函式在模擬器中正常運作後，您就可以繼續在實際工作環境中部署、測試及執行函式。請注意，如要部署至實際環境，專案必須採用 Blaze 定價方案。請參閱 Cloud Functions 定價。

如要完成本教學課程，請部署函式並執行函式。

1. 執行下列指令來部署函式：

    firebase deploy --only functions
    

   執行這項指令後，Firebase CLI 會輸出任何 HTTP 函式端點的網址。您應該會在終端機中看到類似以下的文字行：

   Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
   

   網址包含專案 ID 和 HTTP 函式所在的地區。雖然您現在不必擔心這點，但某些實際的 HTTP 函式應指定位置，以盡量減少網路延遲時間。

   如果您遇到「無法授權存取專案」等存取錯誤，請嘗試檢查專案別名。

2. 使用 CLI 輸出的網址，新增文字查詢參數，然後在瀏覽器中開啟：

   https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
   

   這個函式會執行並將瀏覽器重新導向至 Firebase 主控台，並在該資料庫位置儲存文字字串。這個寫入事件會觸發「make uppercase」函式，該函式會寫入字串的大寫版本。

部署及執行函式後，您可以在 Google Cloud 控制台中查看記錄。如果您需要在開發或實際環境中刪除函式，請使用 Firebase CLI。

在實際環境中，您可能會想設定執行個體的最低和最高數量，以便最佳化函式效能並控管成本。如要進一步瞭解這些執行階段選項，請參閱「控制資源調度行為」。

注意： 從 Firebase CLI 部署函式時，會受到速率限制。請參閱「Firebase CLI 部署作業的配額限制」一文。

後續步驟

您可以透過本說明文件進一步瞭解如何管理 Cloud Functions 的函式，以及如何處理 Cloud Functions 支援的所有事件類型。

如要進一步瞭解 Cloud Functions，您也可以採取下列做法：

• 請參閱Cloud Functions的用途。
• 試用 Cloud Functions 程式碼研究室。
• 查看並執行 GitHub 上的程式碼範例