開始使用 Firebase Data Connect

注意： 如要將 Data Connect 新增至採用 Blaze 方案的 Firebase 專案，請按照這份快速入門指南操作，建立 Data Connect 服務，並為原型設計佈建 Cloud SQL 資料庫。如果您想使用 Spark 方案，並透過模擬器和本機資料庫在本機製作原型，請參閱本機開發入門指南。

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

在 Firebase 控制台中，您將：

• 將 Firebase Data Connect 新增至 Firebase 專案。
• 在 Firebase 控制台中，使用 AI 輔助產生結構定義功能，為應用程式建立結構定義，然後部署。
• 為應用程式佈建 Cloud SQL 執行個體。
• 使用 Gemini 版 Firebase，在資料庫中填入範例資料。
• 建立查詢和異動，並透過 AI 輔助生成作業，然後部署及使用這些作業，在本機開發用戶端程式碼。

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

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

探索快速入門應用程式存放區，並按照網頁版、iOS 版或 Android 版程式碼研究室的說明，建構功能齊全的 Data Connect 應用程式。

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

1. 建立 Firebase 專案 (如果沒有的話)。
   1. 在 Firebase 控制台中，按一下「新增專案」，然後按照畫面上的指示操作。
2. 前往 Firebase 控制台的「Data Connect」部分。
3. 按一下「開始使用 Gemini」按鈕。
4. 在顯示的「結構定義產生器」工作流程面板中，描述應用程式，以便與您一起建立 GraphQL 結構定義。Gemini
5. 檢查 GraphQL 結構定義，然後按一下「升級並部署」。

6. 將專案升級至 Blaze 方案。您可以使用這個選項建立 PostgreSQL 適用的 Cloud SQL 執行個體。

   注意： 雖然您在升級至 Blaze 方案時設定了帳單，但在試用期間，使用 Data Connect 或預設的 PostgreSQL 適用的 Cloud SQL 設定不會產生費用。

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

   應用程式結構定義會連同對應的 PostgreSQL 資料庫一併部署。

   注意：如要使用客戶自行管理的加密金鑰 (CMEK)，請務必選擇「使用現有的 Cloud SQL 執行個體」，並選取已啟用 CMEK 的現有 Cloud SQL 資料庫。
   注意：系統最多可能需要 15 分鐘，才能完成 Cloud SQL for PostgreSQL 執行個體的佈建作業。您可以使用 Google Cloud 控制台，確認 Data Connect 設定流程 (包括資料庫佈建) 是否完成。

控制台流程：使用 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 mutation，藉此更新其中一個資料表，並定義為 query，藉此確認更新。

注意：您必須先建立及部署結構定義，才能建立作業。

提示：由於結構定義可以描述任何類型的應用程式，為了方便學習本指南中的 Data Connect，我們可以將哪個實體視為參考對象？您的結構化資料可能包含基本實體類型，例如 Movie (電影評論應用程式)、Product (電子商務應用程式) 或 Account (付款應用程式)。在接下來的幾個步驟中，請從架構中挑選單一類型。

警告： 在資料編輯器中執行突變作業會實際執行突變，並可能變更資料。

1. 開啟「資料」分頁。

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

   注意： 請選擇簡單的基本實體 (例如 Product 或 Account) 來填入資料。

   例如：

   Add data for three sample products to my app.
   

3. 點選「產生」，系統會傳回變動。

4. 查看輸出內容。視需要按一下「編輯」來修正提示，然後按一下「重新生成」。

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

6. 按一下「執行」。

執行變動時，資料會寫入 PostgreSQL 資料庫中的適用資料表。您可以在控制台中建立查詢，查看儲存的資料：

1. 使用「幫我寫 GraphQL」 重複先前的步驟，建立查詢。

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 擴充功能 UI：

1. 按一下「啟動模擬器」按鈕。

   注意： 在整合式終端機中，確認已設定的模擬器啟動。執行後，您應該會看到擴充功能 UI 更新，並顯示模擬器詳細資料。

本機流程：在本機環境中尋找結構定義和連接器

您用來將資產同步至現有專案的 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 編輯器面板中，您會看到 GraphQL 型別上方的 CodeLens 按鈕 (位於 /dataconnect/schema/schema.gql 中)。就像在控制台中一樣，您可以建立突變，將資料新增至正式版資料庫。

注意： 結構定義是您向結構定義輔助工具描述的應用程式專屬結構定義。 在架構中選擇要新增資料的基本類型，例如 Movie (電影評論應用程式)、Product 或 Account (電子商務應用程式)。

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

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

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

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

在說明文件中進一步瞭解 Data Connect 突變

本機流程：產生 SDK

結構定義和連接器作業會在本機同步處理。

現在您可以使用 VS Code 擴充功能產生用戶端 SDK，開始在 iOS、Android、網頁和 Flutter 應用程式中實作查詢和變動的呼叫。

1. 在擴充功能 UI 中，按一下「將 SDK 新增至應用程式」按鈕。

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

   注意： 如果還沒有應用程式目錄，可以先建立並選取新的 SDK 程式碼目錄，稍後再連結至應用程式。

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

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

您先前已在 Firebase 控制台中部署結構定義和作業。 如要從應用程式呼叫作業，可以使用產生的 SDK 實作對ListMovies查詢的呼叫。Data Connect

注意： 以下範例再次包含對匯入內容 (例如 @movie-app/movies) 和作業 (例如 ListMovies) 的參照 (可能位於電影評論應用程式的結構定義中)。在產生的 SDK 中，您可能會看到適用於應用程式的方法，例如 ListProducts 或 ListAccounts。

您可能會發現，在我們的程式碼研究室中，探索具有完整功能的 Data Connect 應用程式的快速入門應用程式存放區，對於瞭解產生的 SDK 特別有幫助，適用於網頁、iOS 或 Android。

網頁版

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

   • 匯入產生的 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 伺服器，以及撰寫提示的最佳做法。
• 進一步瞭解結構定義、查詢和突變開發
• 瞭解如何產生用戶端 SDK，以及從網頁、Android、iOS 和 Flutter 的用戶端程式碼呼叫查詢和變動。