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

ملاحظة: تم إطلاق ميزات تجريبية متاحة للجميع من Firebase Data Connect. تخضع Data Connect "لأحكام العروض لمرحلة ما قبل التوفّر للجمهور العام" في القسم الأحكام الخاصة بالخدمة من بنود خدمة Google Cloud Platform. تتوفّر الميزات المتوفّرة قبل طرحها للجمهور "على وضعها الحالي" وقد تكون متوفّرة لفريق دعم محدود. لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق.

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

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

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

يمكنك العثور على مستودع تطبيقات للبدء السريع وإنشاء تطبيق Data Connect كامل الميزات باتّباع الدرس التطبيقي حول الترميز المخصّص للويب في . ستتوفّر قريبًا ورشات Codelabs لنظامَي التشغيل Android وiOS.

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

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

• نظام التشغيل Linux أو macOS أو Windows
• Visual Studio Code

الربط بمشروعك على Firebase

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

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

   ملاحظة: على الرغم من إعداد الفوترة في عملية ترقية Blaze، لن يتم تحصيل رسوم منك مقابل استخدام Data Connect أو الإعداد التلقائي لخدمة Cloud SQL لـ PostgreSQL أثناء فترة المعاينة.

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

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

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

   ملاحظة: قد يستغرق إنهاء توفير مثيل Cloud SQL لقاعدة بيانات MySQL مدة تصل إلى 15 دقيقة. يمكنك التأكّد من اكتمال عملية إعداد Data Connect، بما في ذلك توفير قاعدة البيانات، باستخدام وحدة تحكّم Google Cloud.

اختيار بيئة تطوير وإعدادها

يتيح Data Connect تجربتَي تطوير:

• إذا كنت من مطوّري Kotlin Android أو iOS أو Flutter أو الويب، يمكنك استخدام تطوير VS Code لتصميم المخططات والعمليات واختبارها على الجهاز أثناء الاتصال بمثيل Cloud SQL لنظام PostgreSQL.
• إذا كنت من مطوّري الويب، يمكنك استخدام تطوير IDX لإنشاء نماذج أولية في مساحة عمل IDX باستخدام نموذج IDX تم إعداده مسبقًا مع PostgreSQL، وإضافة VS Code مع محاكي Data Connect، ورمز العميل لبدء الاستخدام السريع الذي تم إعداده نيابةً عنك. يمكنك العثور على مزيد من المعلومات على موقع Project IDX الإلكتروني.

يركز دليل البدء السريع هذا على عملية تطوير إضافات VS Code. للمتابعة:

1. أنشئ دليلاً جديدًا لمشروعك على الجهاز.
2. افتح VS Code في الدليل الجديد.

3. ثبِّت إضافة Firebase Data Connect من Visual Studio Code Marketplace.

   ملاحظة: تتضمّن الإضافة إضافة تمييز بنية GraphQL في السوق. قد تتعارض إضافات GraphQL الأخرى التي تثبّتها مع ميزة GraphQL المضمّنة في إضافة Firebase Data Connect.

إعداد مشروعك المحلي

ملاحظة: إذا كنت لا تستخدم IDX، اتّبِع الخطوات الواردة في هذا القسم.

ثبِّت واجهة برمجة التطبيقات باتّباع التعليمات العادية. إذا سبق لك تثبيت npm ، شغِّل الأمر التالي:

npm install -g firebase-tools

ملاحظة: إذا كنت تستخدم إصدارًا حاليًا من واجهة برمجة التطبيقات، تأكَّد من التحديث إلى أحدث إصدار.

إعداد دليل المشروع

لإعداد مشروعك على الجهاز، عليك بدء دليل المشروع.

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

1. انقر على الزر تسجيل الدخول باستخدام حساب Google.
2. انقر على الزر ربط مشروع Firebase واختَر المشروع الذي أنشأته سابقًا في وحدة التحكّم.
3. انقر على الزر Run firebase init (تشغيل firebase init).
4. إذا كان مشروعك مُدرَجًا في خطة Blaze، عندما يُطلب منك معرفة ما إذا كنت تريد ضبط موارد الخلفية الآن؟، يجب الإجابة "نعم".

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

   ملاحظة: في Terminal المدمج، تأكَّد من بدء تشغيل المحاكيات التي تم ضبطها. بعد تشغيلهما، من المفترض أن ترى واجهة مستخدم الإضافة محدَّثة مع تفاصيل المحاكي.

إنشاء مخطّط

في دليل مشروعك على 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 VS Code للعمل مع قاعدة بيانات الإنتاج، عليك نشر المخطّط قبل المتابعة. بعد نشر المخطّط في قاعدة بيانات الإنتاج، من المفترض أن تتمكّن من عرض المخطّط في وحدة التحكّم.

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

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

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

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

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

1. في schema.gql، انقر على الزر إضافة بيانات أعلى Movie نوع بيان.
   
2. في ملف Movie_insert.gql الذي يتم إنشاؤه، أدخِل البيانات في ملف ثابت ل الحقول الأربعة.
3. انقر على الزر Run (التنفيذ) (الإصدار العلني).
   
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 القريب.

ملاحظة: يمكنك استخدام Gemini في Firebase لمساعدتك في إنشاء طلبات بحث GraphQL واختبارها في وحدة تحكّم Firebase. اطّلِع على مزيد من المعلومات في مقالة استخدام مساعدة الذكاء الاصطناعي في طلبات البحث والطفرات.

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

إنشاء حِزم تطوير برامج (SDK) واستخدامها في تطبيقك

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

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

   ملاحظة: إذا لم يكن لديك دليل تطبيقات حتى الآن، يمكنك إنشاء ملف تعريف جديد لشفرة حزمة SDK وتحديده في الوقت الحالي وربطه بتطبيقك لاحقًا.

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

تعرَّف على كيفية استخدام حزمة تطوير البرامج (SDK) التي تم إنشاؤها للاتّصال بطلبات البحث والتغييرات من تطبيقات العميل (الويب وAndroid وiOS وFlutter).

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

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

إذا كنت تستخدِم إضافة Firebase VS Code للنشر، انقر على الزر النشر في قناة الإصدار العلني.

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

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

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

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

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

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

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