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

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

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

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

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

设置 Node.js 和 Firebase CLI

您需要使用 Node.js 环境编写函数,并且需要使用 Firebase CLI(也需要 Node.js 和 npm)来将函数部署到 Cloud Functions 运行时。

Cloud Functions 可以在 Node v6 或 Node v8 上运行。如果您在 Node v6 上构建了现有的函数,则可以继续使用该版本(默认为 v6)。要了解详情,请参阅设置运行时选项

建议您使用节点版本管理器安装 Node.js 和 npm。安装 Node.js 和 npm 后,您就可以通过 npm 安装 Firebase CLI:

npm install -g firebase-tools

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

初始化 Firebase SDK for Cloud Functions

初始化 Firebase SDK for Cloud Functions 时,您将创建一个空项目(其中包含依赖项和数量极少的一些示例代码),并选择 TypeScript 或 JavaScript 来编写函数。

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

  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 模块。要将第三方库添加到项目中,您可以修改 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 函数是同步函数(类似于 Callable 函数),因此您应尽快发送响应,并使用实时数据库推迟工作。addMessage() HTTP 函数会向 HTTP 端点传递一个文本值,并使用前面初始化的 admin 应用将其插入到实时数据库中(路径 /messages/:pushId/original 下)。

部署和执行 addMessage()

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

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

    $ firebase deploy --only functions
    

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

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

    该网址包含您的项目 ID 以及 HTTP 函数的区域。虽然您现在还用不着处理,但一些生产 HTTP 函数应指定位置以尽可能缩短网络延迟。

  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
    

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

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

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

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

部署和执行函数后,您可以在 Firebase 控制台中查看 Cloud Functions 的日志。如果您需要在开发或生产环境中删除函数,请使用 Firebase CLI

查看完整的示例代码

下面是包含函数 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 设置)的详细指南。

发送以下问题的反馈:

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