تمت ترجمة هذه الصفحة بواسطة 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 طريقتَين لتثبيت أدوات التطوير والعمل على جهازك.

المتطلبات الأساسية

لاستخدام هذا الدليل السريع، ستحتاج إلى ما يلي.

مشروع على Firebase إذا لم يسبق لك إنشاء حساب، يمكنك إجراء ذلك في وحدة تحكّم Firebase.

إعداد بيئة التطوير

أنشئ دليلاً جديدًا لمشروعك المحلي.
لإعداد بيئة تطوير Data Connect وبيئة تطوير متكاملة (IDE) مستندة إلى المتصفّح، شغِّل الأمر التالي في الدليل الجديد الذي أنشأته.
```
curl -sL https://firebase.tools/dataconnect | bash
```
يحاول هذا النص البرمجي إجراء عملية التثبيت. يوفر بيئة التطوير المتكاملة (IDE) المثبّتة أدوات، بما في ذلك إضافات VS Code المجمّعة مسبقًا، لمساعدتك في إدارة المخطط وتحديد طلبات البحث وعمليات التعديل التي سيتم استخدامها في تطبيقك.

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

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

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

ملاحظة: في Terminal المدمج، تأكَّد من بدء تشغيل المحاكيات التي تم ضبطها. بعد تشغيلها، من المفترض أن تظهر لك واجهة مستخدم الإضافة معدَّلة لتتضمّن تفاصيل المحاكي.

إنشاء مخطط

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

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

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

انقر على رمز إضافة Data Connect في VS Code لفتح الشريط الجانبي.
انقر على تجربة 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 في المستندات

إضافة البيانات إلى جداولك

في لوحة محرّر بيئة التطوير المتكاملة، ستظهر أزرار 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 الناتج، انقر على الزر تشغيل (محلي) لتنفيذ طلب البحث.

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

تحديد طلب بحث

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

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

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

انقر على رمز إضافة Data Connect في VS Code لفتح الشريط الجانبي.
انقر على تجربة 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) واستخدامها في تطبيقك

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

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

ملاحظة: إذا لم يكن لديك دليل تطبيقات بعد، يمكنك إنشاء دليل جديد واختياره لرمز حزمة 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 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();
            }),
      )
    ])));
  }
}

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

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

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

ملاحظة: قد يستغرق توفير مثيل Cloud SQL for PostgreSQL ما يصل إلى 15 دقيقة. لن تتمكّن من النشر إلى أن يصبح مثيلك جاهزًا.
ملاحظة: إذا أردت استخدام مفاتيح التشفير المُدارة من العميل (CMEK)، احرص على اختيار استخدام مثيل Cloud SQL حالي واختيار قاعدة بيانات Cloud SQL حالية تتضمّن مفاتيح التشفير المُدارة من العميل.
في النافذة الطرفية المدمجة في بيئة التطوير المتكاملة، شغِّل firebase init dataconnect واختَر معرّف المنطقة/الخدمة الذي أنشأته للتو في وحدة التحكّم.
اختَر Y عند ظهور الرسالة "الملف dataconnect/dataconnect.yaml موجود بالفعل، هل تريد الكتابة فوقه؟".
في نافذة بيئة التطوير المتكاملة (IDE)، ضِمن واجهة مستخدم إضافة VS Code، انقر على الزر نشر إلى مرحلة الإنتاج.
بعد النشر، انتقِل إلى وحدة تحكّم Firebase للتحقّق من أنّه تم تحميل المخطط والعمليات والبيانات إلى السحابة الإلكترونية. من المفترض أن تتمكّن من عرض المخطط وتشغيل عملياتك على وحدة التحكّم أيضًا. سيتم تعديل مثيل Cloud SQL for PostgreSQL باستخدام المخطط والبيانات النهائية التي تم إنشاؤها ونشرها.

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

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

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

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

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