Firebase Data Connect 使用入门

提示 ：加入 Firebase Data Connect 专用预览版计划，详细了解 Firebase 的第一个 SQL 解决方案。您将有机会成为此产品的尝鲜者，并第一时间了解 Firebase 在打造现代化应用开发体验方面所做的全新工作。请在 Firebase Data Connect 产品页面进行注册。

预览版 ：Firebase Data Connect 目前处于非公开预览版阶段，这意味着该产品不在任何服务等级协议 (SLA) 或弃用政策的涵盖范围内，并且可能会以不向后兼容的方式更改。在非公开预览版期间，Data Connect 及其文档将进行更新和改进。非公开预览版产品不得在正式版应用中使用。

注意 ：如需访问 Firebase Data Connect 服务以及本指南中提及的大多数工具和来源，您需要注册非公开预览版计划。

在本快速入门中，您将学习如何完成以下操作：

• 将 Firebase Data Connect 添加到您的 Firebase 项目。
• 设置包含 Visual Studio Code 扩展程序的开发环境，以便使用生产实例。
• 然后，我们将介绍如何执行以下操作：
  • 使用电子邮件应用示例创建架构。
  • 为架构定义查询和变更。
  • 使用自动生成的 SDK 从客户端调用这些查询和变更。
  • 将最终原型部署到生产环境中。

前提条件

要使用本快速入门，您需要具备以下各项。

• Linux、macOS 或 Windows
• Visual Studio Code

将 Data Connect 添加到您的项目并创建数据源

1. 如果您还没有 Firebase 项目，请创建一个。
   1. 在 Firebase 控制台中，点击添加项目，然后按照屏幕上的说明操作。

2. 将您的项目升级到 Blaze 方案。这样，您就可以创建一个 Cloud SQL for PostgreSQL 实例。

   注意 ：虽然您在 Blaze 升级中设置了结算信息，但在预览版期间，您无需为 Data Connect 或默认 Cloud SQL for PostgreSQL 配置的使用付费。

3. 前往 Firebase 控制台的 Data Connect 部分，然后按照产品设置工作流操作。

4. 为您的 CloudSQL for PostgreSQL 数据库选择一个位置。

5. 请记下项目、服务和数据库的名称及 ID，以便稍后确认。

6. 按照其余设置流程操作，然后点击完成。

   注意 ：完成 Cloud SQL for PostgreSQL 实例的预配最多可能需要 20 分钟。

选择并设置开发环境

首先，您需要在 Visual Studio Code 中对应用进行原型设计，以开始使用 Data Connect。

（可选）您可以使用 Data Connect 模拟器安装本地 PostgreSQL 数据库，以进行本地开发。此设置将在本快速入门指南的末尾介绍。

Data Connect 支持两种原型设计开发体验：

• 如果您是 Web 或 Kotlin Android 开发者，可以在连接到 Cloud SQL for PostgreSQL 实例时在本地对架构和操作进行原型设计，或（可选）在本地运行 PostgreSQL。

• 如果您是 Web 开发者，则可以使用 IDX，使用包含 PostgreSQL 的预配置 IDX 模板、搭配 Data Connect 模拟器的 VS Code 扩展程序以及为您设置快速入门代码，在 IDX 工作区中进行原型设计。

VS Code 开发

如果您喜欢在本地进行开发，而不是使用 IDX，请设置 Firebase VS Code 扩展程序，以便通过 SDK 生成（适用于 Web、Kotlin Android 和即将推出的 iOS）快速迭代开发。

1. 为本地项目创建一个新目录。
2. 在新目录中打开 VS Code。
3. 从 Firebase 存储下载扩展程序（打包为 VSIX 软件包）。
4. 在 VS Code 中，从 View 菜单中选择 Extensions。
5. 在“Extensions”面板标题栏中，点击菜单图标 more_horiz，然后按照从 VSIX... 安装。

注意 ：该扩展程序包含 Marketplace GraphQL 语法突出显示扩展程序。您安装的其他 GraphQL 扩展程序可能会与 VSIX 文件中捆绑的 GraphQL 支持冲突。

IDX 开发

IDX 是一种针对 Web 应用开发进行了优化的环境。如果您是 Kotlin Android 开发者，请按照 VS Code 开发标签页上的步骤操作。

如需设置 Data Connect IDX 模板，请执行以下操作：

1. 您可以通过 Project IDX 网站访问该模板。
2. 按照设置流程操作。

设置您的本地项目

注意 ：如果您未使用 IDX，请按照本部分中的步骤操作。

按照常规说明安装 CLI。

然后，启用 Firebase Data Connect 实验。

firebase experiments:enable dataconnect

注意： 如果您使用的是现有 CLI 安装，请务必更新到最新版本。

为了设置您的本地项目，我们将初始化您的项目目录，并更新生成代码所需的一些配置文件。

设置项目目录

初始化您的项目目录。

Firebase Extensions 设置

在 VS Code 左侧面板中，点击 Firebase 图标以打开 Firebase VS Code 扩展程序界面。

在 Firebase Extensions 界面中：

1. 确保您已登录。
2. 在 Firebase 控制台中，确认 Data Connect 设置流程（包括数据库预配）已完成。
3. 点击 Run firebase init 按钮。
4. 查看 VS Code 下方面板中的终端标签页，看看有没有提示。
5. 选择 Data Connect 作为在此目录中使用的功能。
6. 出现提示时，提供您之前在控制台中创建的 Data Connect 项目的项目、服务和数据库 ID。

终端设置

1. 如有必要，请使用 firebase login 登录。
2. 在 Firebase 控制台中，确认 Data Connect 设置流程（包括数据库预配）已完成。
3. 运行 firebase init，按照屏幕上的提示将目录初始化为 Firebase 项目。
4. 选择 Data Connect 作为在此目录中使用的功能。
5. 出现提示时，提供您之前在控制台中创建的 Data Connect 项目的项目、服务和数据库 ID。

这两种流程都会创建 firebase.json 和 .firebaserc 文件，以及 dataconnect 子目录（其中包含本地工作目录中的重要 dataconnect.yaml 和 connector.yaml 文件）。

配置 SDK 代码的生成位置

在您修改架构时，Data Connect 会自动生成 SDK 代码。

如需指定 SDK 的生成位置，请在 dataconnect/connector/connector.yaml 中更新初始连接器的文件。

注意：IDX 中已提供示例 connector.yaml。

connectorId: "my-connector"
authMode: "PUBLIC"
generate:
  javascriptSdk:
    outputDir: "../../js-email-generated"
    package: "@email-manager/emails"
    packageJsonDir: "../../"
  kotlinSdk:
    outputDir: "../kotlin-email-generated"
    package: com.myemailapplication

注意：对于 Web SDK，由于 Data Connect 使用 npm link 安装您的 SDK，因此生成的 SDK 需要输出到与 node_modules 路径相同的目录或可以访问 node_modules 的子目录中。

熟悉 Data Connect 工具包

Data Connect Toolkit 是 Firebase VS Code 扩展程序的一个组件，可直接从 Visual Studio Code 中进行架构开发以及查询和突变管理。

如需了解工具包的功能，请执行以下操作：

1. 在 VS Code 中打开 Firebase 项目目录（如果尚未打开）。
2. 在 VS Code 的左侧面板中，点击 Firebase 图标以打开 Firebase VS Code 扩展程序界面。

请注意，在整个开发工作过程中，您可以通过工具包与本地环境以及生产资源进行交互。在本快速入门中，您将与生产环境进行交互。

该扩展程序界面为您提供了一些实用功能：

在 VS Code 主侧边栏中：

主侧边栏

• 配置面板：可让您登录 Google 并选择 Firebase 项目。
• Firebase Data Connect 面板：可让您控制内置的模拟器并将资源部署到生产环境中。
• FDC Explorer 面板，其中列出了根据您的架构自动生成的隐式查询和变更

在 VS Code 下方面板中：

下面板

• Data Connect Execution 标签页，其中包含的工具可让您通过请求传递数据、模拟身份验证以及查看结果。

在开始开发应用之前，请先了解该扩展程序的一些功能。

试用自定义 CodeLen	当您处理 schema.gql、queries.gql 和 mutations.gql 文件中的资源时，在编写完语法的代码块后，自定义 CodeLens 会显示您可以对声明的表和操作执行的操作。 对于表，CodeLens 可帮助您生成变更以将数据添加到后端数据库。 对于查询和变更，CodeLens 允许您在本地或针对生产资源运行操作。
设置请求的身份验证级别	在下部面板中，Data Connect 执行面板提供了一个“配置”标签页，您可以在其中选择用于操作的模拟身份验证级别。
在查询和变更中填充变量	在同一个“配置”标签页中，您可以填充操作载荷。
检查历史记录、回答和错误	此外，在“配置”标签页中，您还可以查看“历史记录”和“结果”标签页，了解调试信息。

创建 Data Connect 架构和查询

您的设置已完成。现在，我们可以开始使用 Data Connect 进行开发了。

开始使用 GraphQL 对用户和电子邮件建模。您将在以下国家/地区更新来源：

• /dataconnect/schema/schema.gql
• /dataconnect/connector/queries.gql

开始开发架构

在您的 Firebase 项目目录中，记下 dataconnect 文件夹。您可以在此处使用 GraphQL 为 Cloud SQL 数据库定义数据模型。

在 /dataconnect/schema/schema.gql 文件中，开始定义包含用户和电子邮件地址的架构。

用户

在 Data Connect 中，GraphQL 字段映射到列。用户有 uid、name 和电子邮件地址 address。Data Connect 可识别多种原始数据类型：String 和 Date。

复制以下代码段或取消注释文件中相应的行。

# File `/dataconnect/schema/schema.gql`

type User @table(key: "uid") {
   uid: String!
   name: String!
   address: String!
}

默认情况下，如果未提供 UUID id 键，Firebase Data Connect 会添加该键。不过，在这种情况下，您希望将 uid 设为主键，您可以通过 @table(key: "uid") 指令执行此操作。

电子邮件

现在，您已经有了用户，接下来可以对电子邮件进行建模了。您可以在此处添加电子邮件地址数据的典型字段（或列）。这一次，我们省略了添加主键这一步骤，因为您可以依靠 Data Connect 来管理它。

# File `/dataconnect/schema/schema.gql`

type Email @table {
   subject: String!
   date: Date!
   text: String!
   from: User!
}

请注意，from 字段会映射到 User 类型。Data Connect 了解这是 Email 和 User 之间的关系，将为您管理这种关系。

将架构部署到生产环境

由于您要使用 Firebase VS Code 扩展程序来处理生产数据库，因此需要先部署架构，然后才能继续操作。

注意 ：预配 Cloud SQL for PostgreSQL 实例最多可能需要 20 分钟。在实例准备就绪之前，您无法部署。

1. 您可以使用 Firebase VS Code 扩展程序进行部署。
   • 在扩展程序界面中的 Firebase Data Connect 面板下，点击部署。

2. 或者，您也可以使用 Firebase CLI。

   firebase deploy
   

3. 在扩展程序或 CLI 流程中，您可能需要审核架构更改并批准可能具有破坏性的修改。系统会提示您执行以下操作：

   • 使用 firebase dataconnect:sql:diff 查看架构更改
   • 如果您对更改感到满意，请使用由 firebase dataconnect:sql:migrate 启动的流程应用这些更改。

查看生成的架构扩展项

在您修改电子邮件架构时，Data Connect 会自动生成架构扩展、查询、变更、过滤器和表关系。您可以通过两种方式查看此生成的代码。

• 您可以在 Firebase Extensions 界面的 FDC Explorer 面板下查看生成的隐式查询和变更的列表。
• 您可以在 .dataconnect/schema 目录下的源代码中查看所有本地生成的代码。

执行变更以将数据添加到表中

您可以看到 CodeLens 按钮会显示在 /dataconnect/schema/schema.gql 中的 GraphQL 类型上方。

开发时查询和变更

在本例中，与这些 CodeLens 按钮关联的操作是快速而实用的操作，用于向表格中添加数据。Data Connect 使用 GraphQL 变更来描述如何以及谁可以对数据库执行操作。使用此按钮可创建开发时操作，用于快速播种数据。

将架构部署到生产环境后，您可以使用运行（生产环境）CodeLens 按钮在后端执行这些操作。

注意 ：对于 Web 开发者，IDX 模板包含为每个表提供的大量种子数据。您可以点击并逐个添加，也可以将它们合并到一项更改中。

编写查询以列出电子邮件地址

现在，查询是最有趣的部分。作为开发者，您习惯于编写 SQL 查询而不是 GraphQL 查询，因此在开始阶段可能会有一些不同。不过，GraphQL 比原始 SQL 更简洁且类型安全。我们的 VS Code 扩展程序 简化了开发体验

开始修改 /dataconnect/connector/queries.gql 文件。如果您想获取所有电子邮件，请使用如下查询。

# File `/dataconnect/connector/queries.gql`

query listEmails @auth(level: PUBLIC) {
  emails {
    id, subject, text, date
    from {
      name
    }
  }
}

这里非常令人兴奋的功能是，我们能够像图表一样处理数据库关系。由于电子邮件地址的 from 字段引用了用户，因此您可以嵌套到该字段中，获取有关用户的信息。

@auth 指令

在此示例中，@auth 指令并未发挥其最大潜力，但其概念却非常强大。通过这种方式，您可以决定针对数据库的操作的授权政策。

此查询相当简单，当您执行具有多对多关系的更复杂的联接时，Data Connect 真正令人兴奋的功能开始显现。在浏览各种工具和文档时，您会详细了解相关信息。

测试您的查询

现在我们已经创建了此查询，在将其集成到客户端代码中之前，请先检查它能否正常运行。对于开发者而言，使用 Data Connect 时所体验的一项重要功能是使用 Data Connect 执行面板快速迭代和测试查询结果。

您可以提供此查询所需的参数，然后点击查询名称上方的 CodeLens 按钮。这将执行查询并显示结果，这样您就可以看到它正在按预期工作。

生成客户端 SDK 代码并从客户端应用查询数据

为了结束开发周期，请将此查询集成到客户端代码中。

您可以编写一个客户端来演示如何调用查询以及处理 Data Connect 服务的回复。

注意 ：如果您使用的是我们的 IDX 模板，您将有可用的来源，包括框架 Web 应用框架代码。

1. 在 connector.yaml 文件中之前指定的位置找到自动生成的源代码。

2. 将 Firebase 添加到您的项目中，注册您的应用并安装相关的 Firebase 核心 SDK：

   • 对于 JavaScript，请按照这些说明操作。
   • 对于 Kotlin，请按照这些说明操作。

3. 如果您未使用 IDX，则可以设置一个可从命令行调用的客户端。

JavaScript

创建源文件 clientTest.js，然后复制以下代码。

const { initializeApp } = require("firebase/app");
const {
  connectDataConnectEmulator,
  getDataConnect,
} = require("firebase/data-connect");
const { listEmails, connectorConfig } = require("@email-manager/emails");

// TODO: Replace the following with your app's Firebase project configuration
const firebaseConfig = {
  //...
};

initializeApp(firebaseConfig);

// Remove the following line to connect directly to production
connectDataConnectEmulator(
  getDataConnect(connectorConfig),
  "localhost",
  9399
);

listEmails().then(res => {
  console.log(res.data.emails);
  process.exit(0);
});
    

然后，您可以运行客户端

    node clientTest.js
    

Kotlin Android

创建源文件 clientTest.kt，然后复制以下代码。

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    lifecycleScope.launch {
      val connector = MyConnector.instance
      connector.dataConnect.useEmulator() // Remove to connect to production
      try {
        println(connector.listEmails.execute().data.emails)
      } catch (e: Throwable) {
        println("ERROR: $e")
      }
    }
  }
}
    

然后：

1. 运行 activity。
2. 检查 Android 的 logcat 输出。

将已完成的原型部署到生产环境中

您已经完成了一次开发迭代。现在，您可以使用 Firebase 扩展程序界面或 Firebase CLI 将架构、数据、查询和变更部署到服务器，就像使用架构一样。

部署后，您的 Data Connect 服务就可以处理来自客户端的操作了。Cloud SQL for PostgreSQL 实例将使用其最终部署的生成架构和数据进行更新。

（可选）在本地安装 PostgreSQL

通过在本地安装 PostgreSQL 并将其与模拟器集成，您可以在完全本地的开发环境中设计原型。

您可以安装新的 PostgreSQL 实例或使用现有实例。

安装 PostgreSQL

按照适用于您的平台的说明安装 PostgreSQL 15.x 版。

注意 ：请务必记下用户名和密码，以备将来访问。

• macOS。下载并安装 Postgres.app。
• Windows：使用 PostgreSQL 下载页面中的 EDB 安装程序。
• Docker：拉取并运行 pgvector/pgvector:15 映像，该映像同时支持 PostgreSQL 15.x 和矢量。
• Linux：我们建议将 Docker 与上述映像搭配使用，但您也可以按照热门发行版的替代说明进行操作。

记下安装过程中的主机名、端口、用户名和密码以及相关参数输出。

如需连接到 PostgreSQL 实例，模拟器需要具备以下条件：

• 这些设置配置参数
• dataconnect.yaml 中的数据库名称和在本地实例中初始化的具有相应名称的数据库。

使用连接字符串更新 .firebaserc

使用本地 PostgreSQL 配置详细信息（包括本地 PostgreSQL 用户名和密码）将连接字符串添加到 .firebaserc 文件中的以下键。

{
  "projects": {},
  ...,
  ...,
  "dataconnectEmulatorConfig": {
    "postgres": {
      "localConnectionString": "postgresql://postgresusername:postgrespassword@localhost:5432?sslmode=disable"
    }}
}

连接到本地 PostgreSQL 实例

完成此配置后，如需连接到您的本地数据库，请执行以下操作：

1. 在 VS Code 的左侧面板中，点击 Firebase 图标以打开 Firebase VS Code 扩展程序界面。
2. 点击连接到本地 PostgreSQL 按钮。

后续步骤

提示： 本演示您是否有兴趣参与非公开预览版计划？如果是这样，请在 Firebase Data Connect 产品页面进行注册。