開始使用 Firebase Data Connect

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

Firebase 控制台中,您可以執行下列操作:

  • Firebase Data Connect 新增至 Firebase 專案。
  • Firebase 控制台中為應用程式建立結構定義 (使用 AI 輔助產生結構定義),然後部署。
  • 為應用程式配置 Cloud SQL 執行個體。
  • Firebase 中使用 Gemini,並使用示例資料填入資料庫。
  • 使用 AI 輔助的作業產生功能建立查詢和異動,您可以將這些作業部署並用於本機開發用戶端程式碼。

接著,您可以在本機開發環境中執行下列操作:

  • 設定開發工具,包括 Visual Studio Code 擴充功能,以便與正式版執行個體搭配運作。
  • 將本機環境與您在控制台中建立的素材資源同步。
  • 產生強型別 SDK,並在應用程式中使用。

控制台流程:使用 AI 輔助功能設計結構定義,然後部署至資料庫

  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 資料庫。

控制台工作流程:使用 AI 協助功能為客戶建立作業

架構圖部署完成後,您可以採取第一步驟,讓用戶端應用程式可存取這類資料,方法是建立用於部署至後端的查詢和變異的連接器,並稍後從用戶端呼叫。

我們的 AI 輔助工具可提供協助。

  1. 出現提示時,請按一下「透過 Gemini 生成作業」按鈕。

  2. 幾分鐘後,在「Generate your operations」工作流程面板中,查看 Gemini 根據您的結構定義提供的查詢和異動清單。

  3. 按一下每個作業列,即可查看定義該作業的 GraphQL 程式碼。如有需要,請使用垃圾桶控制項刪除不需要的作業。

  4. 如要新增運算,請按一下「+ 新增」按鈕。接著:

    1. 以自然語言描述作業。

      例如:

      List all products
      
    2. 查看系統產生的 GraphQL。

    3. 如果可接受該操作,請按一下「插入」,將該操作加入操作清單。

  5. 繼續移除及新增作業,直到作業集合符合要求為止。

  6. 如要將這份作業清單部署為可供用戶端呼叫的連接器組合,請選擇連接器名稱,然後按一下「部署」

控制台流程:在 Firebase 中使用 Gemini 建立變異,並填入資料庫

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

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

  1. 開啟「資料」分頁。

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

    例如:

    Add data for three sample products to my app.
    
  3. 點選「產生」,系統會傳回變異。

  4. 查看輸出內容。如有需要,請按一下「編輯」來調整提示,然後點選「重新產生」

  5. 接著,按一下「插入」,將變異式插入資料編輯器。

  6. 按一下「執行」

執行變異時,系統會將資料寫入 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 檔案中。
  • 這項工具會同步處理您部署的連接器中的查詢和變異體
    • 尋找連接器:這些作業位於 Firebase 專案目錄中的 /dataconnect/connector/ 目錄中。

本機流程:瞭解結構定義

結構定義範例:電影

Data Connect 中,GraphQL 欄位會對應至資料欄。Movie 類型可能會有 idtitleimageUrlgenreData Connect 可辨識原始資料類型 StringUUID

# 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 瞭解這是 MovieMovieMetadata 之間的關係,並會為您管理這項關係。

進一步瞭解說明文件中的 Data Connect 結構定義

本機流程:在表格中新增更多資料

在 IDE 編輯器面板中,您會看到 CodeLens 按鈕會顯示在 /dataconnect/schema/schema.gql 中的 GraphQL 類型上。就像在控制台中一樣,您可以建立變異操作,將資料新增至正式版資料庫。

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

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

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

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

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

本機流程:產生 SDK

結構定義和連接器作業會在本機同步處理。您現在可以使用本機工具產生用戶端 SDK,開始在 iOS、Android、網頁和 Flutter 應用程式中實作對查詢和突變的呼叫。

  1. 按一下「Add SDK to app」按鈕。
  2. 在隨即顯示的對話方塊中,選取包含應用程式程式碼的目錄。系統會產生 Data Connect SDK 程式碼並儲存在該目錄中。

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

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

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

網頁版

  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 />);
    

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,請將 Data Connect 設為 Gradle 中的依附元件。

    更新 app/build.gradle.kts 中的 pluginsdependencies

    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
          }
        }
      }
    }
    

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 服務。

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