使用入门:编写和部署您的第一批函数

要开始使用 Cloud Functions,请浏览此教程,从必需的设置任务开始,直到完成两个相关函数的创建和部署为止:

  • addMessage() - 提供一个网址,该网址接受文本值并将其写入实时数据库。
  • makeUppercase() - 在有数据写入实时数据库时触发,会将文本转换为大写。

我们为此示例选择了由实时数据库和 HTTP 触发的函数,但您也可以选择用许多其他方式来触发函数。请参阅关于身份验证事件Analytics 事件及其他事件的操作指南。

在您的 Firebase 项目中构建示例

本教程的以下各节内容将详细介绍构建和部署示例所需的步骤。如果您只想运行和检查代码,请跳转到查看完整的示例代码

设置和初始化 Firebase SDK for Cloud Functions

首先,按照 Firebase CLI 参考中的说明安装 Firebase CLI。Firebase CLI 需要使用 Node.jsnpm(您可以按照 https://nodejs.org/ 上的说明进行安装)。安装 Node.js 会同时安装 npm。

Cloud Functions 运行的是 Node v6.14.0,因此我们建议您使用此版本进行本地开发。

安装 Node.js 和 npm 后,您就可以通过 npm 安装 Firebase CLI:

npm install -g firebase-tools

这会安装全局可用的 Firebase 命令。如果命令失败,您可能需要更改 npm 权限。要更新到最新版本的 firebase-tools,请重新运行这一命令。

要初始化您的项目,请执行以下操作:

  1. 运行 firebase login,通过浏览器登录并对 Firebase 工具进行身份验证。
  2. 转到 Firebase 项目目录。
  3. 运行 firebase init functions。该工具会为您提供使用 npm 安装依赖项的选项。如果要以其他方式管理依赖项,您可以放心地拒绝。
  4. 该工具支持两种语言:

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

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

TypeScript

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
      |
      +- package.json  # npm package file describing your Cloud Functions code.
      |
      +- tsconfig.json # Config file containing compiler options.
      |
      +- tslint.json   # Optional file containing rules for TypeScript linting.
      |
      +- src/     # Directory containing TypeScript source
      |   |
      |   +- index.ts     # main source file for your Cloud Functions code
      |
      +- lib/
          |
          +- index.js     # JavaScript output from TypeScript source.
          |
          +- index.js.map # Sourcemap file for TypeScript source.

完成设置并初始化项目后,您可以打开源代码目录,并按照以下各节的说明开始添加代码。

导入所需的模块并进行初始化

对于此示例,您的项目必须使用 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 the Firebase Realtime Database.
const admin = require('firebase-admin');
admin.initializeApp();

这几行代码会加载 firebase-functionsfirebase-admin 模块,并初始化一个您可以在其中更改实时数据库的 admin 应用实例。与 FCM、身份验证、Firebase 实时数据库一样,在 Admin SDK 受支持的所有环境中,它都提供了一种使用 Cloud Functions 来集成 Firebase 的强大方法。

当您初始化项目时,Firebase CLI 会自动安装 Firebase 和 Firebase SDK for Cloud Functions 这两个 Node 模块。要将第三方库添加到项目中,您可以修改 functions/package.json,运行 npm install,然后按照平常的步骤发出请求。如需了解详情,请参阅处理依赖项

添加 addMessage() 函数

要添加 addMessage() 函数,请将下面几行代码添加到 index.js

// Take the text parameter passed to this HTTP endpoint and insert it into the
// Realtime Database under the path /messages/:pushId/original
exports.addMessage = functions.https.onRequest((req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into the Realtime Database using the Firebase Admin SDK.
  return admin.database().ref('/messages').push({original: original}).then((snapshot) => {
    // Redirect with 303 SEE OTHER to the URL of the pushed object in the Firebase console.
    return res.redirect(303, snapshot.ref.toString());
  });
});

addMessage() 函数是一个 HTTP 端点。向端点发送的任何请求都会将 ExpressJS 样式的 RequestResponse 对象传递给 onRequest() 回调函数。

HTTP 函数是同步函数,所以您应尽快发送响应,并使用实时数据库推迟工作。addMessage() HTTP 函数会向 HTTP 端点传递一个文本值,并使用前面初始化的 admin 应用将其插入到实时数据库中(路径 /messages/:pushId/original 下)。

部署和执行 addMessage()

要部署和执行 addMessage() 函数,请执行以下操作:

  1. 运行以下命令部署您的函数:

    $ firebase deploy --only functions
    

    默认情况下,Firebase CLI 会在 index.js 中同时部署所有函数。如果该文件包含大量函数,但您只需要部署其中的一部分,可使用 --only 参数进行部分部署

    $ firebase deploy --only functions:addMessage
    

    部署后,Firebase CLI 会输出任何 HTTP 函数端点的网址。在您的终端中,您应该会看到如下所示的一行代码:

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

    默认情况下,Firebase CLI 会在 functions/ 文件夹中查找源代码。您可以指定其他文件夹,只需在 firebase.json 中添加以下代码即可:

    "functions": {
      "source": "another-folder"
    }
    
  2. addMessage() 网址添加文本查询参数,并在浏览器中打开该网址:

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

    函数就会执行,并将浏览器重定向到 Firebase 控制台中存储着该文本字符串的数据库位置。您应该会看到文本值显示在控制台中。

部署和执行函数后,您可以在 Firebase 控制台中查看日志

添加 makeUppercase() 函数

要添加 makeUppercase() 函数,请将下面几行代码添加到 index.js

// Listens for new messages added to /messages/:pushId/original and creates an
// uppercase version of the message to /messages/:pushId/uppercase
exports.makeUppercase = functions.database.ref('/messages/{pushId}/original')
    .onCreate((snapshot, context) => {
      // Grab the current value of what was written to the Realtime Database.
      const original = snapshot.val();
      console.log('Uppercasing', context.params.pushId, original);
      const uppercase = original.toUpperCase();
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to the Firebase Realtime Database.
      // Setting an "uppercase" sibling in the Realtime Database returns a Promise.
      return snapshot.ref.parent.child('uppercase').set(uppercase);
    });

makeUppercase() 函数会在有数据写入实时数据库时执行。ref(path) 函数则用来定义要侦听数据库的哪个部分。考虑到性能原因,定义应尽可能具体。

大括号可用于括住“参数”(例如 {pushId}),即在回调中提供其匹配数据的通配符。

每当指定路径中有数据被写入或更新时,实时数据库都会触发 onWrite() 回调函数。

事件驱动型函数(如实时数据库事件)是异步函数。回调函数应返回 null、一个对象或一个 Promise。如果您不返回任何结果,函数就会超时,示意发生错误,然后重试。请参阅同步、异步和 Promise

部署和执行 makeUppercase()

要完成本教程,请再次部署您的函数,然后执行 addMessage() 以触发 makeUppercase()

  1. 运行以下命令部署您的函数:

    $ firebase deploy --only functions
    

    默认情况下,Firebase CLI 会在 functions/ 文件夹中查找源代码。您可以指定其他文件夹,只需在 firebase.json 中添加以下代码即可:

    "functions": {
      "source": "another-folder"
    }
    

    如果遇到访问错误(例如“无法授予项目访问权限”(Unable to authorize access to project)),请尝试检查您的项目别名

  2. 使用 CLI 输出的 addMessage() 网址,添加文本查询参数,并在浏览器中打开该网址:

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

    函数就会执行,并将浏览器重定向到 Firebase 控制台中存储着该文本字符串的数据库位置。这一写入事件触发了 makeUppercase(),后者将写入该字符串的大写形式。

部署和执行函数后,您可以在 Firebase 控制台中查看 Cloud Functions 的日志

查看完整的示例代码

下面是包含函数 addMessage()makeUppercase() 的完整的 functions/index.js。这些函数允许您向 HTTP 端点传递一个参数,端点会向实时数据库写入一个值,然后转换该值,将字符串中的所有字符改为大写。

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

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

// Take the text parameter passed to this HTTP endpoint and insert it into the
// Realtime Database under the path /messages/:pushId/original
exports.addMessage = functions.https.onRequest((req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into the Realtime Database using the Firebase Admin SDK.
  return admin.database().ref('/messages').push({original: original}).then((snapshot) => {
    // Redirect with 303 SEE OTHER to the URL of the pushed object in the Firebase console.
    return res.redirect(303, snapshot.ref.toString());
  });
});

// Listens for new messages added to /messages/:pushId/original and creates an
// uppercase version of the message to /messages/:pushId/uppercase
exports.makeUppercase = functions.database.ref('/messages/{pushId}/original')
    .onCreate((snapshot, context) => {
      // Grab the current value of what was written to the Realtime Database.
      const original = snapshot.val();
      console.log('Uppercasing', context.params.pushId, original);
      const uppercase = original.toUpperCase();
      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to the Firebase Realtime Database.
      // Setting an "uppercase" sibling in the Realtime Database returns a Promise.
      return snapshot.ref.parent.child('uppercase').set(uppercase);
    });

后续步骤

在此文档中,您可以详细了解 Cloud Functions 的一般概念,以及有关如何编写函数来处理 Cloud Functions 支持的事件类型的指南。

如需详细了解 Cloud Functions,您还可以执行以下操作:

视频教程

您可以通过观看视频教程来详细了解 Cloud Functions 的相关信息。在此视频中,您将了解有关如何开始使用 Cloud Functions(包括 Node.js 和 CLI 设置)的详细指南。

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面