بدء استخدام 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.

المسار على الجهاز: إعداد بيئة التطوير

  1. أنشئ دليلاً جديدًا لمشروعك على الجهاز.
  2. افتح VS Code في الدليل الجديد.
  3. ثبِّت إضافة Firebase Data Connect من Visual Studio Code Marketplace.

إعداد دليل المشروع

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

  1. انقر على الزر تسجيل الدخول باستخدام حساب Google.
  2. انقر على الزر ربط مشروع Firebase واختَر المشروع الذي أنشأته سابقًا في وحدة التحكّم.
  3. انقر على الزر Run firebase init (تشغيل firebase init).

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

إنشاء مخطّط

في دليل مشروعك على Firebase، في ملف /dataconnect/schema/schema.gql ، ابدأ بتحديد مخطّط GraphQL حول مراجعات الأفلام مثلاً.

استخدام Gemini Code Assist لإنشاء مخطّط

لإنشاء مخطّط لتطبيق مراجعة الأفلام باستخدام Gemini Code Assist:

  1. انقر على رمز إضافة Data Connect في VS Code لفتح الشريط الجانبي.
  2. انقر على تجربة Gemini باستخدام @data-connect. ستفتح نافذة Gemini Code Assist chat.
  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 على نوعَي data primitiv: 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:

  1. في schema.gql، انقر على الزر إضافة بيانات أعلى Movie نوع بيان.
    زر &quot;إضافة بيانات&quot; في CodeLens لخدمة Firebase Data Connect
  2. في ملف Movie_insert.gql الذي يتم إنشاؤه، أدخِل البيانات في ملف ثابت لثلاثة حقول.
  3. انقر على الزر تشغيل (محلي).
    زرّ &quot;تشغيل&quot; في CodeLens لتطبيق Firebase Data Connect
  4. كرِّر الخطوات السابقة لإضافة سجلّ إلى جدول MovieMetadata، مع إدخال id لفيلمك في الحقل movieId، كما هو مطلوب في تحوُّل MovieMetadata_insert الذي تم إنشاؤه.

للتحقّق بسرعة من إضافة البيانات، اتّبِع الخطوات التالية:

  1. في schema.gql، انقر على الزر قراءة البيانات فوق بيان نوع Movie.
  2. في ملف Movie_read.gql الناتج، انقر على الزر تشغيل (محلي) ل ejecutant طلب البحث.

مزيد من المعلومات عن طفرات "ربط البيانات" في المستندات

تحديد طلب بحث

الآن، حان وقت الاستمتاع: حدِّد طلبات البحث التي ستحتاج إليها في تطبيقك. بصفتك مطوّرًا، اعتدت كتابة طلبات بحث SQL بدلاً من طلبات بحث GraphQL، لذا قد يبدو لك هذا الأمر مختلفًا بعض الشيء في البداية.

ومع ذلك، فإنّ GraphQL أكثر إيجازًا وأمانًا من لغة SQL الأوّلية. وتُسهّل إضافة VS Code تجربة التطوير، سواءً للطلبات أو التعديلات.

لإنشاء طلب بحث باستخدام Gemini Code Assist:

  1. انقر على رمز إضافة Data Connect في VS Code لفتح الشريط الجانبي.
  2. انقر على تجربة Gemini باستخدام @data-connect. ستفتح نافذة Gemini Code Assist chat.
  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. انقر على الزر إضافة حزمة تطوير البرامج (SDK) إلى التطبيق.

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

  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، اختَر ملف > إضافة متطلّبات حزمة > إضافة ملف محلي، ثم اختَر المجلد الذي يحتوي على 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. ثبِّت حزمة flutterfire CLI 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();
            }),
      )
    ])));
  }
}

نشر المخطّط وطلب البحث في قناة الإصدار العلني

بعد الانتهاء من الإعداد على الجهاز، يمكنك الآن نشر المخطّط والموصّل في السحابة الإلكترونية. يجب أن يكون لديك مشروع في خطة Blaze لإعداد مثيل Cloud SQL.

  1. انتقِل إلى قسم "ربط البيانات" في وحدة تحكّم Firebase وأنشئ مثيلًا مجانيًا في Cloud SQL.

  2. في وحدة التحكّم المدمجة في IDE، شغِّل firebase init dataconnect و اختَر رقم تعريف المنطقة/الخدمة الذي أنشأته للتو في وحدة التحكّم.

  3. اختَر "نعم" عندما يُطلب منك "ملف dataconnect/dataconnect.yaml يوجد حاليًا، هل تريد استبداله؟".

  4. في نافذة IDE، في واجهة مستخدم إضافة VS Code، انقر على الزر النشر في قناة الإصدار العلني.

  5. بعد نشر النموذج، انتقِل إلى وحدة تحكّم Firebase للتحقّق من تحميل المخطّط والعمليات والبيانات إلى السحابة الإلكترونية. من المفترض أن تتمكّن من عرض المخطّط وتنفيذ عملياتك على وحدة التحكّم أيضًا. سيتم تعديل مثيل Cloud SQL لـ PostgreSQL بالبيانات والمخطّط النهائيين المُنشئَين والمُنفَّذَين.

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

راجِع مشروعك المنشور واستكشِف المزيد من الأدوات:

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

يمكنك الاطّلاع على مزيد من المعلومات في المستندات. على سبيل المثال، بعد أن اكتملت الخطوة الأولى:

  • تعرَّف على المزيد من أدوات المساعدة المستندة إلى الذكاء الاصطناعي والإرشادات لمساعدتك في إنشاء المخططات والطلبات وعمليات التحويل. يتناول دليل المساعدة المستندة إلى الذكاء الاصطناعي أفضل الممارسات لكتابة الطلبات.
  • اطّلِع على مزيد من المعلومات عن تطوير المخططات وطلبات البحث والطفرات.
  • اطّلِع على مزيد من المعلومات عن إنشاء حِزم تطوير برامج (SDK) للعملاء واستدعاء طلبات البحث وعمليات التحويل من код العميل لالويب وAndroid وiOS وFlutter.