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

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

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

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

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

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

مسار Console: تصميم المخطّط ونشره في قاعدة البيانات

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

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

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

    يتم نشر مخطّط تطبيقك، بالإضافة إلى قاعدة بيانات PostgreSQL المقابلة لهذا المخطّط.

مسار وحدة التحكّم: استخدام 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. نفِّذ الأمر التالي في الدليل الجديد الذي أنشأته.

      curl -sL https://firebase.tools/dataconnect | bash

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

alias dataconnect='curl -sL https://firebase.tools/dataconnect | bash'

الخطوات المحلية: إعداد دليل المشروع

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

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

  3. انقر على الزر Run firebase init وأكمِل العملية.

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

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

أدّت الخطوة firebase init في القسم السابق إلى مزامنة المخطّط الذي تم نشره من وحدة التحكّم إلى بيئة التطوير المحلية.

ابحث عن المخطّط: يمكنك العثور عليه في دليل مشروع Firebase، في ملف /dataconnect/schema/schema.gql.

التدفق المحلي: العمل مع المخطّط

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

في 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. انقر على الزر Run (التنفيذ) (الإصدار العلني).
    زرّ &quot;تشغيل&quot; في Code Lens لخدمة Firebase Data Connect
  4. كرِّر الخطوات السابقة لإضافة سجلّ إلى الجداول الأخرى.

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

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

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

الخطوات المحلية: تحديد طلب البحث

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

لتنفيذ طلب بحث، يمكنك تعديل طلب تم إنشاؤه باستخدام أداة CodeLens:

  1. في /dataconnect/schema/schema.gql، فوق نوع (Movie أو Product أو Account أو غير ذلك)، انقر على زر قراءة البيانات في CodeLens.
  2. في ملف <type>_read.gql الناتج، اختبِر طلب البحث من خلال النقر على الزر تشغيل (الإصدار العلني).
  3. انسخ طلب البحث الذي يعمل بشكل صحيح إلى /dataconnect/connector/queries.gql.

  4. ليصبح هذا الطلب قابلاً للنشر، يجب تحديد اسم فريد له.

    على سبيل المثال، في المثال العام التالي، يمكن أن يكون query_name هو ListMovies أو ListProducts أو ListAccounts.

# File `/dataconnect/connector/queries.gql`

# @auth() directives control who can call each operation.
query <query_name> @auth(level: PUBLIC) {
   <table_name> {
     <field_1>
     <field_2>
     <field_3>
  }
}

نفِّذ الطلب باستخدام زر CodeLens القريب.

مزيد من المعلومات حول طلبات البحث في Data Connect في المستندات

الخطوات المحلية: إنشاء حِزم SDK

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

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

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

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

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

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

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

مزيد من المعلومات عن استخدام محاكي Data Connect في المستندات

العملية المحلية: استخدام حِزم SDK للاتّصال بطلب البحث من تطبيق

بعد نشر المخطّط المعدَّل (إن وُجد) وطلب البحث في مرحلة الإنتاج، يمكنك استخدام حزمة 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، اختَر ملف > إضافة متطلّبات الحزمة > إضافة ملف محلي، ثم اختَر المجلد الذي يحتوي على 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 CLI 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.

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