بدء استخدام Firebase Data Connect

في هذا الدليل السريع، ستتعرّف على كيفية إنشاء Firebase Data Connect في تطبيقك باستخدام مثيل SQL مخصّص للإنتاج.

في وحدة تحكّم Firebase، عليك إجراء ما يلي:

  • أضِف Firebase Data Connect إلى مشروعك على Firebase.
  • أنشئ مخططًا لتطبيق باستخدام ميزة إنشاء المخططات المستندة إلى الذكاء الاصطناعي في وحدة تحكّم Firebase، ثمّ نفِّذه.
  • توفير مثيل Cloud SQL لتطبيقك
  • باستخدام "Gemini في Firebase"، يمكنك ملء قاعدة البيانات ببيانات نموذجية.
  • يمكنك إنشاء طلبات وعمليات تغيير، مع إنشاء عمليات بمساعدة الذكاء الاصطناعي، ويمكنك نشرها واستخدامها لتطوير رمز العميل محليًا.

بعد ذلك، في بيئة التطوير المحلية، عليك إجراء ما يلي:

  • إعداد أدوات التطوير، بما في ذلك إضافة Visual Studio Code، للعمل مع مثيل الإنتاج
  • يمكنك مزامنة بيئتك المحلية مع مواد العرض التي أنشأتها في وحدة التحكّم.
  • إنشاء حِزم SDK ذات أنواع محددة واستخدامها في تطبيقك

مسار وحدة التحكّم: استخدام ميزة "المساعدة المستندة إلى الذكاء الاصطناعي" لتصميم المخطط، ثم نشره في قاعدة البيانات

  1. أنشئ مشروعًا على Firebase، إذا لم يسبق لك ذلك.
    1. في Firebaseوحدة التحكّم، انقر على إضافة مشروع، ثم اتّبِع التعليمات الظاهرة على الشاشة.
  2. انتقِل إلى القسم Data Connect في وحدة تحكّم Firebase.
  3. انقر على زر بدء استخدام Gemini.
  4. في لوحة سير العمل أداة إنشاء المخطط التي تظهر، صف تطبيقًا كي يساعدك Gemini في إنشاء مخطط GraphQL.
  5. راجِع مخطط GraphQL، ثم انقر على الترقية والنشر.

  6. رقِّي مشروعك إلى خطة Blaze. يتيح لك ذلك إنشاء مثيل Cloud SQL لـ PostgreSQL.

  7. اختَر إنشاء مثيل Cloud SQL جديد. في مربّع الحوار الذي يظهر، اختَر موقعًا جغرافيًا وتسمية لقاعدة بيانات Cloud SQL for PostgreSQL.

    يتم نشر مخطط تطبيقك مع قاعدة بيانات PostgreSQL تتوافق مع هذا المخطط.

مسار وحدة التحكّم: استخدام ميزة "المساعدة المستندة إلى الذكاء الاصطناعي" لإنشاء عمليات لعملائك

بعد نشر المخطط، يمكنك اتّخاذ الخطوات الأولى لإتاحة الوصول إلى هذه البيانات من تطبيقات العميل من خلال إنشاء رابط للاستعلامات والتعديلات لنشره في الخلفية، ثم استدعائه من العملاء لاحقًا.

تتوفّر أدوات المساعدة المستندة إلى الذكاء الاصطناعي لمساعدتك.

  1. عندما يُطلب منك ذلك، انقر على الزر إنشاء عمليات باستخدام Gemini.

  2. بعد بضع لحظات، في لوحة سير العمل إنشاء العمليات التي تظهر، راجِع قائمة طلبات البحث وعمليات التعديل التي يقدّمها Gemini استنادًا إلى المخطط.

  3. انقر على كل صف عملية لمراجعة رمز GraphQL الذي يحدّد تلك العملية. إذا لزم الأمر، استخدِم عنصر التحكّم الخاص بسلة المهملات لحذف العمليات التي لا تحتاج إليها.

  4. لإضافة عمليات، انقر على الزر + إضافة. بعد ذلك:

    1. قدِّم وصفًا لعمليتك بلغة طبيعية.

      على سبيل المثال:

      List all products

    2. راجِع GraphQL الذي تم إنشاؤه.

    3. إذا كانت العملية مقبولة، انقر على إدراج لإضافتها إلى قائمة العمليات.

  5. واصِل إزالة العمليات وإضافتها إلى أن تصبح مجموعة العمليات مقبولة.

  6. لنشر قائمة العمليات هذه كمجموعة موصلات يمكن استدعاؤها من العميل، اختَر اسم الموصل، ثم انقر على نشر.

مسار Console: استخدام Gemini في Firebase لإنشاء تغيير وتعبئة قاعدة البيانات

من خلال إكمال الخطوات السابقة، أنشأت Data Connect مخططًا يتألف من أنواع الكيانات ذات الصلة، ونشرته في مرحلة الإنتاج، ما يعني أنّه تم أيضًا إنشاء قاعدة بيانات PostgreSQL تتضمّن جداول مطابقة ونشرها.

لملء قاعدة البيانات، يمكنك استخدام Gemini في Firebase لمساعدتك في تحويل مدخلاتك باللغة الطبيعية إلى تعديل في GraphQL لتعديل أحد جداولك وطلب بحث لتأكيد تعديلاتك.

  1. افتح علامة التبويب البيانات.

  2. انقر على رمز ساعدني في كتابة GraphQL pen_spark وفي المربّع الذي يظهر، اكتب الإدخال.

    على سبيل المثال:

    Add data for three sample products to my app.

  3. انقر على إنشاء. يتم عرض التغيير.

  4. راجِع الناتج. إذا لزم الأمر، انقر على تعديل لتحسين الطلب، ثم انقر على إعادة إنشاء.

  5. بعد ذلك، انقر على إدراج لإدراج التغيير في أداة تعديل البيانات.

  6. انقر على تشغيل.

عند تنفيذ عملية التغيير، تتم كتابة البيانات في الجدول المناسب في قاعدة بيانات PostgreSQL. يمكنك إنشاء طلب بحث في وحدة التحكّم لعرض البيانات المخزّنة باتّباع الخطوات التالية:

  1. كرِّر الخطوات السابقة باستخدام ساعدني في كتابة GraphQL pen_spark لإنشاء طلب بحث.

  2. في المربّع الذي يظهر، اكتب الإدخال.

    على سبيل المثال:

    Query data for all sample products in my app.

  3. انقر على إنشاء، ثم على تشغيل.

مسار التطوير المحلي: اختيار أدوات التطوير

بعد أن أصبحت لديك بيانات في قاعدة البيانات التي تم نشرها، وبعد أن نشرت موصّلاً، يمكنك مواصلة تطوير المخطط والموصّلات في بيئة التطوير المحلية.

أولاً، عليك إعداد بيئة محلية. توفّر لك Data Connect طريقتَين لتثبيت أدوات التطوير.

المسار المحلي: إعداد بيئة التطوير

  1. أنشئ دليلاً جديدًا لمشروعك المحلي.

  2. لإعداد Data Connect بيئة تطوير وبيئة تطوير متكاملة مستندة إلى المتصفّح وإنشاء حِزم SDK للعملاء، شغِّل الأمر التالي في الدليل الجديد الذي أنشأته.

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

    يحاول هذا النص البرمجي إجراء عملية التثبيت. توفر بيئة التطوير المتكاملة (IDE) المثبَّتة أدوات، بما في ذلك إضافات VS Code المجمَّعة مسبقًا، لمساعدتك في إدارة المخطط وتحديد طلبات البحث وعمليات التعديل التي سيتم استخدامها في تطبيقك، وإنشاء حِزم SDK ذات أنواع محددة بدقة.

    يعمل النص البرمجي أيضًا على مزامنة مواد العرض التي أنشأتها في وحدة تحكّم Firebase مع الدليل المحلي، كما ينشئ حِزم SDK للعملاء لأي تطبيقات سجّلتها في مشروعك.

التدفق المحلي: إعداد مشروعك المحلي

لإعداد مشروعك المحلي، عليك تهيئة دليل المشروع. في نافذة بيئة التطوير المتكاملة (IDE)، انقر على رمز Firebase في اللوحة اليمنى لفتح واجهة مستخدم إضافة Data Connect VS Code:

  1. انقر على الزر بدء المحاكيات.

المسار المحلي: العثور على المخطط والموصّل في البيئة المحلية

يؤدي خيار التثبيت التلقائي لنظام التشغيل macOS أو Linux الذي استخدمته لمزامنة مواد العرض مع مشروع حالي إلى حدوث ما يلي:
  • تتم مزامنة المخطّط الذي نشرته
    • ابحث عن المخطط الخاص بك: يقع في دليل مشروعك على Firebase، في الملف /dataconnect/schema/schema.gql.
  • تتم مزامنة طلبات البحث وعمليات التعديل في الموصّل الذي نشرته
    • ابحث عن أداة الربط: تقع العمليات في دليل مشروعك على Firebase، ضمن الدليل /dataconnect/connector/.

المخطط المحلي: فهم المخطط

مثال على المخطط: فيلم

في Data Connect، يتم ربط حقول GraphQL بالأعمدة. من المحتمل أن يتضمّن النوع Movie id وtitle وimageUrl وgenre. يتعرّف Data Connect على نوعَي البيانات الأساسيَّين String وUUID.

# File `/dataconnect/schema/schema.gql`

# By default, a UUID id key will be created by default as primary key.
type Movie @table {
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

مثال على المخطط 1:1: MovieMetadata

باستخدام الأفلام، يمكنك تصميم بيانات وصفية للأفلام.

على سبيل المثال، في schema.gql، يمكنك إضافة المقتطف التالي أو رمز المراجعة الذي تم إنشاؤه بواسطة Gemini.

# 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. وكما فعلت في وحدة التحكّم، يمكنك إنشاء عملية تغيير لإضافة بيانات إلى قاعدة بيانات الإنتاج.

لإضافة بيانات إلى جدول، اتّبِع الخطوات التالية:

  1. في schema.gql، انقر على الزر إضافة بيانات أعلى بيان الإفصاح الخاص بأحد أنواع البيانات (مثل Movie أو Product أو Account، حسب طبيعة تطبيقك).
    زر &quot;إضافة بيانات&quot; في Code Lens لخدمة Firebase Data Connect
  2. يتمّ إضافة ملف جديد، <type>_insert.qgl، إلى دليل العمل، مثل Movie_insert.gql أو Product_insert.gql. إدخال البيانات بشكل ثابت في الحقول الخاصة بهذا النوع
  3. انقر على الزر تشغيل (في مرحلة الإنتاج).
    زر &quot;تشغيل&quot; Code Lens في Firebase Data Connect
  4. كرِّر الخطوات السابقة لإضافة سجلّ إلى جداول أخرى.

للتأكّد بسرعة من أنّه تمّت إضافة البيانات، اتّبِع الخطوات التالية:

  1. بالعودة إلى schema.gql، انقر على الزر قراءة البيانات أعلى تعريف النوع.
  2. في ملف <type>_read.gql الناتج، مثل Product_read.gql، انقر على الزر تشغيل (الإنتاج) لتنفيذ طلب البحث.

مزيد من المعلومات حول عمليات تغيير Data Connect في المستندات

المسار المحلي: إنشاء حِزم SDK

تتم مزامنة عمليات المخطط والموصل محليًا.

يمكنك الآن استخدام إضافة VS Code لإنشاء حِزم SDK للعملاء من أجل بدء تنفيذ طلبات البحث وعمليات التعديل في تطبيقات iOS وAndroid والويب وFlutter.

  1. في واجهة مستخدم الإضافة، انقر على الزر إضافة حزمة تطوير برامج (SDK) إلى التطبيق.

  2. في مربّع الحوار الذي يظهر، اختَر دليلاً يحتوي على الرمز البرمجي لتطبيقك. سيتم إنشاء الرمز البرمجي لحزمة تطوير البرامج (SDK) وحفظه هناك.Data Connect

  3. اختَر نظام تشغيل تطبيقك، ثم لاحظ أنّه يتم إنشاء رمز حزمة SDK على الفور في الدليل الذي اخترته.

المسار المحلي: استخدام حِزم SDK لطلب البحث من تطبيق

في السابق، نشرت المخطط والعمليات في وحدة تحكّم Firebase. لاستدعاء عمليات من تطبيقك، يمكنك استخدام حزمة SDK التي تم إنشاؤها Data Connect لتنفيذ عملية استدعاء لطلب البحث ListMovies.

الويب

  1. أضِف Firebase إلى تطبيقك على الويب.

  2. في الملف الرئيسي لتطبيق React، اتّبِع الخطوات التالية:

    • استيراد حزمة SDK التي تم إنشاؤها
    • استدعاء طرق Data Connect
    import React from 'react';
import ReactDOM from 'react-dom/client';

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

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

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

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 dart pub global activate flutterfire_cli.
  3. نفِّذ الأمر flutterfire configure.
  4. في الدالة الرئيسية لتطبيقك:
    • استيراد حزمة SDK التي تم إنشاؤها
    • استدعاء طرق 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,
  );
  
  
  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();
            }),
      )
    ])));
  }
}

الخطوات التالية

راجِع مشروعك الذي تم نشره واطّلِع على المزيد من الأدوات:

  • يمكنك إضافة بيانات إلى قاعدة البيانات وفحص المخططات وتعديلها وتتبُّع خدمة Data Connect في وحدة تحكّم Firebase.

يمكنك الاطّلاع على مزيد من المعلومات في المستندات. على سبيل المثال، بعد إكمال دليل التشغيل السريع، يمكنك إجراء ما يلي: