Google 致力于为黑人社区推动种族平等。查看具体举措
本頁面由 Cloud Translation API 翻譯而成。
Switch to English

入門:編寫,測試和部署您的第一個功能

要開始使用Cloud Functions,請嘗試完成本教程,該教程以必需的設置任務開始,並通過創建,測試和部署兩個相關功能進行工作:

  • addMessage() ,它公開一個接受文本值的URL並將其寫入Cloud Firestore。
  • makeUppercase() ,它會在Cloud Firestore上觸發寫入並將文本轉換為大寫形式。

我們為此示例選擇了Cloud Firestore和HTTP觸發的JavaScript函數,部分原因是可以通過Firebase Local Emulator Suite徹底測試這些背景觸發器。該工具集還支持實時數據庫,PubSub,Auth和HTTP可調用觸發器。其他類型的後台觸發器(例如Remote Config,TestLab和Analytics觸發器)都可以使用此頁面中未描述的工具集進行交互測試

本教程的以下各節詳細介紹了構建,測試和部署樣本所需的步驟。如果您只想運行代碼並檢查代碼,請跳至“查看完整的示例代碼”

創建Firebase項目

  1. Firebase控制台中,單擊“添加項目” ,然後選擇或輸入項目名稱

    如果您有現有的Google Cloud項目,則可以從下拉菜單中選擇該項目,以將Firebase資源添加到該項目。

  2. (可選)如果您要創建一個新項目,則可以編輯Project ID

    Firebase會自動為您的Firebase項目分配一個唯一ID。訪問了解Firebase項目了解Firebase如何使用項目ID。

  3. 點擊繼續

  4. (可選)為您的項目設置Google Analytics(分析 ,使您可以使用以下任意Firebase產品獲得最佳體驗:

    出現提示時,選擇使用現有的Google Analytics(分析)帳戶或創建一個新帳戶。
    如果您選擇創建一個新帳戶,請選擇您的Google Analytics(分析)報告位置,然後接受項目的數據共享設置和Google Analytics(分析)條款。

  5. 點擊創建項目(如果您正在使用現有的Google Cloud項目,則點擊添加Firebase )。

Firebase會自動為您的Firebase項目配置資源。該過程完成後,您將進入Firebase控制台中Firebase項目的概述頁面。

設置Node.js和Firebase CLI

您將需要一個Node.js環境來編寫函數,並且需要Firebase CLI來將函數部署到Cloud Functions運行時。要安裝Node.js和npm ,建議使用Node Version Manager

安裝完Node.js和npm後,通過首選方法安裝Firebase CLI 。要通過npm安裝CLI,請使用:

npm install -g firebase-tools

這將安裝全局可用的firebase命令。如果命令失敗,則可能需要更改npm權限。要更新到最新版本的firebase-tools ,請重新運行相同的命令。

初始化您的項目

初始化Firebase SDK for Cloud Functions時,會創建一個包含依賴項和一些最少示例代碼的空項目,並選擇TypeScript或JavaScript來編寫函數。就本教程而言,您還需要初始化Cloud Firestore。

要初始化您的項目:

  1. 運行firebase login以通過瀏覽器firebase login並驗證firebase工具。
  2. 轉到您的Firebase項目目錄。
  3. 運行firebase init firestore 。對於本教程,當提示您輸入Firestore規則和索引文件時,您可以接受默認值。如果您尚未在此項目中使用Cloud Firestore,則還需要按照Cloud Firestore入門中所述選擇Firestore的啟動模式和位置​​。
  4. 運行firebase init functions 。該工具為您提供了使用npm安裝依賴項的選項。如果您想以另一種方式管理依賴關係,則可以安全地拒絕,但是如果您拒絕,則需要在模擬或部署功能之前運行npm install
  5. 該工具為您提供了兩種語言支持選項:

    對於本教程,請選擇JavaScript

這些命令成功完成後,您的項目結構如下所示:

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

在初始化期間創建的package.json文件包含一個重要鍵: "engines": {"node": "10"} 。這指定用於編寫和部署功能的Node.js版本。您可以選擇其他受支持的版本

導入所需的模塊並初始化應用

完成設置任務後,您可以打開源目錄並按照以下各節中的說明開始添加代碼。對於此樣本,您的項目必須使用Node require語句導入Cloud Functions和Admin SDK模塊。將以下內容添加到index.js文件中:

// The Cloud Functions for Firebase SDK to create Cloud Functions and setup triggers.
const functions = require('firebase-functions');

// The Firebase Admin SDK to access Firestore.
const admin = require('firebase-admin');
admin.initializeApp();

這些行會加載firebase-functionsfirebase-admin模塊,並初始化可從其進行Cloud Firestore更改的admin應用程序實例。無論在何處獲得Admin SDK支持,例如FCM,身份驗證和Firebase實時數據庫,它都提供了一種使用Cloud Functions集成Firebase的強大方法。

初始化項目時,Firebase CLI會自動為雲功能節點模塊安裝Firebase和Firebase SDK。要將第三方庫添加到您的項目,可以修改package.json並運行npm install 。有關更多信息,請參見處理依賴項

添加addMessage()函數

對於addMessage()函數,將這些行添加到index.js

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.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 admin.firestore().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.`});
});

addMessage()函數是一個HTTP端點。對端點的任何請求都將導致ExpressJS樣式的RequestResponse對像傳遞到onRequest()回調。

HTTP函數是同步的(類似於可調用函數),因此您應盡快發送響應並推遲使用Cloud Firestore的工作。 addMessage() HTTP函數將文本值傳遞到HTTP端點,並將其插入到/messages/:documentId/original路徑下的數據庫中。

添加makeUppercase()函數

對於makeUppercase()函數,將這些行添加到index.js

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore.document('/messages/{documentId}')
    .onCreate((snap, context) => {
      // Grab the current value of what was written to Firestore.
      const original = snap.data().original;

      // Access the parameter `{documentId}` with `context.params`
      functions.logger.log('Uppercasing', context.params.documentId, original);
      
      const uppercase = original.toUpperCase();
      
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to Firestore.
      // Setting an 'uppercase' field in Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

當寫入Cloud Firestore時執行makeUppercase()函數。 ref.set函數定義要監聽的文檔。出於性能原因,您應該盡可能具體。

花括號(例如{documentId}環繞“參數”,即通配符,用於在回調中公開其匹配的數據。

每當在給定文檔上寫入或更新數據時,Cloud Firestore都會觸發onWrite()回調。

由事件驅動的功能(例如Cloud Firestore事件)是異步的。回調函數應返回null ,Object或Promise 。如果不返回任何內容,則該函數超時,表示發生錯誤,然後重試。請參閱同步,異步和承諾

模擬功能的執行

Firebase本地仿真器套件可讓您在本地計算機上構建和測試應用程序,而無需部署到Firebase項目。強烈建議在開發過程中進行本地測試,部分原因是它降低了編碼錯誤的風險,而編碼錯誤可能會在生產環境中產生成本(例如,無限循環)。

要模擬您的功能,請執行以下操作:

  1. 運行firebase emulators:start並檢查輸出,以獲取Emulator Suite UI的URL。它默認為localhost:4000 ,但可以託管在計算機上的其他端口上。在瀏覽器中輸入該URL,以打開Emulator Suite UI。

  2. 檢查firebase emulators:start命令的輸出,以獲取HTTP函數addMessage()的URL。它看起來類似於http://localhost:5001/MY_PROJECT/us-central1/addMessage ,除了:

    1. MY_PROJECT將替換為您的項目ID。
    2. 您的本地計算機上的端口可能不同。
  3. 將查詢字符串?text=uppercaseme到函數URL的末尾。看起來應該像這樣: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme 。 (可選)您可以將消息“ uppercaseme”更改為自定義消息。

  4. 通過在瀏覽器的新標籤頁中打開URL來創建新消息。

  5. 在Emulator Suite UI中查看功能的效果:

    1. 在“日誌”選項卡中,您應該看到新的日誌,指示函數addMessage()makeUppercase()運行:

      我的職能:開始執行“ addMessage”

      我的職能:開始執行“ makeUppercase”

    2. 在“ Firestore”選項卡中,您應該看到一個文檔,其中包含原始消息以及消息的大寫版本(如果最初是“ uppercaseme”,則將顯示“ UPPERCASEME”)。

將功能部署到生產環境

一旦您的功能在仿真器中可以正常工作,您就可以繼續在生產環境中部署,測試和運行它們。請記住,要部署到推薦的Node.js 12運行時環境,您的項目必須處於Blaze即用即付計費計劃中。請參閱“雲功能定價”

要完成本教程,請部署您的函數,然後執行addMessage()來觸發makeUppercase()

  1. 運行以下命令以部署功能:

    $ firebase deploy --only functions
    

    運行此命令後,Firebase CLI將輸出所有HTTP功能終結點的URL。在您的終端中,您應該看到類似以下的行:

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

    該URL包含您的項目ID以及HTTP函數的區域。儘管您現在不必擔心,但某些生產HTTP函數應指定一個位置以最大程度地減少網絡延遲。

    如果遇到訪問錯誤,例如“無法授權對項目的訪問”,請嘗試檢查項目別名

  2. 使用CLI輸出的addMessage() URL,添加文本查詢參數,然後在瀏覽器中將其打開:

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

    該函數執行並將瀏覽器重定向到存儲文本字符串的數據庫位置的Firebase控制台。此寫事件觸發makeUppercase() ,該makeUppercase()將寫一個大寫版本的字符串。

部署和執行功能後,您可以 在Firebase控制台中查看Cloud Functions的日誌。如果您需要刪除開發或生產中的功能,請使用Firebase CLI。

查看完整的示例代碼

這是包含函數addMessage()makeUppercase()的完整functions/index.js makeUppercase() 。這些功能允許您將參數傳遞到HTTP端點,該端點將值寫入Cloud Firestore,然後通過大寫字符串中的所有字符來對其進行轉換。

// The Cloud Functions for Firebase SDK to create Cloud Functions and setup triggers.
const functions = require('firebase-functions');

// The Firebase Admin SDK to access Firestore.
const admin = require('firebase-admin');
admin.initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into 
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.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 admin.firestore().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 creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore.document('/messages/{documentId}')
    .onCreate((snap, context) => {
      // Grab the current value of what was written to Firestore.
      const original = snap.data().original;

      // Access the parameter `{documentId}` with `context.params`
      functions.logger.log('Uppercasing', context.params.documentId, original);
      
      const uppercase = original.toUpperCase();
      
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to Firestore.
      // Setting an 'uppercase' field in Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

下一步

在本文檔中,您可以找到有關Cloud Functions通用概念的更多信息,以及有關編寫函數以處理Cloud Functions支持的事件類型的指南。

要了解有關雲功能的更多信息,您還可以執行以下操作:

影片教學

您可以通過觀看視頻教程來了解有關Cloud Functions的更多信息。在此視頻中,您將找到有關Cloud Functions入門的詳細指南,包括Node.js和CLI設置。