前往主控台

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

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

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

我们为此示例选择了由实时数据库和 HTTP 触发的 JavaScript 函数,但您也可以选择用许多其他方式来触发函数。请参阅关于其他后台触发器(例如身份验证事件分析事件)的方法指南;或者,如果您需要 JavaScript 的类型化替代方案,请参阅使用 TypeScript 编写函数

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

创建 Firebase 项目

  1. Firebase 控制台中,点击添加项目,然后选择或输入项目名称

    如果您已有 Google Cloud Platform (GCP) 项目,则可以从下拉菜单中选择该项目,然后将 Firebase 资源添加到该项目中。

  2. (可选)如果您创建了一个新项目,可以修改项目 ID

    Firebase 会自动为您的 Firebase 项目分配一个唯一的 ID。请访问了解 Firebase 项目以详细了解 Firebase 如何使用该项目 ID。

  3. 点击继续

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

    出现提示时,选择使用现有的 Google Analytics(分析)帐号或创建一个新帐号。
    如果您选择创建一个新帐号,请选择 Analytics(分析)报告位置,然后接受项目的数据共享设置和 Google Analytics(分析)条款。

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

Firebase 会自动为您的 Firebase 项目预配资源。完成此过程后,您将进入 Firebase 控制台中 Firebase 项目的概览页面。

设置 Node.js 和 Firebase CLI

您需要使用 Node.js 环境来编写函数,并且需要使用 Firebase CLI 将函数部署到 Cloud Functions 运行时。支持 Node.js 版本 8 和版本 10。建议您使用 Node Version Manager 安装 Node.js 和 npm

安装 Node.js 和 npm 后,您就可以使用您偏好的方法安装 Firebase CLI。如需通过 npm 安装 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

初始化期间创建的 package.json 文件包含一个重要的键:"engines": {"node": "8"}。它指定了用于编写和部署函数的节点版本。您可以选择其他受支持的版本,但本教程中建议使用 Node.js 8(实际上是默认版本)。

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

完成设置任务后,您可以打开源代码目录,并按照以下各部分的说明开始添加代码。对于此示例,您的项目必须使用 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(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into the Realtime Database using the Firebase Admin SDK.
  const snapshot = await admin.database().ref('/messages').push({original: original});
  // Redirect with 303 SEE OTHER to the URL of the pushed object in the Firebase console.
  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(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into the Realtime Database using the Firebase Admin SDK.
  const snapshot = await admin.database().ref('/messages').push({original: original});
  // Redirect with 303 SEE OTHER to the URL of the pushed object in the Firebase console.
  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 设置)的详细指南。