תחילת העבודה עם Firebase Data Connect באופן מקומי

במדריך למתחילים הזה תלמדו איך לפתח את Firebase Data Connect באפליקציה באופן מקומי, בלי להגדיר מכונה של SQL בסביבת הייצור. תוכלו:

  • מוסיפים את Firebase Data Connect לפרויקט Firebase.
  • הגדרת סביבת פיתוח שכוללת תוספים ל-Visual Studio Code לעבודה עם מכונה מקומית.
  • לאחר מכן נסביר איך:
    • משתמשים בכלי התוספים של VS Code, עם Gemini Code Assist, כדי:
      • יצירת סכימה לאפליקציה
      • יצירת שאילתות ומוטציות ניהוליות כדי לאכלס את מסד הנתונים המקומי
      • עזרה בהטמעת שאילתות ומוטציות לאפליקציה במחבר שניתן לפריסה
    • בדיקת השאילתות והמוטציות באמצעות נתונים לדוגמה במהלך בדיקה במהדורת אימולטור מקומית
    • יצירת ערכות SDK עם סוגים מוגדרים ושימוש בהן באפליקציה
    • פורסים את הסכימה והמחבר הסופיים בענן (אופציונלי, עם שדרוג לתוכנית Blaze).

בחירת תהליך פיתוח מקומי

ב-Data Connect יש שתי דרכים להתקין כלי פיתוח ולעבוד באופן מקומי.

דרישות מוקדמות

כדי להשתמש במדריך למתחילים הזה, נדרשים הדברים הבאים:

תהליך מקומי: הגדרת סביבת הפיתוח

  1. יוצרים ספרייה חדשה לפרויקט המקומי.
  2. פותחים את VS Code בספרייה החדשה.
  3. מתקינים את התוסף Firebase Data Connect מ-Visual Studio Code Marketplace.

הגדרת ספריית הפרויקט

כדי להגדיר את הפרויקט המקומי, צריך לאתחל את ספריית הפרויקט. בחלון ה-IDE, לוחצים על סמל Firebase בחלונית הימנית כדי לפתוח את ממשק המשתמש של התוסף Data Connect ל-VS Code:

  1. לוחצים על הלחצן כניסה באמצעות חשבון Google.
  2. לוחצים על הלחצן Connect a Firebase project ובוחרים את הפרויקט שיצרתם קודם במסוף.
  3. לוחצים על הלחצן Run firebase init.

  4. לוחצים על הלחצן Start emulators.

יצירת סכימה

בספריית הפרויקט ב-Firebase, בקובץ /dataconnect/schema/schema.gql, מתחילים להגדיר סכימה של GraphQL לגבי ביקורות על סרטים, לדוגמה.

שימוש ב-Gemini Code Assist כדי ליצור סכימה

כדי ליצור סכימה של אפליקציה לביקורות סרטים באמצעות Gemini Code Assist:

  1. לוחצים על הסמל של התוסף Data Connect ל-VS Code כדי לפתוח את סרגל הצד שלו.
  2. לוחצים על Try Gemini with @data-connect. חלון הצ'אט Gemini Code Assist ייפתח.
  3. לוחצים על ממשק הצ'אט ומתחילים להקליד @data-connect כדי לסנן את הפקודות הרלוונטיות.

  4. בוחרים את הפקודה /generate_schema ובתגובה להנחיה, משלימים את הפקודה ומבקשים מ-Gemini ליצור סכימה לאפליקציה שאתם מפתחים.

    לדוגמה:

    @data-connect /generate_schema I want to build an app to track movie reviews from multiple users

  5. אחרי כמה רגעים תוצג לכם סכימה מומלצת. בודקים את הסכימה.

  6. כדי להוסיף את הקוד ל-schema.gql:

    1. לוחצים על הלחצן הוספה לתחתית הקובץ.
    2. לחלופין, כדי להוסיף את הקוד במיקום הסמן, לוחצים על הלחצן + בחלק העליון של התשובה בצ'אט.

סרט

ב-Data Connect, שדות GraphQL ממופים לעמודות. הסרט כולל את id, title, imageUrl וגם genre. Data Connect מזהה סוגי נתונים בסיסיים: String ו-UUID.

מעתיקים את קטע הקוד הבא או מסירים את ההערות מהשורות המתאימות בקובץ.

# By default, a UUID id key will be created by default as primary key.
# If you want to specify a primary key, say title, which you can do through
# the @table(key: "title") directive
type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

MovieMetadata

מעתיקים את קטע הקוד הבא או מסירים את ההערות מהשורות המתאימות בקובץ.

# 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 זמין במסמכי התיעוד

הוספת נתונים לטבלאות

בחלונית העריכה של סביבת הפיתוח המשולבת יופיעו לחצני CodeLens מעל סוגי GraphQL בקובץ /dataconnect/schema/schema.gql. אפשר להשתמש בלחצנים Add data (הוספת נתונים) ו-Run (Local) (הפעלה (מקומית)) כדי להוסיף נתונים למסד הנתונים המקומי.

כדי להוסיף רשומות לטבלאות Movie ו-MovieMetadata:

  1. ב-schema.gql, לוחצים על הלחצן Add data מעל הצהרת הסוג Movie.
    לחצן הוספת נתונים של CodeLens ל-Firebase Data Connect
  2. בקובץ Movie_insert.gql שנוצר, מקודדים את הנתונים של שלושת השדות.
  3. לוחצים על הלחצן הפעלה (מקומית).
    לחצן ההפעלה של CodeLens עבור Firebase Data Connect
  4. חוזרים על השלבים הקודמים כדי להוסיף רשומה לטבלה MovieMetadata, ומספקים את הערך של id של הסרט בשדה movieId, כפי שמופיע בהנחיה במונטיזציה שנוצרה של MovieMetadata_insert.

כדי לוודא במהירות שהנתונים נוספו:

  1. חזרה ב-schema.gql, לוחצים על הלחצן Read data מעל להצהרת הסוג Movie.
  2. בקובץ Movie_read.gql שנוצר, לוחצים על הלחצן Run (Local) כדי להריץ את השאילתה.

מידע נוסף על מוטציות של Data Connect זמין במסמכי התיעוד

הגדרת שאילתה

עכשיו מגיע החלק הכי כיף: הגדרת השאילתות שיהיו נחוצות באפליקציה. כמפתחים, אתם רגילים לכתוב שאילתות SQL ולא שאילתות GraphQL, ולכן יכול להיות שבהתחלה זה ייראה לכם קצת שונה.

עם זאת, GraphQL הוא מצומצם הרבה יותר ומאובטח יותר מבחינת סוגים מ-SQL גולמי. בנוסף, התוסף שלנו ל-VS Code מקל על תהליך הפיתוח, גם של שאילתות וגם של מוטציות.

כדי ליצור שאילתה באמצעות Gemini Code Assist:

  1. לוחצים על הסמל של התוסף Data Connect ל-VS Code כדי לפתוח את סרגל הצד שלו.
  2. לוחצים על Try Gemini with @data-connect. חלון הצ'אט Gemini Code Assist ייפתח.
  3. לוחצים על ממשק הצ'אט ומתחילים להקליד @data-connect כדי לסנן את הפקודות הרלוונטיות.

  4. בוחרים את הפקודה /generate_operation ובתגובה להנחיה, משלימים את הפקודה ומבקשים מ-Gemini ליצור שאילתה.

    לדוגמה:

    @data-connect /generate_operation List all movies with titles start with "A".

  5. אחרי כמה רגעים תופיע שאילתה מומלצת. בודקים את השאילתה.

  6. כדי להוסיף את הקוד ל-queries.gql:

    1. לוחצים על הלחצן הוספה לתחתית הקובץ.
    2. לחלופין, כדי להוסיף את הקוד במיקום הסמן, לוחצים על הלחצן + בחלק העליון של התשובה בצ'אט.

מריצים את השאילתה באמצעות לחצן CodeLens שנמצא בקרבת מקום.

מידע נוסף על שאילתות של Data Connect זמין במסמכי התיעוד

יצירת ערכות SDK ושימוש בהן באפליקציה

בחלונית הימנית של סביבת הפיתוח המשולבת, לוחצים על סמל Firebase כדי לפתוח את ממשק המשתמש של התוסף Data Connect ל-VS Code:

  1. לוחצים על הלחצן Add SDK to app (הוספת ה-SDK לאפליקציה).

  2. בתיבת הדו-שיח שתופיע, בוחרים ספרייה שמכילה את הקוד של האפליקציה. קוד ה-SDK של Data Connect ייווצר ויישמר שם.

  3. בוחרים את פלטפורמת האפליקציה, שימו לב שקוד ה-SDK נוצר באופן מיידי בתיקייה שנבחרה.

שימוש ב-SDK כדי להפעיל את השאילתה מאפליקציה

אפשר להשתמש ב-SDK שנוצר על ידי Data Connect כדי להטמיע קריאה לשאילתה ListMovies. לאחר מכן תוכלו להריץ את השאילתה הזו באופן מקומי באמצעות אמולטור Data Connect.

אינטרנט

  1. מוסיפים את Firebase לאפליקציית האינטרנט.

  2. בקובץ הראשי של אפליקציית React:

    • מייבאים את ה-SDK שנוצר
    • מכשירים את האפליקציה כדי להתחבר לאמולטור Data Connect
    • קריאה לשיטות Data Connect.
    import React from 'react';
import ReactDOM from 'react-dom/client';

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

// Generated queries.
// Update as needed with the path to your generated SDK.
import { listMovies, ListMoviesData } from '@movie-app/movies';

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

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
    • קריאה לשיטות 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

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

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.

    מעדכנים את plugins ואת dependencies ב-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. בפעילות הראשית של האפליקציה:

    • מייבאים את ה-SDK שנוצר
    • מכשירים את האפליקציה כדי להתחבר לאמולטור Data Connect
    • קריאה לשיטות 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
  .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)
  }


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. מתקינים את ה-CLI של flutterfire dart pub global activate flutterfire_cli.
  3. מריצים את flutterfire configure.
  4. בפונקציה הראשית של האפליקציה:
    • מייבאים את ה-SDK שנוצר
    • מכשירים את האפליקציה כדי להתחבר לאמולטור Data Connect
    • קריאה לשיטות 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,
  );
  
  MoviesConnector.instance.dataConnect
      .useDataConnectEmulator(Uri.base.host, 443, isSecure: true);
  
  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();
            }),
      )
    ])));
  }
}

פריסה של הסכימה והשאילתה בסביבת הייצור

אחרי שתגדירו את האפליקציה באופן מקומי, תוכלו לפרוס את הסכימה והמחבר בענן. כדי להגדיר מכונה של Cloud SQL, צריך פרויקט בתוכנית Blaze.

  1. עוברים לקטע Data Connect במסוף Firebase ויוצרים מכונה של Cloud SQL לניסיון בחינם.

  2. במסוף המובנה של IDE, מריצים את הפקודה firebase init dataconnect ובוחרים את Region/Service ID שיצרתם עכשיו במסוף.

  3. בוחרים באפשרות Y בתגובה להודעה "File dataconnect/dataconnect.yaml already exists, Overwrite?".

  4. בחלון ה-IDE, בממשק המשתמש של התוסף ל-VS Code, לוחצים על הלחצן פריסה בסביבת הייצור.

  5. אחרי הפריסה, עוברים למסוף Firebase כדי לוודא שהסכימה, הפעולות והנתונים הועלאו לענן. אמורה להיות לכם אפשרות להציג את הסכימה ולהריץ את הפעולות במסוף. המכונה של Cloud SQL for PostgreSQL תתעדכן עם הסכימה והנתונים שנוצרו לפריסה הסופית.

השלבים הבאים

בודקים את הפרויקט שנפרס ומכירים כלים נוספים:

  • הוספת נתונים למסד הנתונים, בדיקה ושינוי של הסכימות ומעקב אחרי שירות Data Connect במסוף Firebase.

מידע נוסף זמין במסמכי התיעוד. לדוגמה, אחרי שמשלימים את המדריך למתחילים: