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

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

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

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

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

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

    הסקריפט מתקין את Firebase CLI ואת התוסף Data Connect VS Code, ומנחה אתכם firebase init dataconnect להגדרת הפרויקט. אם לא התקנתם את VS Code desktop, הסקריפט ייפתח בדפדפן.

    curl -sL https://firebase.tools/init/dataconnect | editor=true bash
  2. פותחים את המסך של התוסף Data Connect VS Code על ידי לחיצה על סמל Firebase בחלונית הימנית של Visual Studio Code.

  3. לוחצים על 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

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

בהגדרת ברירת המחדל, אפשר למצוא את השאילתות והמוטציות של Data Connect בספרייה dataconnect/example/.

אפשר לשאול שאילתות מדויקות על נתונים יחסיים באמצעות שאילתות מקוננות.

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

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

firebase init dataconnect באופן אוטומטי מגדיר ערכות SDK בטוחות לטיפוסים עבור אפליקציות בפרויקט. במידת הצורך, אפשר להוסיף את ה-SDK באופן ידני באמצעות הלחצן Add SDK to app (הוספת SDK לאפליקציה) בתוסף VS Code או על ידי הפעלת firebase init dataconnect:sdk.

אינטרנט

  1. מוסיפים את Firebase לאפליקציית האינטרנט.
  2. בקובץ הראשי של אפליקציית 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

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

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

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

    • מייבאים את 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)
      
    • הפעלת methods של 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. מוסיפים את 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 שנוצר:
    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

  1. מוסיפים את Firebase לאפליקציית Flutter.
  2. מתקינים את flutterfire CLI dart pub global activate flutterfire_cli.
  3. מריצים את flutterfire configure.
  4. בפונקציה הראשית של האפליקציה:

    • מייבאים את ה-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();
                }),
          )
        ])));
      }
    }
    

פריסה בסביבת הייצור

כדי לפרוס את הסכימה, השאילתות והמוטציות בסביבת הייצור:

  1. משדרגים את הפרויקט ב-Firebase לתוכנית Blaze.

  2. לוחצים על הלחצן Deploy to production (פריסה בסביבת הייצור) בתוסף Data Connect VS Code או מריצים את הפקודה במסוף:

    firebase deploy --only dataconnect
    

    אחרי הפריסה, נכנסים אל מסוף Firebase כדי לראות את הסכימה ולהריץ שאילתות ושינויים.

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

השלבים הבאים

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