Firebase Data Connect 使用入门

注意： 如果您想在采用 Blaze 方案的某个 Firebase 项目中添加 Data Connect，创建 Data Connect 服务，并为原型设计预配 Cloud SQL 数据库，请按照此快速入门指南操作。如果您更倾向于使用 Spark 方案，并希望使用模拟器和本地数据库在本地进行原型设计，请尝试本地开发入门。

在本快速入门中，您将学习如何使用生产 SQL 实例在应用中构建 Firebase Data Connect。

在 Firebase 控制台中，您将：

• 将 Firebase Data Connect 添加到您的 Firebase 项目。
• 在 Firebase 控制台中，使用 AI 辅助的架构生成功能为应用创建架构，然后部署该架构。
• 为应用预配 Cloud SQL 实例。
• 借助 Gemini in Firebase，使用示例数据填充数据库。
• 创建查询和突变，并借助 AI 辅助生成操作，您可以部署这些操作并使用它们在本地开发客户端代码。

然后，在本地开发环境中，您将：

• 设置开发工具，包括用于处理生产实例的 Visual Studio Code 扩展程序。
• 将本地环境与您在控制台中创建的资源同步。
• 生成强类型 SDK 并在应用中使用它们。

探索快速入门应用代码库，并按照我们的 Web Codelab、iOS Codelab 或 Android Codelab 构建功能齐全的 Data Connect 应用。

控制台流程：使用 AI 辅助功能设计架构，然后将其部署到数据库

1. 如果尚未创建，请创建一个 Firebase 项目。
   1. 在 Firebase 控制台中，点击添加项目，然后按照屏幕上的说明操作。
2. 前往 Firebase 控制台的 Data Connect 部分。
3. 点击开始使用 Gemini 按钮。
4. 在随即显示的架构生成器工作流面板中，描述应用，以便 Gemini 帮助您创建 GraphQL 架构。
5. 查看 GraphQL 架构，然后点击升级并部署。

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

   注意： 虽然您在升级到 Blaze 方案时设置了结算信息，但在试用期间，您无需为使用 Data Connect 或默认 Cloud SQL for PostgreSQL 配置付费。

7. 选择创建新的 Cloud SQL 实例。在随即显示的对话框中，为 Cloud SQL for PostgreSQL 数据库选择位置和命名。

   您的应用架构已部署，同时部署的还有与该架构对应的 PostgreSQL 数据库。

   注意：如果您想使用客户管理的加密密钥 (CMEK)，请务必选择使用现有的 Cloud SQL 实例，然后选择具有 CMEK 的现有 Cloud SQL 数据库。
   注意：预配 Cloud SQL for PostgreSQL 实例可能需要长达 15 分钟的时间。您可以使用 Google Cloud 控制台确认 Data Connect 设置流程（包括数据库预配）已完成。

控制台流程：使用 AI 辅助功能为客户创建运营

部署架构后，您可以采取第一步措施，通过创建查询和突变的连接器来部署到后端，并稍后从客户端调用，从而使客户端应用可以访问这些数据。

我们的 AI 辅助工具可随时为您提供帮助。

注意： 您必须先创建并部署架构，然后才能创建操作。

1. 出现提示时，点击使用 Gemini 生成操作按钮。

2. 片刻之后，在显示的生成操作工作流面板中，查看 Gemini 根据您的架构提供的查询和突变列表。

3. 点击每个操作行，查看定义相应操作的 GraphQL 代码。如有必要，请使用回收站控件删除不需要的操作。

4. 如需添加操作，请点击 + 添加按钮。然后：

   1. 用自然语言描述您的操作。

      例如：

      List all products
      

   2. 查看生成的 GraphQL。

   3. 如果该操作可以接受，请点击插入将其添加到您的操作列表中。

5. 继续移除和添加操作，直到您的操作集可以接受为止。

6. 如需将此操作列表部署为可供客户端调用的连接器集，请选择连接器的名称，然后点击部署。

控制台流程：使用 Gemini in Firebase 创建突变并填充数据库

完成上述步骤后，您创建了一个包含相关实体类型的 Data Connect schema，并将其部署到生产环境，这意味着系统还创建并部署了一个包含相应表的 PostgreSQL 数据库。

如需填充数据库，您可以使用 Firebase 中的 Gemini，将自然语言输入转换为 GraphQL mutation 来更新某个表，并转换为 query 来确认更新。

注意：您必须先创建并部署架构，然后才能创建操作。

提示：由于您的架构可以描述任何类型的应用，为了在本指南中学习 Data Connect，我们可以引用什么实体？您的架构可能包含 Movie（适用于影评应用）、Product（适用于电子商务应用）或 Account（适用于支付应用）等基本实体类型。在接下来的几个步骤中，请在架构中选择一种类型。

警告： 在数据编辑器中运行 mutation 会执行该 mutation，并可能会更改您的数据。

1. 打开数据标签页。

2. 点击帮我写 GraphQL pen_spark 图标，然后在随即显示的框中输入内容。

   注意： 请选择 Product 或 Account 等简单、基本的实体来填充数据。

   例如：

   Add data for three sample products to my app.
   

3. 点击生成。返回相应变异。

4. 查看输出。如有需要，请点击修改以优化提示，然后点击重新生成。

5. 接下来，点击插入，将变异插入到数据编辑器中。

6. 点击运行。

运行 mutation 时，数据会写入 PostgreSQL 数据库中的相应表。您可以在控制台中创建查询，以查看存储的数据：

1. 使用帮我写 GraphQL pen_spark 重复执行上述步骤，以创建查询。

2. 在随即显示的方框中，输入您的内容。

   例如：

   Query data for all sample products in my app.
   

3. 点击生成，然后点击运行。

本地流程：选择开发工具

现在，您已在已部署的数据库中添加了数据，并已部署连接器，接下来可以在本地开发环境中继续开发架构和连接器。

首先，您需要设置本地环境。Data Connect 为您提供了两种安装开发工具的方式。

自动安装（macOS 或 Linux） 手动安装 (Windows)

本地流程：设置开发环境

1. 为本地项目创建新目录。

2. 如需设置 Data Connect开发环境和基于浏览器的 IDE 并生成客户端 SDK，请在您创建的新目录中运行以下命令。

     curl -sL https://firebase.tools/init/dataconnect | editor=true bash

   此脚本会尝试安装。安装的 IDE 提供各种工具，包括预先捆绑的 VS Code 扩展程序，可帮助您管理架构、定义要在应用中使用的查询和变更，以及生成强类型 SDK。

   该脚本还会将您在 Firebase 控制台中创建的资源同步到本地目录，并为已注册到项目中的所有应用生成客户端 SDK。

注意：如果您已安装桌面版 VS Code，脚本会自动打开该应用。

注意：如果脚本失败，请按照手动安装步骤操作。

本地流程：设置本地项目

如需设置本地项目，请初始化项目目录。在 IDE 窗口的左侧面板中，点击 Firebase 图标以打开 Data Connect VS Code 扩展程序界面：

1. 点击启动模拟器按钮。

   注意： 在集成终端中，验证您配置的模拟器是否已启动。运行后，您应该会看到扩展程序界面更新，其中包含模拟器详细信息。

本地流程：在本地环境中查找架构和连接器

您用于将资源同步到现有项目的 macOS 或 Linux 自动安装选项具有以下效果：

• 它会同步您部署的架构
  • 找到您的架构：它位于 Firebase 项目目录的 /dataconnect/schema/schema.gql 文件中。
• 它会同步您部署的连接器中的查询和变更
  • 找到您的连接器：操作位于 Firebase 项目目录的 /dataconnect/connector/ 目录中。

注意：您的架构是您之前为 Gemini 描述并部署的应用所独有的，并且包含适合该应用的实体类型。

在本指南的其余部分，示例将重点介绍一种 Movie 类型，如果您提示 Gemini 创建电影评价应用，则可能会出现这种类型。本指南将使用 Movie 来介绍适用于任何类型的应用架构的 GraphQL 和工作流概念。

本地流程：了解您的架构

架构示例：电影

在 Data Connect 中，GraphQL 字段会映射到列。Movie 类型可能具有 id、title、imageUrl 和 genre。Data Connect 可识别原初数据类型 String 和 UUID。

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

# By default, a UUID id key will be created by default as primary key.
type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

架构示例 1：1 表：MovieMetadata

对于电影，您可以对电影元数据进行建模。

例如，在 schema.gql 中，您可以添加以下代码段，也可以查看 Gemini 生成的代码。

# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata @table {
  # This time, we omit adding a primary key because
  # you can rely on Data Connect to manage it.

  # @unique indicates a 1-1 relationship
  movie: Movie! @unique
  # movieId: UUID <- this is created by the above reference
  rating: Float
  releaseYear: Int
  description: String
}

请注意，movie 字段映射到 Movie 类型。 Data Connect 了解这是 Movie 和 MovieMetadata 之间的关系，并将为您管理这种关系。

如需详细了解 Data Connect 架构，请参阅相关文档

本地流程：向表格添加更多数据

在 IDE 编辑器面板中，您可以看到 /dataconnect/schema/schema.gql 中的 GraphQL 类型上方显示了 CodeLens 按钮。与在控制台中一样，您可以创建突变来向生产数据库添加数据。

注意： 您的架构是您向架构辅助工具描述的应用所独有的。 选择架构中的基本类型以添加数据，例如 Movie（对于电影评论应用）、Product 或 Account（对于电子商务应用）。

在本地添加数据到表：

1. 在 schema.gql 中，点击其中一种类型（例如 Movie、Product、Account，具体取决于应用的性质）的声明上方的添加数据按钮。
   
2. 系统会在您的工作目录（例如 Movie_insert.gql 或 Product_insert.gql）中添加一个新文件 <type>_insert.qgl。对相应类型的字段中的数据进行硬编码。
3. 点击运行（正式版）按钮。
   
4. 重复上述步骤，将记录添加到其他表格。

如需快速验证数据是否已添加，请执行以下操作：

1. 返回到 schema.gql，点击类型声明上方的 Read data 按钮。
2. 在生成的 <type>_read.gql 文件（例如 Product_read.gql）中，点击运行（生产）按钮以执行查询。

在文档中详细了解 Data Connect 突变

本地流程：生成 SDK

您的架构和连接器操作已在本地同步。

现在，您可以使用 VS Code 扩展程序生成客户端 SDK，开始在 iOS、Android、Web 和 Flutter 应用中实现对查询和突变的调用。

1. 在扩展程序界面中，点击向应用添加 SDK 按钮。

2. 在随即显示的对话框中，选择包含应用代码的目录。Data Connect系统会生成 SDK 代码并将其保存到该目录中。

   注意： 如果您还没有应用目录，可以先创建并选择一个新目录来存放 SDK 代码，稍后再将其与应用相关联。

3. 选择应用平台，然后注意，系统会立即在所选目录中生成 SDK 代码。

本地流程：使用 SDK 从应用中调用查询

之前，您已在 Firebase 控制台中部署了架构和操作。 如需从应用中调用操作，您可以使用 Data Connect 生成的 SDK 来实现对 ListMovies 查询的调用。

注意： 同样，以下示例包含对导入（例如 @movie-app/movies）和操作（例如 ListMovies，可能位于电影评论应用的架构中）的引用。在生成的 SDK 中，您可能会看到适用于您应用的方法，例如 ListProducts 或 ListAccounts。

您可能会发现，在我们的 Codelab 中探索具有完整功能的 Data Connect 应用的快速入门应用代码库（针对网页、iOS 或 Android）对于了解生成的 SDK 特别有用。

Web

1. 将 Firebase 添加到您的网页应用。

2. 在 React 应用的主文件中：

   • 导入生成的 SDK
   • 调用 Data Connect 方法。
   注意： 在此示例中，React 应用使用 Firebase JavaScript SDK 调用您的查询。Data Connect 还提供特殊绑定，以便在 React 中异步处理 Data Connect。

   import React from 'react';
   import ReactDOM from 'react-dom/client';
   
   // Generated queries.
   // Update as needed with the path to your generated SDK.
   import { listMovies, ListMoviesData } from '@movie-app/movies';
   
   function App() {
     const [movies, setMovies] = useState<ListMoviesData['movies']>([]);
     useEffect(() => {
       listMovies.then(res => setMovies(res.data));
     }, []);
     return (
       movies.map(movie => <h1>{movie.title}</h1>);
     );
   }
   
   const root = ReactDOM.createRoot(document.getElementById('root'));
   root.render(<App />);
   

Swift

1. 将 Firebase 添加到您的 iOS 应用。

2. 如需使用生成的 SDK，请在 Xcode 中将其配置为依赖项。

   在 Xcode 顶部导航栏中，依次选择 File > Add Package Dependencies > Add Local，然后选择包含生成的 Package.swift 的文件夹。

3. 在应用的主委托中：

   • 导入生成的 SDK
   • 调用 Data Connect 方法。

   import SwiftUI
   
   import FirebaseDataConnect
   // Generated queries.
   // Update as needed with the package name of your generated SDK.
   import <CONNECTOR-PACKAGE-NAME>
   
   let connector = DataConnect.moviesConnector
   
   struct ListMovieView: View {
   @StateObject private var queryRef = connector.listMovies.ref()
   
       var body: some View {
           VStack {
               Button {
                   Task {
                       do {
                           try await refresh()
                       } catch {
                           print("Failed to refresh: \(error)")
                       }
                   }
               } label: {
                   Text("Refresh")
               }
   
               // use the query results in a view
               ForEach(queryRef.data?.movies ?? []) { movie in
                       Text(movie.title)
                   }
               }
       }
       @MainActor
       func refresh() async throws {
           _ = try await queryRef.execute()
       }
   
       struct ContentView_Previews: PreviewProvider {
       static var previews: some View {
           ListMovieView()
       }
   }
   

Kotlin Android

1. 将 Firebase 添加到您的 Android 应用。

2. 如需使用生成的 SDK，请在 Gradle 中将 Data Connect 配置为依赖项。

   更新 app/build.gradle.kts 中的 plugins 和 dependencies。

   plugins {
     // Use whichever versions of these dependencies suit your application.
     // The versions shown here were the latest as of March 14, 2025.
     // Note, however, that the version of kotlin("plugin.serialization") must,
     // in general, match the version of kotlin("android").
     id("com.android.application") version "8.9.0"
     id("com.google.gms.google-services") version "4.4.2"
     val kotlinVersion = "2.1.10"
     kotlin("android") version kotlinVersion
     kotlin("plugin.serialization") version kotlinVersion
   }
   
   dependencies {
     // Use whichever versions of these dependencies suit your application.
     // The versions shown here were the latest versions as of March 14, 2025.
     implementation("com.google.firebase:firebase-dataconnect:16.0.0-beta04")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.1")
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3")
   
     // These dependencies are not strictly required, but will very likely be used
     // when writing modern Android applications.
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")
     implementation("androidx.appcompat:appcompat:1.7.0")
     implementation("androidx.activity:activity-ktx:1.10.1")
     implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.7")
     implementation("com.google.android.material:material:1.12.0")
   }
   

3. 在应用的主 activity 中：

   • 导入生成的 SDK
   • 调用 Data Connect 方法。

   import android.os.Bundle
   import android.widget.TextView
   import androidx.appcompat.app.AppCompatActivity
   import androidx.lifecycle.Lifecycle
   import androidx.lifecycle.lifecycleScope
   import androidx.lifecycle.repeatOnLifecycle
   import kotlinx.coroutines.launch
   
   
   private val connector = com.myapplication.MoviesConnector.instance
   
   class MainActivity : AppCompatActivity() {
   
     override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       setContentView(R.layout.activity_main)
       val textView: TextView = findViewById(R.id.text_view)
   
       lifecycleScope.launch {
         lifecycle.repeatOnLifecycle(Lifecycle.State.STARTED) {
           
           val result = connector.listMovies.runCatching { execute { } }
           
           val newTextViewText = result.fold(
             onSuccess = {
               val titles = it.data.movies.map { it.title }
               "${titles.size} movies: " + titles.joinToString(", ")
             },
             onFailure = { "ERROR: ${it.message}" }
           )
           textView.text = newTextViewText
         }
       }
     }
   }
   

Flutter

1. 将 Firebase 添加到您的 Flutter 应用。
2. 安装 flutterfire CLI dart pub global activate flutterfire_cli。
3. 运行 flutterfire configure。
4. 在应用的主函数中：
   • 导入生成的 SDK
   • 调用 Data Connect 方法。

import 'package:firebase_core/firebase_core.dart';
import 'package:flutter/material.dart';
import 'firebase_options.dart';

// Generated queries.
// Update as needed with the path to your generated SDK

import 'movies_connector/movies.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  
  
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
        home: Scaffold(
            body: Column(children: [
      ConstrainedBox(
        constraints: const BoxConstraints(maxHeight: 200),
        child: FutureBuilder(
            future: MoviesConnector.instance.listMovies().execute(),
            builder: (context, snapshot) {
              if (snapshot.connectionState == ConnectionState.done) {
                return ListView.builder(
                  scrollDirection: Axis.vertical,
                  itemBuilder: (context, index) => Card(
                      child: Text(
                    snapshot.data!.data.movies[index].title,
                  )),
                  itemCount: snapshot.data!.data.movies.length,
                );
              }
              return const CircularProgressIndicator();
            }),
      )
    ])));
  }
}

后续步骤

查看已部署的项目并探索更多工具：

• 在 Firebase 控制台中，您可以向数据库添加数据、检查和修改架构，以及监控 Data Connect 服务。

如需了解详情，请参阅相关文档。例如，由于您已完成快速入门：

• 了解更多 AI 辅助工具和指南，帮助您生成架构、查询和变更。AI 辅助功能指南介绍了如何在 IDE 中设置和使用 MCP 服务器，以及撰写提示的最佳实践。
• 详细了解架构、查询和变更开发
• 了解如何为 Web、Android、iOS 和 Flutter 生成客户端 SDK，以及如何从客户端代码调用查询和突变。