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

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

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

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

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

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

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

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

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

أطلِق على المشروع اسم Quickstart App مع اسم الحزمة 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 في it.

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/sequel/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 إلى VS 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, ثم انتقِل إلى الصفحات التالية للتعرّف على كيفية كتابة العمليات.