本頁面由 Cloud Translation API 翻譯而成。

在本機開始使用 Firebase Data Connect

本快速入門導覽課程將協助您開始使用 Firebase Data Connect，將網頁和行動應用程式連線至 PostgreSQL 資料庫。您將學會以下內容：

使用 VS Code 和 Firebase CLI 設定本機 Firebase Data Connect 專案目錄。
根據您以自然語言提出的應用程式構想，生成 Data Connect 結構定義、查詢和異動。
在應用程式中使用強型別 SDK，執行Data Connect查詢和異動。
佈建 PostgreSQL 適用的 Cloud SQL 執行個體、Data Connect 結構定義、查詢和變動 (需要 Blaze 方案)。

設定本機專案目錄

您可以透過兩種方式安裝 Data Connect 的本機開發工具。

安裝下列必要項目：
- Visual Studio Code
- Node.js，使用 nvm-windows (適用於 Windows) 或 nvm (適用於 macOS 或 Linux)。
- Firebase CLI
建立專案目錄，並在 Visual Studio Code 中開啟。
從 VS Code Marketplace 安裝 Firebase Data Connect 擴充功能。
按一下「使用 Google 帳戶登入」按鈕。
按一下「連結 Firebase 專案」按鈕。
按一下「Run firebase init」按鈕。
按一下「Start emulators」按鈕，即可使用本機 PGlite 資料庫執行 Data Connect 模擬器。

查看結構定義

Firebase Data Connect 使用 GraphQL 定義資料模型。@table 指令會將 GraphQL 型別對應至 PostgreSQL 資料表。類型中的欄位會對應至 PostgreSQL 資料欄。您可以使用參照其他 @table 型別的欄位定義資料表之間的關係，包括使用具有複合主鍵的聯結資料表定義多對多關係。

在預設設定中，您可以在 dataconnect/schema/ 目錄中找到 Data Connect 架構檔案。以下是電影範本結構定義中的兩個範例表格。如果您使用 Gemini 生成結構化資料，結構化資料可能會有所不同。

type Movie @table {
  # Every table has an implicit primary key field that looks something like:
  #  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

type Review @table(key: ["movie", "user"]) {
  user: User!
  movie: Movie!
  rating: Int
  reviewText: String
  reviewDate: Date! @default(expr: "request.time")
}

進一步瞭解資料連結架構

開發查詢和異動

Firebase Data Connect 使用 GraphQL 進行查詢和異動。您可以在 .gql 檔案中定義這些項目，並從應用程式依名稱呼叫。GraphQL 語法提供強型別 SDK 和彈性 API，可擷取應用程式所需的確切資料。

在資料庫中填充資料

模擬器執行後，您就可以植入初始資料。您可以使用提供的 dataconnect/seed_data.gql 檔案，也可以自行編寫突變。

在 VS Code 中使用「Run (local)」程式碼鏡頭按鈕執行突變，並填入本機 PGlite 資料庫。

Firebase Data Connect 的 CodeLens 執行按鈕

查看查詢和異動

在預設設定中，您可以在 dataconnect/example/ 目錄中找到 Data Connect 查詢和變動。

您可以使用巢狀查詢，精確查詢關聯式資料。

query ListMovies @auth(level: PUBLIC, insecureReason: "Anyone can list all movies and their reviews.") {
  movies {
    title imageUrl genre
    reviews_on_movie {
      rating reviewDate
      user { username }
    }
  }
}

Data Connect可協助您使用 Firebase Auth 建構安全無虞的查詢和變動。

為確保應用程式安全，網頁和行動應用程式只能透過 @auth 指令存取 Data Connect 查詢和變動。查詢和變動可使用 {field}_expr: "auth.uid" 等運算式，安全存取 Firebase Auth UID。

mutation AddReview($movieId: UUID!, $rating: Int!, $reviewText: String!) @auth(level: USER) {
  review_upsert(
    data: {
      userId_expr: "auth.uid"
      movieId: $movieId
      rating: $rating
      reviewText: $reviewText
    }
  )
}

進一步瞭解 Data Connect 查詢進一步瞭解 Data Connect 突變進一步瞭解 Data Connect Auth

生成查詢和異動

您不必是 GraphQL 專家，也能有效使用 Data Connect。您可以根據自然語言描述生成 Data Connect 查詢和突變。

在任何 .gql 檔案中，輸入 # 即可開始註解，並說明查詢或變動。接著，使用「Generate/Refine Operation」程式碼鏡頭按鈕，產生 GraphQL 作業。

Firebase Data Connect 的 CodeLens「生成」按鈕

在應用程式中使用產生的 SDK

firebase init dataconnect 會自動為專案中的應用程式設定類型安全 SDK。如有需要，您可以使用 VS Code 擴充功能的「Add SDK to app」(將 SDK 新增至應用程式) 按鈕，或執行 firebase init dataconnect:sdk，手動新增 SDK。

網頁版

將 Firebase 新增至網頁應用程式。

在 React 應用程式的主要檔案中：

匯入產生的 SDK：

// Update as needed with the path to your generated SDK.
import { listMovies, ListMoviesData } from '@dataconnect/generated';

為應用程式進行插樁，以便連線至 Data Connect 模擬器：

import { connectDataConnectEmulator } from 'firebase/data-connect';

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);

呼叫 Data Connect 方法。

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

將 Firebase 新增至 iOS 應用程式。
如要使用產生的 SDK，請在 Xcode 中將其設為依附元件。

在 Xcode 頂端導覽列中，依序選取「File」>「Add Package Dependencies」>「Add Local」，然後選擇包含所產生 Package.swift 的資料夾。

在應用程式的主要委派中：

匯入 Data Connect SDK 和您產生的 SDK：

import FirebaseDataConnect
// Generated queries.
// Update as needed with the package name of your generated SDK.
import <CONNECTOR-PACKAGE-NAME>

let connector = DataConnect.moviesConnector

為應用程式進行插樁，以便連線至 Data Connect 模擬器：

// Connect to the emulator on "127.0.0.1:9399"
connector.useEmulator()

// (alternatively) if you're running your emulator on non-default port:
// connector.useEmulator(port: 9999)

呼叫 Data Connect 方法：

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

將 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")
}

在應用程式的主要活動中：

從產生的 SDK 取得連接器執行個體：

private val connector = com.myapplication.MoviesConnector.instance

為應用程式進行插樁，以便連線至 Data Connect 模擬器：

private val connector = com.myapplication.MoviesConnector.instance
  .apply {
    // Connect to the emulator on "10.0.2.2:9399" (default port)
    dataConnect.useEmulator()

    // (alternatively) if you're running your emulator on non-default port:
    // dataConnect.useEmulator(port = 9999)
  }

呼叫 Data Connect 方法。

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

將 Firebase 新增至 Flutter 應用程式。
安裝 flutterfire CLI dart pub global activate flutterfire_cli。
執行 flutterfire configure。

在應用程式的主要函式中：

匯入產生的 SDK：

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

import 'movies_connector/movies.dart';

為應用程式進行插樁，以便連線至 Data Connect 模擬器：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  
  MoviesConnector.instance.dataConnect
      .useDataConnectEmulator(Uri.base.host, 443, isSecure: true);
  
  runApp(const MyApp());
}

呼叫 Data Connect 方法。

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 專案，改用 Blaze 方案。
在 Data Connect VS Code 擴充功能中，按一下「Deploy to production」(部署至正式版) 按鈕，或在終端機中執行下列指令：
```
firebase deploy --only dataconnect
```
部署完成後，請前往 Firebase 控制台查看結構定義，並執行查詢和突變。

提示：您可以在部署前，於 dataconnect.yaml 中設定 Cloud SQL 區域、執行個體名稱和 PostgreSQL 資料庫名稱。
提示：每個專案都可使用一個 Cloud SQL 3 個月的免費試用執行個體。請參閱相關限制。

進一步瞭解 dataconnect.yaml 進一步瞭解 Data Connect 如何與 Cloud SQL 搭配運作

後續步驟

您已完成快速入門導覽課程，接下來可以採取下列行動：

探索快速入門應用程式存放區，並按照網頁版程式碼研究室、iOS 版程式碼研究室或 Android 版程式碼研究室的說明，建構功能齊全的 Data Connect 應用程式。
在 Firebase 控制台中，將資料新增至資料庫、檢查結構定義，以及監控 Data Connect 服務。
使用 Gemini Code Assist 等 AI 輔助開發工具，設定 Firebase MCP 伺服器。
進一步瞭解結構定義、查詢和突變開發作業。
進一步瞭解 Data Connect 如何管理 PostgreSQL 結構定義。
進一步瞭解網頁、Android、iOS 和 Flutter 的用戶端 SDK，以及 Node.js 的 Admin SDK。