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

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

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

إنشاء مشروع Firebase وقاعدة بيانات Cloud SQL

  1. أنشئ مشروعًا على Firebase، إذا لم يسبق لك ذلك.
    1. في وحدة تحكّم Firebase، انقر على إضافة مشروع، ثم اتّبِع التعليمات الظاهرة على الشاشة.
  2. انتقِل إلى قسم Data Connect في وحدة تحكّم Firebase واتّبِع سير عمل إعداد المنتج.

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

  4. اختَر موقعًا لقاعدة بيانات Cloud SQL لنظام PostgreSQL.

  5. سجِّل أسماء المشروع والخدمة وقاعدة البيانات وأرقام تعريفها للتأكيد لاحقًا.

  6. اتّبِع خطوات الإعداد المتبقية، ثم انقر على تم.

اختيار مسار تطوير

يوفّر لك 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، في ملف /dataconnect/schema/schema.gql ، ابدأ بتحديد مخطّط GraphQL يتضمّن الأفلام.

فيلم

في 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
}

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 في المستندات

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

عليك نشر المخطّط قبل المتابعة.

في واجهة مستخدم الإضافة، ضِمن لوحة Firebase Data Connect، انقر على النشر في قناة الإصدار العلني.

بعد نشر المخطّط في قاعدة بيانات الإنتاج، من المفترض أن تتمكّن من عرض المخطّط في وحدة تحكّم Firebase.

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

في لوحة محرِّر IDE، يمكنك رؤية أزرار CodeLens تظهر فوق أنواع GraphQL في /dataconnect/schema/schema.gql. بما أنّك طرحت مخطّطك في قناة الإصدار العلني، يمكنك استخدام الزرَّين إضافة بيانات وتشغيل (الإصدار العلني) لإضافة بيانات إلى قاعدة بياناتك في الخلفية.

لإضافة سجلّات إلى جدول Movie:

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

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

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

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

تحديد طلب البحث

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

ابدأ بتعديل ملف /dataconnect/connector/queries.gql. إذا أردت الحصول على كل الأفلام، استخدِم طلب بحث مثل هذا.

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

# @auth() directives control who can call each operation.
# Anyone should be able to list all movies, so the auth level
# is set to PUBLIC
query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
  }
}

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

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

إنشاء حِزم SDK

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

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

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

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

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

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

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

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

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

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

الويب Swift ‫Kotlin Android Flutter
  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 />);
  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 ?? [], id: \.self.id) { movie in
                    Text(movie.title)
                }
            }
    }
    @MainActor
    func refresh() async throws {
        _ = try await queryRef.execute()
    }

    struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ListMovieView()
    }
}
  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 December 03, 2024.
  // Note, however, that the version of kotlin("plugin.serialization") must,
  // in general, match the version of kotlin("android").
  id("com.android.application") version "8.7.3"
  id("com.google.gms.google-services") version "4.4.2"
  val kotlinVersion = "2.1.0"
  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 December 03, 2024.
  implementation("com.google.firebase:firebase-dataconnect:16.0.0-beta03")
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
  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.9.3")
  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
      }
    }
  }
}
  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();
            }),
      )
    ])));
  }
}

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

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

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

  • اطّلِع على مزيد من المعلومات عن تطوير المخططات وطلبات البحث والطفرات.

  • اطّلِع على مزيد من المعلومات عن إنشاء حِزم تطوير برامج (SDK) للعملاء واستدعاء طلبات البحث والتغييرات من код العميل لالويب وAndroid وiOS وFlutter.