דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

כדי להשתמש במדריך למתחילים הזה, תצטרכו את הדברים הבאים.

‫Visual Studio Code.
התקנה של Node.js, באמצעות nvm-windows ל-Windows או nvm ל-macOS או ל-Linux.
פרויקט Firebase. אם עדיין לא יצרתם חשבון, אתם יכולים לעשות זאת במסוף Firebase.

הגדרת סביבת הפיתוח

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

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

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

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

הערה: במסוף המשולב, מוודאים שהאמולטורים שהגדרתם מופעלים. אחרי שהם יפעלו, ממשק המשתמש של התוסף יעודכן עם פרטי האמולטור.

יצירת סכימה

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

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

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

לוחצים על סמל התוסף Data Connect VS Code כדי לפתוח את סרגל הצד שלו.
לוחצים על Try Gemini with @FirebaseDataConnect (ניסיון השימוש ב-Gemini עם @FirebaseDataConnect). ייפתח חלון הצ'אט Gemini Code Assist.
לוחצים על ממשק הצ'אט ומתחילים להקליד @FirebaseDataConnect כדי לסנן פקודות רלוונטיות.
בוחרים בפקודה /generate_schema ובחלון ההנחיה משלימים את הפקודה ומבקשים מ-Gemini ליצור סכימה לאפליקציה שאתם מפתחים.

לדוגמה:
```
@FirebaseDataConnect /generate_schema I want to build an app to track movie reviews from multiple users
```
אחרי כמה רגעים יופיע סכימה מומלצת. בודקים את הסכימה.

הערה: אם רוצים לשנות את הסכימה הראשונית, אפשר להריץ פקודה חדשה של @FirebaseDataConnect /generate_schema ולבקש מ-Gemini, לדוגמה, להסיר סוג מהסכימה או להוסיף שדות ספציפיים לסוג.
כדי להוסיף את הקוד ל-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 זמין במסמכי התיעוד

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

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

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

ב-schema.gql, לוחצים על הלחצן הוספת נתונים מעל הצהרת הסוג Movie.
בקובץ Movie_insert.gql שנוצר, מקודדים את הנתונים בשלושת השדות.
לוחצים על הלחצן הפעלה (מקומית).
חוזרים על השלבים הקודמים כדי להוסיף רשומה לטבלה MovieMetadata, ומזינים את id של הסרט בשדה movieId, כמו שמופיע בהנחיה במוטציה MovieMetadata_insert שנוצרה.

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

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

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

הגדרת שאילתה

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

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

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

לוחצים על סמל התוסף Data Connect VS Code כדי לפתוח את סרגל הצד שלו.
לוחצים על Try Gemini with @FirebaseDataConnect (ניסיון השימוש ב-Gemini עם @FirebaseDataConnect). ייפתח חלון הצ'אט Gemini Code Assist.
לוחצים על ממשק הצ'אט ומתחילים להקליד @FirebaseDataConnect כדי לסנן פקודות רלוונטיות.
בוחרים את הפקודה /generate_operation ובחלון ההנחיה, משלימים את הפקודה ומבקשים מ-Gemini ליצור שאילתה.

לדוגמה:
```
@FirebaseDataConnect /generate_operation List all movies with titles start with "A".
```
אחרי כמה רגעים תופיע שאילתה מומלצת. בודקים את השאילתה.

הערה: אם רוצים לשנות את השאילתה הראשונית, אפשר להריץ פקודה חדשה של @FirebaseDataConnect /generate_operation ולבקש מ-Gemini, לדוגמה, לסנן כותרות שמתחילות בספרות. אפשר גם לבקש ממנו ליצור כמה מוטציות באמצעות הוראה כמו "צור מוטציה לכל סוגי הסכימות שלי".
כדי להוסיף את הקוד ל-queries.gql:
1. לוחצים על הלחצן הוספה לתחתית הקובץ.
2. אפשר גם ללחוץ על הלחצן + בחלק העליון של תשובת הצ'אט כדי להוסיף את הקוד במיקום הסמן.

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

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

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

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

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

הערה: אם עדיין אין לכם ספריית אפליקציות, אתם יכולים ליצור ולבחור ספרייה חדשה לקוד ה-SDK בשלב הזה, ולקשר אותה לאפליקציה מאוחר יותר.
בוחרים את פלטפורמת האפליקציה, ושימו לב שקוד ה-SDK נוצר באופן מיידי בספרייה שבחרתם.

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

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

אינטרנט

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

בקובץ הראשי של אפליקציית 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

מוסיפים את Firebase לאפליקציה ל-iOS.
כדי להשתמש ב-SDK שנוצר, צריך להגדיר אותו כתלות ב-Xcode.

בסרגל הניווט העליון של Xcode, בוחרים באפשרות File > Add Package Dependencies > Add Local (קובץ > הוספת תלות בחבילה > הוספה מקומית), ובוחרים את התיקייה שמכילה את הקובץ Package.swift שנוצר.

בנציג הראשי של האפליקציה:

ייבוא של ערכת ה-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

מוסיפים את 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 שנוצרה
הגדרת האפליקציה לחיבור לאמולטור 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

מוסיפים את Firebase לאפליקציית Flutter.
מתקינים את flutterfire CLI dart pub global activate flutterfire_cli.
מריצים את flutterfire configure.
בפונקציה הראשית של האפליקציה:
- ייבוא של ערכת ה-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.

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

הערה: הקצאת המשאבים של מופע Cloud SQL ל-PostgreSQL עשויה להימשך עד 15 דקות. לא תוכלו לבצע פריסה עד שהמופע יהיה מוכן.
הערה: אם אתם רוצים להשתמש במפתחות הצפנה בניהול הלקוח (CMEK), הקפידו לבחור באפשרות Use existing Cloud SQL instance (שימוש במופע קיים של Cloud SQL) ולבחור מסד נתונים קיים של Cloud SQL עם CMEK.
בTerminal המשולב ב-IDE, מריצים את הפקודה firebase init dataconnect ובוחרים את מזהה האזור או השירות שיצרתם במסוף.
כשמופיעה ההודעה "File dataconnect/dataconnect.yaml already exists, Overwrite?" (הקובץ dataconnect/dataconnect.yaml כבר קיים, להחליף אותו?), בוחרים באפשרות Y.
בחלון IDE, בממשק המשתמש של התוסף VS Code, לוחצים על הלחצן Deploy to production (פריסה בסביבת ייצור).
אחרי הפריסה, נכנסים אל מסוף Firebase כדי לוודא שהסכימה, הפעולות והנתונים הועלו לענן. אפשר לראות את הסכימה ולהריץ את הפעולות במסוף. מכונת Cloud SQL for PostgreSQL תעודכן עם הסכימה והנתונים הסופיים שנוצרו ופרסנו.

השלבים הבאים

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

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

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

אתם יכולים להיעזר בהנחיות ובכלים נוספים מבוססי-AI כדי ליצור סכימות, שאילתות ומוטציות. במדריך לעזרה מבוססת-AI מוסבר איך להגדיר את שרת ה-MCP שלנו ולהשתמש בו עם סביבות הפיתוח המשולבות (IDE) שלכם ואיך לכתוב הנחיות בצורה הכי טובה.
מידע נוסף על פיתוח סכימות, שאילתות ומוטציות
במאמרים הבאים מוסבר איך ליצור ערכות SDK ללקוח ואיך לקרוא לשאילתות ולשינויים מקוד הלקוח עבור אינטרנט, Android,‏ iOS ו-Flutter.