開始使用 Firebase Data Connect

在本快速入門課程中，您將瞭解如何使用正式版 SQL 執行個體，在應用程式中建構 Firebase Data Connect。

在 Firebase 控制台中，您可以執行下列操作：

  • 將 Firebase Data Connect 新增至 Firebase 專案。
  • 使用結構定義輔助工具，在 Firebase 主控台為應用程式建立結構定義並部署。
  • 為應用程式配置 Cloud SQL 執行個體。
  • 使用 Gemini Code Assist，將範例資料填入資料庫。

接著，在本機開發環境中，您將執行下列操作：

  • 設定開發工具，包括 Visual Studio Code 擴充功能，以便與正式版執行個體搭配運作。
  • 將本機環境與控制台中建立的素材資源同步。
  • 使用擴充功能工具，協助您在應用程式中實作查詢。
  • 產生強型別 SDK，並在應用程式中使用。
  • 將最終結構定義、查詢和資料部署到雲端。

控制台流程：設計結構定義並部署至資料庫

  1. 如果您尚未建立 Firebase 專案，請先建立。
    1. 在 Firebase 控制台中，按一下「新增專案」，然後按照畫面上的指示操作。
  2. 前往 Firebase 控制台的「Data Connect」部分。
  3. 按一下「開始使用 Gemini」按鈕。
  4. 在隨即顯示的「結構定義產生器」工作流程面板中，說明應用程式，Gemini 就能協助您建立 GraphQL 結構定義。
  5. 查看 GraphQL 結構定義，然後按一下「升級並部署」。

  6. 將專案升級至 Blaze 方案。這樣一來，您就能建立 PostgreSQL 適用的 Cloud SQL 執行個體。

  7. 選取「建立新的 Cloud SQL」執行個體。在隨即顯示的對話方塊中，選取 PostgreSQL 適用的 Cloud SQL 資料庫位置和名稱。

    應用程式結構定義會部署，並與該結構定義相對應的 PostgreSQL 資料庫。

控制台流程：在 Firebase 中使用 Gemini 建立 mutation 並填入資料庫

完成前一個步驟後，您已建立包含相關實體類型的 Data Connect 結構定義，並將其部署至實際工作環境，也就是說，您也已建立並部署了含有相應資料表的 PostgreSQL 資料庫。

如要填入資料庫，您可以在 Firebase 中使用 Gemini，藉由自然語言輸入內容定義 GraphQL 異動，以便更新其中一個資料表，並使用查詢確認更新。

  1. 開啟「資料」分頁。

  2. 按一下「幫我寫 GraphQL」pen_spark圖示，然後在隨即顯示的方塊中輸入內容。

    例如：

    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. 依序按一下「Generate」和「Run」。

本機流程：選擇開發工具

在已部署的資料庫中擁有資料後，您可以繼續在本機開發環境中開發結構定義和連接器。

首先，您需要設定本機環境。Data Connect 提供兩種安裝開發工具的方式。

本機流程：設定開發環境

  1. 為本機專案建立新目錄。

  2. 請在您建立的新目錄中執行下列指令。

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

    這個指令碼會嘗試為您設定開發環境，並啟動瀏覽器式 IDE。這個 IDE 提供工具，包括預先內含的 VS Code 擴充功能，可協助您管理結構定義，並定義應用程式要使用的查詢和變異，以及產生強型別 SDK。

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

本機流程：設定專案目錄

如要設定本機專案，請初始化專案目錄。在 IDE 視窗的左側面板中，按一下 Firebase 圖示，開啟 Data Connect VS Code 擴充功能 UI：

  1. 點選「使用 Google 帳戶登入」按鈕。
  2. 按一下「連結 Firebase 專案」按鈕，然後選取先前在控制台中建立的專案。

  3. 按一下「Run firebase init」按鈕，完成流程。

  4. 按一下「Start emulators」按鈕。

本機流程：在本機環境中尋找結構定義

上一節的 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 類型上。就像在控制台中一樣，您可以建立變異操作，將資料新增至正式版資料庫。

在本機工作時，如要將資料新增至資料表，請按照下列步驟操作：

  1. 在 schema.gql 中，按一下所宣告類型 (例如 Movie、Product、Account，視應用程式性質而定) 上方的「Add data」按鈕。
    Firebase Data Connect 的 Code Lens「Add data」按鈕
  2. 系統會將新檔案 <type>_insert.qgl 新增至工作目錄 (例如 Movie_insert.gql 或 Product_insert.gql)。在該類型的欄位中硬式編碼資料。
  3. 按一下「Run (Production)」按鈕。
    Firebase Data Connect 的 Code Lens 執行按鈕
  4. 重複上述步驟，將記錄新增至其他資料表。

如要快速驗證資料是否已新增，請按照下列步驟操作：

  1. 回到 schema.gql，按一下型別宣告上方的「Read data」按鈕。
  2. 在產生的 <type>_read.gql 檔案 (例如 Product_read.gql) 中，按一下「Run (Production)」按鈕執行查詢。

進一步瞭解說明文件中的 Data Connect 變異體

本機流程：定義查詢

接下來是查詢的部分。開發人員通常會編寫 SQL 查詢，而非 GraphQL 查詢，因此一開始可能會覺得有點不同。不過，GraphQL 比原始 SQL 更精簡，且具有類型安全性。我們的 VS Code 擴充功能可讓開發體驗更輕鬆。

如要實作查詢，您可以調整 CodeLens 產生的查詢：

  1. 在 /dataconnect/schema/schema.gql 中，按一下類型 (Movie、Product、Account 等) 上方的 Read data CodeLens 按鈕。
  2. 在產生的 <type>_read.gql 檔案中，按一下「Run (Production)」按鈕來測試查詢。
  3. 將正常運作的查詢複製到 /dataconnect/connector/queries.gql。

  4. 如要讓這項查詢可供部署，請宣告其專屬名稱。

    例如，在下列一般範例中，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

  1. 按一下「Add SDK to app」按鈕。

  2. 在隨即顯示的對話方塊中，選取包含應用程式程式碼的目錄。系統會產生 Data Connect SDK 程式碼並儲存在該目錄中。

  3. 選取應用程式平台後，SDK 程式碼會立即在所選目錄中產生。

本機流程：將結構定義和查詢部署至實際工作環境

您已完成一個開發迭代。您現在可以使用 Firebase 擴充功能 UI 或 Firebase CLI 將結構定義和查詢部署至伺服器，就像為結構定義執行這項操作一樣。

在 IDE 視窗的 VS Code 擴充功能 UI 中，按一下「Deploy to production」按鈕。

部署完成後，請前往 Firebase 控制台，確認結構定義更新 (如適用) 和作業已上傳至雲端。您應該可以查看結構定義，並在控制台中執行作業。系統會更新 PostgreSQL 適用的 Cloud SQL 執行個體，並使用最終部署產生的結構定義和資料。

進一步瞭解如何在說明文件中使用 Data Connect Emulator

本機流程：使用 SDK 從應用程式呼叫查詢

更新的結構定義 (如適用) 和查詢已部署至實際環境，您可以使用 Data Connect 產生的 SDK 對 ListMovies 查詢執行呼叫。

網頁版 Swift Kotlin Android Flutter
  1. 將 Firebase 新增至網頁應用程式。

  2. 在 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 />);
  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()
    }
}
  1. 將 Firebase 新增至 Android 應用程式。

  2. 如要使用產生的 SDK，請將 Data Connect 設為 Gradle 中的依附元件。

    更新 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. 在應用程式的主活動中：

    • 匯入您產生的 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
      }
    }
  }
}
  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 服務。

如需更多資訊，請參閱說明文件。舉例來說，您已完成快速入門導覽課程：