תחילת העבודה עם Firebase Data Connect

במדריך למתחילים הזה תלמדו איך להשתמש ב-Firebase Data Connect כדי לקשר את אפליקציות האינטרנט והאפליקציות לנייד למסד נתונים של PostgreSQL. תצטרכו:

מגדירים את ספריית הפרויקט המקומי Firebase Data Connect באמצעות VS Code ו-Firebase CLI.
יצירת סכימות, שאילתות ומוטציות על סמך רעיונות לאפליקציות בשפה טבעית.Data Connect
אפשר להשתמש בערכות ה-SDK עם הקלדה חזקה באפליקציות כדי להריץ שאילתות ושינויים.Data Connect
הקצאת מכונה של Cloud SQL ל-PostgreSQL, סכימה של Data Connect, שאילתות ושינויים.

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

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

בספריית פרויקט, מריצים את הפקודה הבאה.

הסקריפט מתקין את Firebase CLI ואת התוסף Data Connect VS Code, ומנחה אתכם firebase init dataconnect להגדרת הפרויקט. אם לא התקנתם את VS Code desktop, הסקריפט ייפתח בדפדפן.
```
curl -sL https://firebase.tools/init/dataconnect | editor=true bash
```
פותחים את המסך של התוסף Data Connect VS Code על ידי לחיצה על סמל Firebase בחלונית הימנית של Visual Studio Code.
לוחצים על Start emulators כדי להפעיל את האמולטור עם מסד נתונים מקומי של PGlite.

סכימת ביקורת

‫Firebase Data Connect משתמש ב-GraphQL כדי להגדיר את מודל הנתונים. ההנחיה @table ממפה סוג GraphQL לטבלת PostgreSQL. השדות במפת הסוגים ממופים לעמודות ב-PostgreSQL. אפשר להגדיר קשרים בין טבלאות באמצעות שדות שמפנים לסוגים אחרים של @table, כולל קשרים רבים לרבים באמצעות טבלאות איחוד עם מפתחות ראשיים מורכבים.

בהגדרת ברירת המחדל, קובצי הסכימה Data Connect נמצאים בספרייה dataconnect/schema/. לפניכם שתי דוגמאות לטבלאות מסכימת התבנית של סרט. יכול להיות שהסכימה שלכם תהיה שונה אם השתמשתם ב-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")
}

מידע נוסף על סכימות של Data Connect

פיתוח שאילתות ומוטציות

‫Firebase Data Connect משתמש ב-GraphQL לשאילתות ולשינויים. אתם מגדירים אותם בקובצי .gql וקוראים להם לפי שם מהאפליקציה. תחביר GraphQL מספק ערכות SDK עם הקלדה חזקה וממשק API גמיש לאחזור הנתונים המדויקים שהאפליקציה שלכם צריכה.

נתוני Seed במסד הנתונים

אחרי שמפעילים את האמולטור, אפשר להזין בו נתונים ראשוניים. אתם יכולים להשתמש בקובץ dataconnect/seed_data.gql שסופק או לכתוב מוטציות משלכם.

משתמשים בלחצן Run (local) (הפעלה (מקומי)) של Code Lens ב-VS Code כדי להריץ את השינויים ולאכלס את מסד הנתונים המקומי של PGlite.

לחצן ההפעלה של CodeLens ל-Firebase Data Connect

בדיקת שאילתות ומוטציות

בהגדרת ברירת המחדל, אפשר למצוא את השאילתות והמוטציות בספרייה 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 אפשר לגשת בבטחה למזהה המשתמש (UID) של Firebase Auth באמצעות שאילתות ומוטציות, באמצעות ביטוי כמו {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
    }
  )
}

מידע נוסף על Data Connect שאילתות מידע נוסף על Data Connect מוטציות מידע נוסף על Data Connect אימות

יצירה של שאילתות ומוטציות

לא צריך להיות מומחים ב-GraphQL כדי להשתמש ב-Data Connect ביעילות. אתם יכולים ליצור שאילתות ומוטציות של Data Connect מתיאורים בשפה טבעית.

בכל קובץ .gql, מקלידים # כדי להתחיל תגובה ולתאר שאילתה או מוטציה. לאחר מכן, משתמשים בלחצן Generate/Refine Operation Code Lens כדי ליצור את פעולת GraphQL.

לחצן ליצירת קוד ב-CodeLens ל-Firebase Data Connect

שימוש ב-SDK שנוצר באפליקציה

‫firebase init dataconnect באופן אוטומטי מגדיר ערכות SDK בטוחות לטיפוסים עבור אפליקציות בפרויקט. אם צריך, אפשר להוסיף את ה-SDK באופן ידני באמצעות הלחצן Add SDK to app (הוספת ה-SDK לאפליקציה) בתוסף Data Connect של VS Code או על ידי הפעלת firebase init dataconnect: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);

הפעלת methods של 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)

הפעלת method של 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 שנוצר, צריך להגדיר את 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")
}

בפעילות הראשית של האפליקציה:

מקבלים מופע של מחבר מ-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)
  }

הפעלת methods של 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());
}

הפעלת methods של 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 Data Connect.
לוחצים על הלחצן Deploy to production (פריסה בסביבת הייצור) בתוסף Data Connect VS Code או מריצים את הפקודה בטרמינל:
```
firebase deploy --only dataconnect
```
אחרי הפריסה, נכנסים אל מסוף Firebase כדי לראות את הסכימה ולהריץ שאילתות ושינויים.

טיפ: אפשר להגדיר את האזור ב-Cloud SQL, את שם המופע ואת שם מסד הנתונים של PostgreSQL ב-dataconnect.yaml לפני הפריסה.

מידע נוסף על dataconnect.yaml מידע נוסף על האופן שבו Data Connect פועל עם Cloud SQL

השלבים הבאים

עכשיו, אחרי שסיימתם את המדריך למתחילים, הנה כמה פעולות שכדאי לבצע:

אפשר לעיין במאגר של אפליקציית התחלה מהירה וליצור אפליקציית Data Connect מלאה באמצעות ה-Codelab לאינטרנט, ה-Codelab ל-iOS או ה-Codelab ל-Android.
אפשר להוסיף נתונים למסד הנתונים, לבדוק את הסכימות ולעקוב אחרי שירות Data Connect במסוף Firebase.
מגדירים את שרת ה-MCP של Firebase בעזרת כלי פיתוח מבוססי-AI כמו Gemini Code Assist.
מידע נוסף על פיתוח סכימות, שאילתות ומוטציות
Data Connect מידע נוסף על האופן שבו מנוהלת סכימת PostgreSQL
מידע נוסף על ערכות SDK ללקוח ל-web,‏ Android,‏ iOS ו-Flutter, וגם על Admin SDK ל-Node.js