بدء استخدام Firebase SQL Connect على Android

في هذا الدليل السريع، ستنشئ قاعدة بيانات صغيرة نموذجية وتنفّذها، ثم ستصل إليها من خلال تطبيق Android.

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

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

  • بيئة مثبَّت عليها الأدوات التالية:
    • إصدار حديث من استوديو Android
    • Firebase CLI إذا كانت حزمة NPM مثبَّتة، شغِّل الأمر التالي: 
      npm install -g firebase-tools@latest
       يمكنك الاطّلاع على المستندات للحصول على تعليمات التثبيت.
  • حساب Google

برنامج تعليمي

برنامج تعليمي

1. إنشاء مشروع جديد في "استوديو Android"

في "استوديو Android"، أنشئ مشروعًا جديدًا باستخدام نموذج نشاط فارغ.

أطلِق على المشروع اسم تطبيق Quickstart مع اسم الحزمة com.example.quickstartapp.

 مربّع حوار مشروع جديد في "استوديو Android"

2. إضافة Firebase إلى مشروعك في "استوديو Android"

أضِف التبعيات الخاصة بمنصة Firebase والمكوّن الإضافي لتسلسل Kotlin إلى ملفات build.gradle.kts.

 QuickstartApp/build.gradle.kts 
plugins {
  alias(libs.plugins.android.application) apply false
  alias(libs.plugins.kotlin.compose) apply false

  // Add this line.
  id("com.google.gms.google-services") version "4.4.4" apply false
}
 QuickstartApp/app/build.gradle.kts 
plugins {
  alias(libs.plugins.android.application)
  alias(libs.plugins.kotlin.compose)

  // Add these lines.
  kotlin("plugin.serialization") version libs.versions.kotlin
  id("com.google.gms.google-services")
}

// ...

dependencies {
  // ...

  // Add these lines.
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.11.0")
  implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.11.0")

  implementation(platform("com.google.firebase:firebase-bom:34.14.0"))
  implementation("com.google.firebase:firebase-dataconnect")
}

3- إعداد مشروع Firebase

انتقِل إلى دليل مشروع "استوديو Android" وأنشئ مشروع Firebase فيه.

 
cd ~/QuickstartApp
 
firebase login --reauth
 
firebase init dataconnect

عندما يُطلب منك ذلك، حدِّد الخيارات التالية:

  • أنشِئ مشروع Firebase جديدًا.
  • لا تنشئ مخططًا باستخدام Gemini (في هذا البرنامج التعليمي، ستستخدم مثالاً على مخطط تم إنشاؤه مسبقًا).
  • توفير مثيل وقاعدة بيانات Cloud SQL لفترة تجريبية مجانية

اقبل القيم التلقائية لجميع الطلبات الأخرى.

بعد ذلك، سجِّل تطبيق Android في مشروع Firebase.

firebase apps:create -a com.example.quickstartapp android android-quickstart
 
firebase apps:sdkconfig android -o app/google-services.json

4. مراجعة أمثلة على تعريفات GraphQL

في SQL Connect، يمكنك تحديد جميع مخططات قاعدة البيانات وعملياتها باستخدام GraphQL. عند إعداد مشروعك، أنشأ Firebase CLI بعض تعريفات الأمثلة لمساعدتك على البدء.

 dataconnect/schema/schema.gql (مقتطف) 
type Movie @table {
  title: String!
  imageUrl: String!
  genre: String
}

type MovieMetadata @table {
  movie: Movie! @unique
  rating: Float
  releaseYear: Int
  description: String
}
 dataconnect/example/queries.gql (مقتطف) 
query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
  }
}

5- نشر المخططات والعمليات

عند إجراء تغييرات على مخططات قاعدة البيانات أو طلبات البحث أو عمليات التعديل، عليك نشرها حتى يتم تطبيق التغييرات على قاعدة البيانات.

 
firebase deploy --only dataconnect

6. تعبئة قاعدة البيانات ببيانات نموذجية

ستمنحك بيانات البداية هذه شيئًا يمكنك الاطّلاع عليه عند اختبار نموذج التطبيق. يُرجى العِلم بأنّك في هذه الخطوة ستنفّذ رمز GraphQL عشوائيًا، وهو أمر مسموح به للمهام الإدارية.

 
firebase dataconnect:execute dataconnect/seed_data.gql

7. إنشاء حزمة تطوير برامج (SDK) لبرنامج Android

يستخدم هذا الأمر تعريفات GraphQL لإنشاء حزمة تطوير برامج (SDK) لعميل Android مخصّصة لقاعدة البيانات. يمكنك استخدام هذه المكتبة في تطبيق العميل لتنفيذ جميع عمليات قاعدة البيانات.

يمكنك إنشاء مكتبات لأنظمة أساسية متعددة، بما في ذلك Swift لنظام التشغيل iOS وJavaScript للويب وFlutter، وذلك عن طريق إضافة تعريفات إلى connector.yaml.

 
firebase dataconnect:sdk:generate
 حزمة تطوير البرامج (SDK) لنظام التشغيل Android التي يتم إنشاؤها تلقائيًا (مقتطف) 
public interface ExampleConnector : GeneratedConnector<ExampleConnector> {
  override val dataConnect: com.google.firebase.dataconnect.FirebaseDataConnect

  public val listMovies: ListMoviesQuery

  // ...
}

8. كتابة نموذج لعميل Android

يمكنك استبدال محتوى app/src/main/java/com/example/quickstartapp/MainActivity.kt بهذا التطبيق البسيط على Android.

لاحظ أنّ التطبيق يكمل عملية الوصول اللازمة إلى قاعدة البيانات باستخدام دالة من حزمة SDK التي تم إنشاؤها.

 
package com.example.quickstartapp

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import com.example.quickstartapp.ui.theme.QuickstartAppTheme
import com.google.firebase.dataconnect.generated.ExampleConnector
import com.google.firebase.dataconnect.generated.ListMoviesQuery
import com.google.firebase.dataconnect.generated.execute
import com.google.firebase.dataconnect.generated.instance

class MainActivity : ComponentActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    setContent {
      QuickstartAppTheme() {
        Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
          var movies by remember {
            mutableStateOf(emptyList<ListMoviesQuery.Data.MoviesItem>())
          }
          LaunchedEffect(Unit) {
            // Queries need to be executed in a coroutine context
            try {
              movies = ExampleConnector.instance.listMovies.execute().data.movies
            } catch (e: Exception) {
              // TODO: Handle error, e.g., show a Toast or update a state variable to
              //   display an error message.
            }
          }
          LazyColumn(modifier = Modifier.padding(innerPadding)) {
            items(movies) { movie ->
              Text(text = movie.title)
            }
          }
        }
      }
    }
  }
}

9. جرّب التطبيق

من "استوديو Android"، شغِّل تطبيق المثال لترى كيفية عمله.

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

جرِّب إضافة SQL Connect VS Code

عند التطوير باستخدام SQL Connect، ننصحك بشدة باستخدام إضافة SQL Connect في Visual Studio Code. حتى إذا لم تكن تستخدم Visual Studio Code كبيئة التطوير الأساسية، يوفّر لك هذا الامتداد العديد من الميزات التي تجعل عملية تطوير المخططات والعمليات أكثر ملاءمة:

  • خادم لغة GraphQL يوفّر عمليات التحقّق من البنية واقتراحات الإكمال التلقائي الخاصة بـ SQL Connect
  • أزرار CodeLens في سطر الرمز البرمجي تتيح لك قراءة البيانات وكتابتها من ملفات تعريف المخطط وتنفيذ طلبات البحث وعمليات التعديل من تعريفات العمليات.
  • الحفاظ على مزامنة حِزم SDK التي تم إنشاؤها تلقائيًا مع تعريفات GraphQL
  • إعداد مبسّط للمحاكي المحلي
  • نشر مبسّط للإصدار العلني

استخدام محاكي SQL Connect للتطوير المحلي

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

تعرَّف على كيفية كتابة المخططات والعمليات لتطبيقك

عند تطوير تطبيقات باستخدام SQL Connect، يُعد تصميم المخططات والعمليات من أولى مهام التطوير وأهمها التي ستُكملها.

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