Bắt đầu sử dụng Firebase Data Connect

Hướng dẫn bắt đầu nhanh này giúp bạn thiết lập và chạy Firebase Data Connect để kết nối các ứng dụng web và di động của bạn với cơ sở dữ liệu PostgreSQL. Bạn sẽ:

  • Thiết lập thư mục dự án Firebase Data Connect cục bộ bằng VS Code và Giao diện dòng lệnh (CLI) của Firebase.
  • Tạo lược đồ, truy vấn và đột biến Data Connect dựa trên ý tưởng về ứng dụng của bạn bằng ngôn ngữ tự nhiên.
  • Sử dụng các SDK có kiểu dữ liệu rõ ràng trong ứng dụng để chạy các truy vấn và đột biến Data Connect.
  • Cung cấp một phiên bản Cloud SQL cho PostgreSQL, một giản đồ Data Connect, các truy vấn và đột biến (cần có gói Blaze).

Thiết lập thư mục dự án cục bộ

Bạn có thể cài đặt các công cụ phát triển cục bộ cho Data Connect theo 2 cách.

  1. Trong thư mục dự án, hãy chạy lệnh sau.

    Tập lệnh này sẽ cài đặt Firebase CLI và tiện ích Data Connect VS Code, đồng thời hướng dẫn bạn thực hiện firebase init dataconnect để thiết lập dự án. Nếu bạn chưa cài đặt VS Code trên máy tính, tập lệnh sẽ mở VS Code trong một trình duyệt.

    curl -sL https://firebase.tools/init/dataconnect | editor=true bash

  2. Mở màn hình tiện ích Data Connect VS Code bằng cách nhấp vào biểu tượng Firebase trong bảng điều khiển bên trái của Visual Studio Code.

  3. Nhấp vào Start emulators (Khởi động trình mô phỏng) để chạy trình mô phỏng bằng cơ sở dữ liệu PGlite cục bộ.

Giản đồ bài đánh giá

Firebase Data Connect sử dụng GraphQL để xác định mô hình dữ liệu của bạn. Chỉ thị @table liên kết một loại GraphQL với một bảng PostgreSQL. Các trường trong bản đồ loại liên kết với các cột PostgreSQL. Bạn có thể xác định mối quan hệ giữa các bảng bằng cách sử dụng các trường tham chiếu đến các loại @table khác, bao gồm cả mối quan hệ nhiều-nhiều bằng cách sử dụng các bảng kết hợp với khoá chính kết hợp.

Trong chế độ thiết lập mặc định, bạn có thể tìm thấy các tệp giản đồ Data Connect trong thư mục dataconnect/schema/. Sau đây là 2 bảng ví dụ trong giản đồ mẫu phim. Lược đồ của bạn có thể khác nếu bạn dùng Gemini để tạo lược đồ đó.

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

Tìm hiểu thêm về giản đồ Data Connect

Phát triển các truy vấn và đột biến

Firebase Data Connect sử dụng GraphQL cho các truy vấn và đột biến. Bạn xác định các tệp này trong .gql và gọi chúng theo tên từ ứng dụng của mình. Cú pháp GraphQL cung cấp các SDK có kiểu dữ liệu mạnh và một API linh hoạt để tìm nạp chính xác dữ liệu mà ứng dụng của bạn cần.

Dữ liệu ban đầu trong cơ sở dữ liệu

Khi trình mô phỏng đang chạy, bạn có thể gieo dữ liệu ban đầu cho trình mô phỏng. Bạn có thể sử dụng tệp dataconnect/seed_data.gql được cung cấp hoặc tự viết các đột biến.

Sử dụng nút Run (local) (Chạy (cục bộ)) của Code Lens trong VS Code để thực thi các đột biến và điền sẵn cơ sở dữ liệu PGlite cục bộ.

Nút Chạy CodeLens cho Firebase Data Connect

Xem xét các truy vấn và đột biến

Trong chế độ thiết lập mặc định, bạn có thể tìm thấy các truy vấn và đột biến Data Connect trong thư mục dataconnect/example/.

Bạn có thể truy vấn dữ liệu quan hệ một cách chính xác bằng các truy vấn lồng nhau.

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 giúp bạn tạo các truy vấn và đột biến an toàn bằng Firebase Auth.

Để đảm bảo an toàn cho ứng dụng, các ứng dụng web và di động chỉ có thể truy cập vào các truy vấn và đột biến Data Connect bằng chỉ thị @auth. Các truy vấn và đột biến có thể truy cập an toàn vào UID Xác thực Firebase bằng một biểu thức như {field}_expr: "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
    }
  )
}

Tìm hiểu thêm về các truy vấn Data Connect Tìm hiểu thêm về các đột biến Data Connect Tìm hiểu thêm về Data Connect Auth

Tạo truy vấn và đột biến

Bạn không cần phải là chuyên gia về GraphQL để sử dụng Data Connect một cách hiệu quả. Bạn có thể tạo các truy vấn và đột biến Data Connect từ nội dung mô tả bằng ngôn ngữ tự nhiên.

Trong tệp .gql bất kỳ, hãy nhập # để bắt đầu một nhận xét và mô tả một truy vấn hoặc đột biến. Sau đó, hãy dùng nút Generate/Refine Operation (Tạo/Tinh chỉnh thao tác) Code Lens để tạo thao tác GraphQL.

Nút Tạo CodeLens cho Firebase Data Connect

Sử dụng SDK đã tạo trong ứng dụng của bạn

firebase init dataconnect tự động thiết lập các SDK an toàn về kiểu cho các ứng dụng trong dự án của bạn. Nếu cần, bạn có thể thêm SDK theo cách thủ công bằng nút Add SDK to app (Thêm SDK vào ứng dụng) trong tiện ích VS Code hoặc bằng cách chạy firebase init dataconnect:sdk.

Web

  1. Thêm Firebase vào ứng dụng web của bạn.

  2. Trong tệp chính của ứng dụng React:

    • Nhập SDK đã tạo:
    // Update as needed with the path to your generated SDK.
import { listMovies, ListMoviesData } from '@dataconnect/generated';
    • Đo lường ứng dụng của bạn để kết nối với trình mô phỏng Data Connect:
    import { connectDataConnectEmulator } from 'firebase/data-connect';

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);
    • Gọi các phương thức 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

  1. Thêm Firebase vào ứng dụng iOS của bạn.

  2. Để sử dụng SDK đã tạo, hãy định cấu hình SDK đó làm một phần phụ thuộc trong Xcode.

    Trong thanh điều hướng trên cùng của Xcode, hãy chọn File (Tệp) > Add Package Dependencies (Thêm các phần phụ thuộc của gói) > Add Local (Thêm cục bộ), rồi chọn thư mục chứa Package.swift đã tạo.

  3. Trong uỷ quyền chính của ứng dụng:

    • Nhập SDK Data Connect và SDK do bạn tạo:

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

let connector = DataConnect.moviesConnector

    • Đo lường ứng dụng của bạn để kết nối với trình mô phỏng 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)

    • Gọi các phương thức 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

  1. Thêm Firebase vào ứng dụng Android của bạn.

  2. Để sử dụng SDK đã tạo, hãy định cấu hình Data Connect làm phần phụ thuộc trong Gradle.

    Cập nhật plugins và dependencies trong app/build.gradle.kts.

    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. Trong hoạt động chính của ứng dụng:

    • Lấy một thực thể trình kết nối từ SDK đã tạo:
    private val connector = com.myapplication.MoviesConnector.instance
    • Đo lường ứng dụng của bạn để kết nối với trình mô phỏng 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)
  }
    • Gọi các phương thức 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

  1. Thêm Firebase vào ứng dụng Flutter.
  2. Cài đặt CLI flutterfire dart pub global activate flutterfire_cli.
  3. Chạy flutterfire configure.

  4. Trong hàm chính của ứng dụng:

    • Nhập SDK đã tạo:
    // Generated queries.
// Update as needed with the path to your generated SDK

import 'movies_connector/movies.dart';
    • Đo lường ứng dụng của bạn để kết nối với trình mô phỏng 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());
}
    • Gọi các phương thức 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();
            }),
      )
    ])));
  }
}

Triển khai cho kênh phát hành công khai

Cách triển khai giản đồ, truy vấn và đột biến của bạn cho bản phát hành công khai:

  1. Nâng cấp Dự án Firebase để sử dụng gói Blaze.

  2. Nhấp vào nút Triển khai cho bản phát hành công khai trong tiện ích Data Connect VS Code hoặc chạy trong một thiết bị đầu cuối:

    firebase deploy --only dataconnect

    Sau khi triển khai, hãy truy cập vào bảng điều khiển Firebase để xem giản đồ và chạy các truy vấn cũng như đột biến.

Tìm hiểu thêm về dataconnect.yaml Tìm hiểu thêm về cách Data Connect hoạt động với Cloud SQL

Các bước tiếp theo

Giờ đây, bạn đã hoàn thành hướng dẫn bắt đầu nhanh. Sau đây là một số bước tiếp theo: