الإنشاء باستخدام Firebase Data Connect (لنظام التشغيل Android)

1. نظرة عامة

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

• كتابة مخطّط GraphQL لخدمة Firebase Data Connect
• كتابة طلبات البحث والطفرات
• تنفيذ مصادقة المستخدمين لتأمين بياناتك

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

• أحدث إصدار من استوديو Android
• محاكي Android بالمستوى 23 من واجهة برمجة التطبيقات أو إصدار أحدث

ما ستتعرّف عليه

• كيفية إعداد Firebase Data Connect باستخدام المحاكيات المحلية
• كيفية تصميم مخطّط بيانات باستخدام Data Connect وGraphQL
• كيفية كتابة طلبات البحث وعمليات التحويل لتطبيق مراجعات الأفلام
• كيفية إنشاء حزمة تطوير البرامج (SDK) لـ Kotlin واستخدامها في تطبيق Android
• (اختياري) كيفية نشر خدمة Data Connect في قناة الإصدار العلني

2- إعداد نموذج المشروع

إنشاء مشروع على Firebase

1. سجِّل الدخول إلى وحدة تحكُّم Firebase باستخدام حسابك على Google.
2. في وحدة تحكُّم Firebase، انقر على "إضافة مشروع".
3. أدخِل اسمًا لمشروعك على Firebase (على سبيل المثال، "مراجعة فيلم")، ثم انقر على "متابعة".
4. قد يُطلب منك تفعيل "إحصاءات Google"، ولكن لا يهمّ اختيارك لأغراض هذا الدليل التعليمي.
5. بعد دقيقة أو نحو ذلك، سيكون مشروعك على Firebase جاهزًا. انقر على "متابعة".

تنزيل الرمز

نفِّذ الأمر التالي لنسخ نموذج الرمز البرمجي لهذا الدليل التعليمي. سيؤدي ذلك إلى إنشاء دليل باسم codelab-dataconnect-android على جهازك:

git clone https://github.com/firebaseextended/codelab-dataconnect-android.git

إذا لم يكن لديك git على جهازك، يمكنك أيضًا تنزيل الرمز البرمجي مباشرةً من GitHub.

إضافة إعدادات Firebase

1. في وحدة تحكُّم Firebase، اختَر "نظرة عامة على المشروع" في شريط التنقّل الأيمن. انقر على زر Android لاختيار النظام الأساسي. عند طلب اسم حزمة، استخدِم com.google.firebase.example.dataconnect.
2. انقر على "تسجيل التطبيق" واتّبِع التعليمات لتنزيل ملف google-services.json ونقله إلى الدليل app/ للرمز الذي نزّلته للتو. بعد ذلك، انقر على "التالي".

3- إعداد Data Connect

تثبيت

التثبيت التلقائي

نفِّذ الأمر التالي في دليل codelab-dataconnect-android:

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

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

بعد تنفيذ النص البرمجي، من المفترض أن يتم فتح VS Code تلقائيًا.

ملاحظة: إذا كان لديك إصدار VS Code المخصّص للكمبيوتر المكتبي مثبَّتًا، من المفترض أن يفتحه النص البرمجي تلقائيًا. إذا تعذّر تنفيذ النص البرمجي، اتّبِع خطوات التثبيت اليدوي أدناه.

التثبيت اليدوي

1. تثبيت Visual Studio Code
2. تثبيت Node.js
3. في VS Code، افتح الدليل codelab-dataconnect-android.
4. ثبِّت إضافة Firebase Data Connect من Visual Studio Code Marketplace.

بدء Data Connect في المشروع

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

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

انقر على الزر Run firebase init واتّبِع الخطوات الواردة في وحدة التحكّم المدمجة.

ضبط إعدادات إنشاء حزمة SDK

بعد النقر على زر "تشغيل بدء Firebase"، من المفترض أن تبدأ إضافة Firebase Data Connect في إعداد دليل dataconnect/ نيابةً عنك.

في VS Code، افتح ملف dataconnect/connector/connector.yaml وستجد الإعدادات التلقائية. لتسهيل إنشاء تمثيل مرئي لإنشاء الرمز في هذا الدليل التعليمي، غيِّر connectorId إلى movies والحزمة إلى com.google.firebase.example.dataconnect.generated:

connectorId: movies
generate:
  kotlinSdk:
    outputDir: ../../app/src/main/java
    package: com.google.firebase.example.dataconnect.generated

لفهم ما تعنيه كل حالة من هذه الحالات:

• connectorId: اسم فريد لهذا الموصّل.
• ‫outputDir: مسار تخزين حِزمة تطوير البرامج (SDK) التي تم إنشاؤها من Data Connect هذا المسار نسبي إلى الدليل الذي يحتوي على ملف connector.yaml.
• package: اسم الحزمة الذي سيتم استخدامه في حزمة SDK التي تم إنشاؤها.

تشغيل محاكيات Firebase

في VS Code، انقر على الزر بدء المحاكيات.

من المفترض أن يظهر لك المحاكي قيد التشغيل في المحطة الطرفية المدمجة. إذا بدأ التطبيق بشكل صحيح، من المفترض أن يظهر لك ناتج بالشكل التالي:

ضبط تطبيق Android لاستخدام المحاكي المحلي

1. افتح "استوديو Android".
2. في شاشة الترحيب في Android Studio، انقر على الزر "فتح" واختَر الدليل codelab-dataconnect-android. انتظِر حتى تكتمل مزامنة Gradle.
3. بعد اكتمال مزامنة Gradle، افتح ملف app/src/main/java/com/google/firebase/example/dataconnect/MainActivity.kt واتصل بـ useEmulator():

import com.google.firebase.example.dataconnect.generated.MoviesConnector
import com.google.firebase.example.dataconnect.generated.instance

class MainActivity : ComponentActivity() {
  ...

  // Initialize Firebase Data Connect
  MoviesConnector.instance.dataConnect.useEmulator("10.0.2.2", 9399)

  ...
}

4. تحديد المخطّط وملء قاعدة البيانات مسبقًا

في هذا القسم، ستحدِّد بنية الكيانات الرئيسية في تطبيق الأفلام وعلاقاتها في مخطّط. يتمّ ربط كيانات مثل Movie وUser وReview بجداول قاعدة البيانات، مع إنشاء العلاقات باستخدام Firebase Data Connect وتوجيهات مخطّط GraphQL.

الكيانات والعلاقة الأساسية

يحتوي نوع Movie على تفاصيل رئيسية، مثل العنوان والنوع والعلامات، والتي يستخدمها التطبيق في عمليات البحث والملفات الشخصية للأفلام. يتتبّع النوع User تفاعلات المستخدمين، مثل المراجعات والعناصر المفضّلة. يربط تطبيق Review المستخدمين بالأفلام، ويسمح للتطبيق بعرض التقييمات والملاحظات التي ينشئها المستخدمون.

جدول المستخدمين

يحدِّد نوع المستخدِم عنصر مستخدِم يتفاعل مع الأفلام من خلال كتابة مراجعات أو إضافة الأفلام إلى المفضّلة.

في VS Code، افتح ملف dataconnect/schema/schema.gql وأزِل التعليق التوضيحي (أو أضِفه) من تعريف الجدول User:

# Users
# Suppose a user can leave reviews for movies
# user  -> reviews is a one to many relationship,
# movie -> reviews is a one to many relationship
# movie <-> user is a many to many relationship
type User @table {
  id: String! @col(name: "user_auth")
  username: String! @col(name: "username", dataType: "varchar(50)")
  # The following are generated by the user: User! field in the Review table
  # reviews_on_user 
  # movies_via_Review
}

جدول الأفلام

يحدِّد نوع Movie البنية الرئيسية لكيان الفيلم، بما في ذلك حقول مثل title وgenre وreleaseYear وrating.

في VS Code، افتح ملف dataconnect/schema/schema.gql وأزِل التعليق التوضيحي (أو أضِفه) من تعريف الجدول Movie:

# Movies
type Movie @table {
  # The below parameter values are generated by default with @table, and can be edited manually.
  # implies directive `@col(name: "movie_id")`, generating a column name
  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

جدول MovieMetadata

ينشئ نوع MovieMetadata علاقة مباشرة بنوع Movie. ويتضمن بيانات إضافية، مثل مخرج الفيلم.

في VS Code، افتح ملف dataconnect/schema/schema.gql وأزِل التعليق التوضيحي (أو أضِفه) من تعريف الجدول MovieMetadata:

# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata @table {
  # @unique indicates a 1-1 relationship
  movie: Movie! @unique 
  # movieId: UUID <- this is created by the above reference
  rating: Float
  releaseYear: Int
  description: String
}

جدول المراجعة

يمثّل نوع المراجعة عنصر المراجعة ويربط نوعَي "المستخدم" و"الفيلم" في علاقة بين عناصر متعددة (يمكن لمستخدم واحد نشر العديد من المراجعات، ويمكن أن يتضمّن كل فيلم العديد من المراجعات).

في VS Code، افتح ملف dataconnect/schema/schema.gql وأزِل التعليق التوضيحي (أو أضِفه) من تعريف الجدول Review:

# Reviews
type Review @table(name: "Reviews", key: ["movie", "user"]) {
  id: UUID! @default(expr: "uuidV4()")
  user: User!
  movie: Movie!
  rating: Int
  reviewText: String
  reviewDate: Date! @default(expr: "request.time")
}

الحقول والإعدادات التلقائية

يستخدم المخطّط عبارات مثل @default(expr: "uuidV4()") لإنشاء معرّفات وطابعات زمنية فريدة تلقائيًا. على سبيل المثال، يتم ملء حقل id في نوعَي "الفيلم" و"المراجعة" تلقائيًا بمعرّف فريد عالمي (UUID) عند إنشاء سجلّ جديد.

إدراج بيانات وهمية

بعد تحديد المخطّط، يمكنك الآن تعبئة قاعدة البيانات تلقائيًا ببيانات وهمية للاختبار.

1. في VS Code، افتح dataconnect/moviedata_insert.gql. تأكَّد من تشغيل المحاكيات في إضافة Firebase Data Connect.
2. من المفترض أن يظهر لك زر "تشغيل (على الجهاز)" في أعلى الملف. انقر على هذا الخيار لإدراج بيانات الفيلم النموذجية في قاعدة بياناتك.

3. اطّلِع على محطة تنفيذ "ربط البيانات" للتأكّد من أنّه تمت إضافة البيانات بنجاح.

بعد إضافة البيانات، انتقِل إلى الخطوة التالية للتعرّف على كيفية إنشاء طلبات بحث في "ربط البيانات".

5- إنشاء طلب بحث لعرض الأفلام

ابدأ بإنشاء طلب بحث لعرض الأفلام. لكل فيلم، ستسترجع id وtitle وimageUrl وgenre.

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

في VS Code، افتح ملف dataconnect/connector/queries.gql وأزِل التعليق التوضيحي (أو أضِفه) من طلب البحث ListMovies:

query ListMovies @auth(level: PUBLIC) {
  movies {
    id
    title
    imageUrl
    genre
  }
}

لاختبار طلب البحث الجديد، انقر على الزر "تنفيذ (محلي)" لتنفيذ طلب البحث في قاعدة البيانات المحلية. من المفترض أن تظهر قائمة الأفلام من قاعدة البيانات ضمن قسم "النتيجة" في محطة تنفيذ Data Connect.

الاتصال به من تطبيق Android

بعد اختبار طلب البحث في "محاكي Data Connect"، حان الوقت لإضافته إلى التطبيق.

في Android Studio، افتح ملف app/src/main/java/com/google/firebase/example/dataconnect/MoviesScreen.kt وأضِف الرمز البرمجي التالي لعرض قائمة الأفلام بتنسيق شبكة:

import com.google.firebase.example.dataconnect.generated.ListMoviesQuery
import com.google.firebase.example.dataconnect.generated.MoviesConnector
import com.google.firebase.example.dataconnect.generated.execute
import com.google.firebase.example.dataconnect.generated.instance

@Composable
fun MoviesScreen(
    onMovieClicked: (id: String) -> Unit
) {
    var movies by remember { mutableStateOf(emptyList<ListMoviesQuery.Data.MoviesItem>()) }
    LaunchedEffect(Unit) {
        // Queries need to be executed in a coroutine context
        try {
          movies = MoviesConnector.instance.listMovies.execute().data.movies
        } catch (e: Exception) {
          // Will be done at a later step
        }
    }
    LazyVerticalGrid(GridCells.Adaptive(150.dp)) {
        items(movies) { movie ->
            MovieCard(
                movieId = movie.id.toString(),
                movieTitle = movie.title,
                movieImageUrl = movie.imageUrl,
                movieGenre = movie.genre,
                onMovieClicked = {
                    onMovieClicked(movie.id.toString())
                }
            )
        }
    }
}

تشغيل التطبيق

في Android Studio، انقر على الزر "تشغيل" لتشغيل التطبيق في محاكي Android.

بعد تشغيل التطبيق، من المفترض أن تظهر لك شاشة بالشكل التالي:

6- إنشاء طلب بحث عن تفاصيل الفيلم

الآن بعد أن أصبح بإمكان التطبيق عرض الأفلام، لننشئ طلب بحث لعرض تفاصيل كل فيلم.

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

في VS Code، افتح ملف dataconnect/connector/queries.gql وأزِل التعليق التوضيحي (أو أضِفه) من طلب البحث GetMovieById:

# Get movie by id
query GetMovieById($id: UUID!) @auth(level: PUBLIC) {
  movie(id: $id) {
    id
    title
    imageUrl
    genre
    metadata: movieMetadata_on_movie {
      rating
      releaseYear
      description
    }
    reviews: reviews_on_movie {
      id
      reviewText
      reviewDate
      rating
      user {
        id
        username
      }
    }
  }
}

الاتصال به من تطبيق Android

في "استوديو Android"، افتح ملف app/src/main/java/com/google/firebase/example/dataconnect/MovieDetailScreen.kt وأضِف الرمز التالي:

importcom.google.firebase.example.dataconnect.generated.GetMovieByIdQuery
importcom.google.firebase.example.dataconnect.generated.MoviesConnector
importcom.google.firebase.example.dataconnect.generated.execute
importcom.google.firebase.example.dataconnect.generated.instance

@Composable
fun MovieDetailScreen(
    movieId: String
) {
    var movie by remember { mutableStateOf<GetMovieByIdQuery.Data.Movie?>(null) }
    LaunchedEffect(Unit) {
        movie = MoviesConnector.instance.getMovieById.execute(
            UUID.fromString(movieId)
        ).data.movie
    }
    if (movie == null) {
        LoadingScreen()
    } else {
        MovieDetails(
            movieTitle = movie!!.title,
            movieImageUrl = movie!!.imageUrl,
            movieGenre = movie!!.genre,
            movieRating = movie!!.metadata?.rating,
            movieReleaseYear = movie!!.metadata?.releaseYear,
            movieDescription = movie!!.metadata?.description,
        )
    }
}

تشغيل التطبيق

في Android Studio، انقر على الزر "تشغيل" لتشغيل التطبيق في محاكي Android.

7. أنشئ عملية تعديل لإدراج المستخدمين.

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

لأغراض هذا الدليل التعليمي، يستخدم التطبيق المصادقة المجهولة لتسجيل المستخدمين، ولكن للحصول على تطبيق أكثر أمانًا، ننصحك باستخدام طريقة مصادقة مختلفة، مثل مصادقة البريد الإلكتروني/كلمة المرور أو موفِّر هوية موحَّد.

تحديد الطفرة

في VS Code، افتح ملف dataconnect/connector/mutations.gql وأزِل التعليق التوضيحي (أو أضِفه) من طلب البحث UpsertUser:

# Upsert (update or insert) a user's username based on their auth.uid
mutation UpsertUser($username: String!) @auth(level: USER) {
  user_upsert(
    data: {
      id_expr: "auth.uid"
      username: $username
    }
  )
}

الاتصال به من تطبيق Android

في Android Studio، افتح ملف app/src/main/java/com/google/firebase/example/dataconnect/MainActivity.kt واطلب الطفرة:

import com.google.firebase.example.dataconnect.generated.execute

LaunchedEffect(Unit) {
  // If there's no user signed in, sign in an anonymous user
  if (firebaseAuth.currentUser == null) {
    firebaseAuth.signInAnonymously().await()
    val newUsername = getRandomUsername()
    MoviesConnector.instance.upsertUser.execute(newUsername)
  }
}

تشغيل التطبيق

في Android Studio، انقر على الزر "تشغيل" لتشغيل التطبيق في محاكي Android.

8. تهانينا

نبارك لك على إضافة Firebase Data Connect بنجاح إلى تطبيق Android.

الآن، لديك فكرة عن الخطوات الرئيسية المطلوبة لإعداد Data Connect وإنشاء طلبات البحث والتغييرات ومعالجة مصادقة المستخدم.

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

• مزيد من المعلومات عن الأسعار
• مزيد من المعلومات عن تأمين العمليات
• النشر في قناة الإصدار العلني (القسم التالي)
• تعرَّف على كيفية إجراء بحث تشابه متجهات.

اختياري: النشر في قناة الإصدار العلني

حتى الآن، لم يستخدم هذا التطبيق سوى محاكيات Firebase. إذا كنت تريد معرفة كيفية نشر هذا التطبيق في مشروع حقيقي على Firebase، انتقِل إلى الخطوة التالية.

9. (اختياري) نشر تطبيقك

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

تفعيل ميزة "مصادقة Firebase"

في "وحدة تحكّم Firebase"، انتقِل إلى قسم "المصادقة" وانقر على "البدء". انتقِل إلى علامة التبويب "طريقة تسجيل الدخول" واختَر خيار "تسجيل الدخول بدون إظهار الهوية" من بين مقدّمي الخدمة.

فعِّل طريقة تسجيل الدخول بدون إظهار الهوية وانقر على "حفظ".

نشر مخطّط Firebase Data Connect

ملاحظة مهمة: إذا كانت هذه هي المرة الأولى التي يتم فيها نشر مخطّط في مشروعك، ستؤدي هذه العملية إلى إنشاء مثيل PostgreSQL على Cloud SQL، ما قد يستغرق 15 دقيقة تقريبًا. لن تتمكّن من النشر إلى أن يصبح مثيل Cloud SQL جاهزًا ومدمجًا مع Firebase Data Connect.

1. في واجهة مستخدم إضافة Firebase Data Connect في VS Code، انقر على النشر في قناة الإصدار العلني.
2. قد تحتاج إلى مراجعة تغييرات المخطط والموافقة على التعديلات التي قد تكون مدمرة. سيُطلب منك تنفيذ ما يلي:
   • مراجعة تغييرات المخطط باستخدام firebase dataconnect:sql:diff
   • عندما تكون التغييرات مناسبة لك، طبِّقها باستخدام المسار الذي بدأه firebase dataconnect:sql:migrate.

سيتم تعديل آلة Cloud SQL لنظام PostgreSQL الافتراضية باستخدام المخطّط والبيانات النهائيَين اللذَين تم نشرهما. يمكنك مراقبة الحالة في "وحدة تحكّم Firebase".

يمكنك الآن النقر على "تشغيل (الإصدار العلني)" في لوحة Firebase Data Connect، تمامًا كما فعلت مع المحاكيات المحلية، لإضافة البيانات إلى بيئة الإصدار العلني.