获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

开始:编写、测试和部署您的第一个函数

要开始使用 Cloud Functions,请尝试完成本教程,该教程从所需的设置任务开始,并通过创建、测试和部署两个相关函数来完成:

  • addMessage() ,它公开一个接受文本值并将其写入 Cloud Firestore 的 URL。
  • makeUppercase() ,触发 Cloud Firestore 写入并将文本转换为大写。

我们为此示例选择了 Cloud Firestore 和 HTTP 触发的 JavaScript 函数,部分原因是这些后台触发器可以通过Firebase Local Emulator Suite进行全面测试。此工具集还支持实时数据库、PubSub、Auth 和 HTTP 可调用触发器。其他类型的后台触发器(例如 Remote Config、TestLab 和 Analytics 触发器)都可以使用本页中未描述的工具集进行交互式测试

本教程的以下部分详细介绍了构建、测试和部署示例所需的步骤。如果您只想运行代码并检查它,请跳转到Review complete sample code

创建 Firebase 项目

  1. Firebase 控制台中,单击添加项目

    • 要将 Firebase 资源添加到现有的Google Cloud 项目,请输入其项目名称或从下拉菜单中选择它。

    • 要创建新项目,请输入所需的项目名称。您还可以选择编辑项目名称下方显示的项目 ID。

  2. 如果出现提示,请查看并接受Firebase 条款

  3. 单击继续

  4. (可选)为您的项目设置 Google Analytics,这使您能够使用以下任何 Firebase 产品获得最佳体验:

    选择现有的Google Analytics 帐户或创建一个新帐户。

    如果您创建一个新帐户,请选择您的Analytics 报告位置,然后接受您项目的数据共享设置和 Google Analytics 条款。

  5. 点击创建项目(或添加 Firebase ,如果您使用的是现有的 Google Cloud 项目)。

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 CLI。
  2. 转到您的 Firebase 项目目录。
  3. 运行firebase init firestore 。对于本教程,您可以在提示输入 Firestore 规则和索引文件时接受默认值。如果您尚未在此项目中使用 Cloud Firestore,您还需要按照开始使用 Cloud Firestore中所述选择 Firestore 的启动模式和位置​​。
  4. 运行firebase init functions 。 CLI 会提示您选择现有代码库或初始化并命名一个新代码库。当您刚刚开始时,默认位置的单个代码库就足够了;稍后,随着您的实现扩展,您可能希望在 codebases 中组织函数
  5. CLI 为您提供了两种语言支持选项:

    对于本教程,选择JavaScript

  6. CLI 为您提供了使用 npm 安装依赖项的选项。如果您想以其他方式管理依赖项,则拒绝是安全的,但如果您拒绝,则需要在模拟或部署函数之前运行npm install

这些命令成功完成后,您的项目结构如下所示:

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": "16"} 。这指定了用于编写和部署函数的 Node.js 版本。您可以选择其他支持的版本

导入所需模块并初始化应用程序

完成设置任务后,您可以打开源目录并开始添加代码,如以下部分所述。对于此示例,您的项目必须使用 Node 的require语句导入 Cloud Functions 和 Admin SDK 模块。在index.js文件中添加如下行:

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

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

这些行加载firebase-functionsfirebase-admin模块,并初始化一个admin应用实例,可以从中进行 Cloud Firestore 更改。无论在哪里提供Admin SDK支持,例如用于 FCM、身份验证和 Firebase 实时数据库,它都提供了一种使用 Cloud Functions 集成 Firebase 的强大方法。

初始化项目时,Firebase CLI 会自动安装 Firebase 和 Firebase SDK for Cloud Functions Node 模块。要将 3rd 方库添加到您的项目中,您可以修改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 样式的请求响应对象传递给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});
    });

makeUppercase()函数在写入 Cloud Firestore 时执行。 ref.set函数定义了要监听的文档。出于性能原因,您应该尽可能具体。

大括号 - 例如, {documentId} - 包围“参数”,通配符在回调中公开其匹配数据。

每当添加新消息时,Cloud Firestore 都会触发onCreate()回调。

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 。或者,您可以将消息“大写”更改为自定义消息。

  4. 通过在浏览器的新选项卡中打开 URL 来创建新消息。

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

    1. Logs选项卡中,您应该会看到新的日志,表明函数addMessage()makeUppercase()运行:

      i 函数:开始执行“addMessage”

      i 函数:开始执行“makeUppercase”

    2. Firestore选项卡中,您应该会看到一个文档,其中包含您的原始消息以及大写版本的消息(如果它最初是“uppercaseme”,您将看到“UPPERCASEME”)。

将功能部署到生产环境

一旦您的功能在模拟器中按需要运行,您就可以继续在生产环境中部署、测试和运行它们。请记住,要部署到推荐的 Node.js 14 运行时环境,您的项目必须采用Blaze 定价计划。请参阅Cloud Functions 定价

要完成本教程,请部署您的函数,然后执行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() ,它写入字符串的大写版本。

部署并执行功能后,您可以在Google Cloud Console中查看日志。如果您需要在开发或生产中删除函数,请使用 Firebase CLI。

在生产中,您可能希望通过设置要运行的最小和最大实例数来优化函数性能并控制成本。有关这些运行时选项的更多信息,请参阅控制缩放行为

查看完整的示例代码

这是包含函数addMessage()makeUppercase()的完整functions/index.js /index.js。这些函数允许您将参数传递给 HTTP 端点,该端点将值写入 Cloud Firestore,然后通过将字符串中的所有字符大写来对其进行转换。

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up 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 的更多信息。在本视频中,您将找到有关开始使用 Cloud Functions 的详细指南,包括 Node.js 和 CLI 设置。