Check out the latest news from Firebase at Cloud Next 2025. Learn more.

此页面由 Cloud Translation API 翻译。

Firebase Data Connect 使用入门

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

在 Firebase 控制台中，您将：

将 Firebase Data Connect 添加到您的 Firebase 项目。
使用架构助手在 Firebase 控制台中为应用创建架构，并进行部署。
为您的应用预配 Cloud SQL 实例。
使用 Gemini Code Assist 将示例数据填充到数据库中。

然后，在本地开发环境中，您将执行以下操作：

设置开发工具（包括 Visual Studio Code 扩展程序），以便与生产实例搭配使用。
将本地环境与您在控制台中创建的资源同步。
使用扩展程序工具来帮助您实现要在应用中使用的查询。
生成强类型 SDK 并在应用中使用它们。
将最终架构、查询和数据部署到云端。

控制台流程：设计架构并将其部署到数据库

如果尚未创建，请创建一个 Firebase 项目。
1. 在 Firebase 控制台中，点击添加项目，然后按照屏幕上的说明操作。
前往 Firebase 控制台的 Data Connect 部分。
点击 Get started with Gemini（开始使用 Gemini）按钮。
在随即显示的 Schema Generator 工作流面板中，描述一个应用，以便 Gemini 帮助您创建 GraphQL 架构。
查看 GraphQL 架构，然后点击升级并部署。
将您的项目升级到 Blaze 方案。这样，您就可以创建 Cloud SQL for PostgreSQL 实例了。

注意：即使您在 Blaze 升级中设置了结算，在试用期间，您也不会因使用 Data Connect 或默认的 Cloud SQL for PostgreSQL 配置而被收费。
选择创建新的 Cloud SQL 实例。在随即显示的对话框中，为 Cloud SQL for PostgreSQL 数据库选择位置和命名方式。

系统会部署您的应用架构以及与该架构对应的 PostgreSQL 数据库。

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

控制台流程：使用 Firebase 中的 Gemini 创建更改并填充数据库

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

如需填充数据库，您可以使用 Firebase 中的 Gemini 来帮助您根据自然语言输入来定义 GraphQL 变更以更新其中一个表，以及定义查询以确认更新。

打开数据标签页。
点击帮我写 GraphQL pen_spark 图标，然后在随即显示的框中输入您的输入内容。

注意：选择一个简单的基本实体（例如 Product 或 Account）以填充数据。

例如：
```
Add data for three sample products to my app.
```
点击生成。系统会返回该更改。
查看输出。如有必要，请点击修改以优化提示，然后点击重新生成。
接下来，点击插入将更改插入数据编辑器。
点击运行。

运行更改时，系统会将数据写入 PostgreSQL 数据库中的适用表。您可以在控制台中创建查询以查看存储的数据：

重复上述步骤，使用帮我写 GraphQL pen_spark 创建查询。
在随即显示的框中，输入您的输入内容。

例如：
```
Query data for all sample products in my app.
```
依次点击生成和运行。

本地流程：选择开发工具

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

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

本地流程：设置开发环境

为您的本地项目创建一个新目录。
在您创建的新目录中运行以下命令。
```
  curl -sL https://firebase.tools/dataconnect | bash
```
此脚本会尝试为您设置开发环境并启动基于浏览器的 IDE。此 IDE 提供了一些工具（包括预捆绑的 VS Code 扩展程序），可帮助您管理架构，定义要在应用中使用的查询和更改，以及生成强类型 SDK。

注意：如果您已安装桌面版 VS Code，脚本会自动打开它。
注意：如果脚本失败，请使用手动安装步骤。

alias dataconnect='curl -sL https://firebase.tools/dataconnect | bash'

本地流程：设置项目目录

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

点击使用 Google 账号登录按钮。
点击关联 Firebase 项目按钮，然后在控制台中选择您之前创建的项目。
点击 Run firebase init 按钮，然后完成相应流程。

注意：firebase init 会将您的本地项目与在 Firebase 控制台中部署的资源同步。请务必注意，您的 GraphQL 架构将下载到您的本地项目，以便您继续开发。
点击启动模拟器按钮。

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

本地流程：在本地环境中查找架构

上一部分中的 firebase init 步骤会将您从控制台部署的架构同步到本地开发环境。

找到您的架构：它位于 Firebase 项目目录中的 /dataconnect/schema/schema.gql 文件中。

本地流程：使用架构

架构示例：电影

在 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 编辑器面板中，您会看到 CodeLens 按钮显示在 /dataconnect/schema/schema.gql 中的 GraphQL 类型上方。就像在控制台中一样，您可以创建一个更改，以将数据添加到生产数据库。

在本地工作时，如需向表中添加数据，请执行以下操作：

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

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

返回 schema.gql，点击类型声明上方的读取数据按钮。
在生成的 <type>_read.gql 文件（如 Product_read.gql）中，点击 Run (Production) 按钮以执行查询。

参阅文档详细了解 Data Connect 更改

本地流程：定义查询

现在进入有趣的部分，查询。作为开发者，您可能习惯编写 SQL 查询，而不是 GraphQL 查询，因此这在开始时可能会感觉有些不同。不过，与原始 SQL 相比，GraphQL 要简洁得多，并且具有类型安全性。我们的 VS Code 扩展程序可简化开发体验。

如需实现查询，您可以改用 CodeLens 生成的查询：

在 /dataconnect/schema/schema.gql 中，点击某个类型（Movie、Product、Account 等）上方的 Read data CodeLens 按钮。
在生成的 <type>_read.gql 文件中，点击 Run (Production) 按钮测试查询。
将正常运行的查询复制到 /dataconnect/connector/queries.gql。
如需使此查询可部署，请为其声明一个唯一名称。

例如，在以下通用示例中，query_name 可能是 ListMovies、ListProducts 或 ListAccounts。

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

# @auth() directives control who can call each operation.
query <query_name> @auth(level: PUBLIC) {
   <table_name> {
     <field_1>
     <field_2>
     <field_3>
  }
}

使用附近的 CodeLens 按钮执行查询。

参阅文档，详细了解 Data Connect 查询

本地流程：生成 SDK

点击将 SDK 添加到应用按钮。
在随即显示的对话框中，选择包含应用代码的目录。Data Connect SDK 代码将生成并保存到该目录中。

注意：如果您还没有应用目录，可以先为 SDK 代码创建并选择一个新目录，稍后再将其关联到您的应用。
选择您的应用平台，然后请注意，SDK 代码会立即在您选择的目录中生成。

本地流程：将架构和查询部署到生产环境

您已完成开发迭代。现在，您可以使用 Firebase Extensions 界面或 Firebase CLI 将架构和查询部署到服务器，就像部署架构一样。

在 IDE 窗口的 VS Code 扩展程序界面中，点击部署到生产环境按钮。

部署完成后，请前往 Firebase 控制台，验证架构更新（如果适用）和操作是否已上传到云端。您应该能够在控制台中查看架构并运行操作。Cloud SQL for PostgreSQL 实例将更新为最终部署的生成架构和数据。

在文档中详细了解如何使用 Data Connect 模拟器

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

现在，更新后的架构（如果适用）和查询已部署到生产环境，您可以使用 Data Connect 生成的 SDK 实现对 ListMovies 查询的调用。

Web Swift Kotlin Android Flutter

将 Firebase 添加到您的Web 应用。

在 React 应用的主文件中：

导入生成的 SDK
调用 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 />);

将 Firebase 添加到您的 iOS 应用。
如需使用生成的 SDK，请在 Xcode 中将其配置为依赖项。

在 Xcode 顶部导航栏中，依次选择 File（文件）> Add Package Dependencies（添加软件包依赖项）> Add Local（添加本地内容），然后选择包含生成的 Package.swift 的文件夹。

在应用的主要委托中：

导入生成的 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()
    }
}

将 Firebase 添加到您的 Android 应用。

如需使用生成的 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")
}

在应用的主 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
      }
    }
  }
}

将 Firebase 添加到您的 Flutter 应用。
安装 flutterfire CLI dart pub global activate flutterfire_cli。
运行 flutterfire configure。
在应用的 main 函数中：
- 导入生成的 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 服务。

如需了解详情，请参阅相关文档。例如，既然您已完成快速入门，请执行以下操作：

详细了解架构、查询和更改开发
了解如何为 Web、Android、iOS 和 Flutter 生成客户端 SDK，以及如何从客户端代码调用查询和更改。