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

ملاحظة: يمكنك الانضمام إلى برنامج المعاينة الخاصة لـ Firebase Data Connect لمعرفة المزيد من المعلومات حول أول حل SQL من Firebase. ستحصل على فرصة أن تكون من المستخدمين في مرحلة مبكرة لهذا المنتج وستحصل على معلومات مباشرة عن الجهود الجديدة التي يبذلها Firebase لتحديث تجربة تطوير التطبيقات لديك. اشترِك من خلال صفحة منتج Firebase Data Connect.

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

ملاحظة: للوصول إلى خدمة Firebase Data Connect وإلى معظم الأدوات والمصادر المذكورة في هذا الدليل، ستحتاج إلى الاشتراك في برنامج "المعاينة الخاصة".

في هذه البداية السريعة، ستتعلم كيفية:

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

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

لاستخدام هذا البدء السريع، ستحتاج إلى ما يلي.

• Linux أو macOS أو Windows
• رمز Visual Studio

إضافة Data Connect إلى مشروعك وإنشاء مصدر بيانات

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

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

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

3. انتقل إلى قسم "ربط البيانات" بوحدة تحكم Firebase واتبع سير عمل إعداد المنتج.

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

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

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

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

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

تدعم Data Connect تجربتي تطوير لإعداد النماذج الأولية:

• إذا كنت من مطوّري Kotlin Android أو الويب، يمكنك استخدام تطوير رموز VS لإنشاء نماذج أوّلية للمخططات والعمليات محليًا أثناء الاتصال بخدمة Cloud SQL لمثيل PostgreSQL.

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

تطوير رمز VS

إذا أردت التطوير محليًا بدلاً من استخدام IDX، عليك إعداد إضافة Firebase VS Code لمساعدتك في تكرار عملية التطوير بسرعة.

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

3. نزِّل الإضافة المجمَّعة كحزمة VSIX من مساحة تخزين Firebase.

   ملاحظة: لا يمكنك النقر مرّتين على حزمة VSIX لتثبيت الإضافة. تأكَّد من اتّباع الخطوات القليلة التالية لتثبيتها بشكل صحيح.

4. في رمز VS، اختَر الإضافات من القائمة عرض.

5. في شريط عناوين لوحة الإضافات، انقر على رمز القائمة more_horiz، ثم اتّبِع الخطوات التثبيت من VSIX....

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

تطوير IDX

تُعد IDX بيئة محسَّنة لتطوير تطبيقات الويب. إذا كنت من مطوِّري Kotlin على Android، يُرجى اتّباع الخطوات الواردة في علامة التبويب تطوير رمز VS.

لإعداد نموذج Data Connect IDX:

1. يمكنك الوصول إلى النموذج على موقع Project IDX الإلكتروني.
2. اتّبِع خطوات عملية الإعداد.

يمكنك، إذا أردت، تثبيت قاعدة بيانات PostgreSQL محلية للتطوير المحلي باستخدام محاكي Data Connect. يتم تناول هذا الإعداد في نهاية دليل البدء السريع هذا.

إعداد مشروعك على الجهاز

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

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

npm install -g firebase-tools

ملاحظة: في حال استخدام واجهة سطر الأوامر الحالية، احرص على التحديث إلى آخر إصدار.

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

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

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

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

في واجهة مستخدم إضافة Firebase:

1. تأكَّد من أنّك سجّلت الدخول.
2. انقر على الزر تشغيل firebase init.
3. تحقَّق من علامة التبويب Terminal في اللوحة السفلية لرمز VS لمعرفة الطلبات.
4. اختَر Data Connect كميزة لاستخدامها في هذا الدليل.
5. عندما يُطلب منك ذلك، قدم المشروع والخدمة ومعرّفات قاعدة البيانات الخاصة بمشروع Data Connect الذي أنشأته سابقًا في وحدة التحكم.

إنشاء مخطط Data Connect وطلب بحث

ابدأ استخدام GraphQL لوضع نماذج للمستخدمين والرسائل الإلكترونية. ستعدّل المصادر في:

• /dataconnect/schema/schema.gql
• /dataconnect/default-connector/queries.gql

البدء في تطوير مخطّط

في دليل مشروع Firebase، لاحظ المجلد dataconnect. هذا هو المكان الذي يمكنك فيه تحديد نموذج البيانات لقاعدة بيانات Cloud SQL باستخدام GraphQL.

في ملف /dataconnect/schema/schema.gql، ابدأ في تحديد مخطط يتضمن المستخدمين والرسائل الإلكترونية.

المستخدِم

في "ربط البيانات"، يتم ربط حقول GraphQL بالأعمدة. لدى المستخدمين uid وname وبريد إلكتروني address. تتعرّف أداة Data Connect على العديد من أنواع البيانات الأساسية: String وDate.

انسخ المقتطف التالي أو ألغِ تعليق الأسطر المقابلة في الملف.

# File `/dataconnect/schema/schema.gql`

type User @table(key: "uid") {
   uid: String!
   name: String!
   address: String!
}

وستضيف أداة Firebase Data Connect تلقائيًا مفتاح UUID id في حال عدم توفير أي منها. ولكنك تريد في هذه الحالة أن يكون uid هو المفتاح الأساسي، وهو ما يمكنك تنفيذه من خلال التوجيه @table(key: "uid").

البريد الإلكتروني

الآن بعد أن أصبح لديك مستخدمون، يمكنك تصميم نماذج للرسائل الإلكترونية. يمكنك هنا إضافة الحقول (أو الأعمدة) النموذجية لبيانات البريد الإلكتروني. هذه المرة، نغفل عن إضافة مفتاح أساسي لأنه يمكنك الاعتماد على Data Connect لإدارته.

# File `/dataconnect/schema/schema.gql`

type Email @table {
   subject: String!
   sent: Date!
   text: String!
   from: User!
}

يُرجى العلم أنّ الحقل from مرتبط بنوع من User. تدرك Data Connect أنّ هذه العلاقة بين Email وUser وستدير هذه العلاقة بالنيابة عنك.

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

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

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

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

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

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

لإضافة سجلّات إلى الجدولَين User وEmail:

1. في schema.gql، انقر على الزر إضافة بيانات أعلى بيان النوع User.
   
2. في ملف User_insert.gql الذي يتم إنشاؤه، بيانات الرموز البرمجية الثابتة للحقول الثلاثة.
3. النقر على الزر تشغيل (مرحلة الإنتاج)
   
4. كرِّر الخطوات السابقة لإضافة سجلّ إلى جدول Email، مع إدخال uid للمستخدم في الحقل fromUid على النحو المطلوب في عملية تغيير Email_insert التي تم إنشاؤها.

كتابة طلب بحث لإدراج عناوين البريد الإلكتروني

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

ابدأ تعديل ملف /dataconnect/default-connector/queries.gql. إذا كنت ترغب في الحصول على جميع رسائل البريد الإلكتروني، فاستخدم استعلامًا مثل هذا.

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

query ListEmails @auth(level: NO_ACCESS) {
  emails {
    id, subject, text, sent
    from {
      name
    }
  }
}

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

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

نشر النموذج الأوّلي المكتمل للإنتاج

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

إذا كنت تستخدم إضافة Firebase VS Code للنشر، انقر على الزر Deploy all (نشر الكل).

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

(اختياري) تثبيت PostgreSQL على الجهاز

يتيح لك تثبيت PostgreSQL محليًا ودمجه مع المحاكي إنشاء نموذج أولي في بيئة تطوير محلية بالكامل.

يمكنك تثبيت مثيل جديد من PostgreSQL أو استخدام مثيل حالي.

تثبيت PostgreSQL

ثبِّت الإصدار 15.x من PostgreSQL من خلال اتّباع التعليمات للنظام الأساسي.

ملاحظة: تأكَّد من تدوين اسم المستخدم وكلمة المرور للوصول إليهما في المستقبل.

• نظام التشغيل macOS نزِّل تطبيق Postgres.app وثبِّته.
• نظام التشغيل Windows: استخدِم أداة تثبيت EDB من صفحة عمليات تنزيل PostgreSQL.
• Docker: اسحب صورة pgvector/pgvector:15 وشغِّلها التي تتوفر مع PostgreSQL 15.x ودعم المتجه.
• نظام التشغيل Linux: ننصح باستخدام Docker مع الصورة السابقة، ولكن يمكنك أيضًا اتّباع تعليمات بديلة حول التوزيعات الشائعة.

لاحظ إخراج اسم المضيف والمنفذ واسم المستخدم وكلمة المرور والمعلمات ذات الصلة أثناء تسلسل التثبيت.

للاتصال بمثيل PostgreSQL، يحتاج المحاكي إلى ما يلي:

• مَعلمات ضبط الإعداد هذه
• تمثّل هذه السمة اسم قاعدة البيانات من dataconnect.yaml وقاعدة بيانات ذات اسم مطابق تم إعداده في المثيل المحلي.

تحديث .firebaserc باستخدام سلسلة الاتصال

استخدِم تفاصيل إعداد PostgreSQL المحلية، بما في ذلك اسم المستخدم وكلمة المرور لحسابك على PostgreSQL، لإضافة سلسلة اتصال إلى المفتاح التالي في ملف .firebaserc.

{
  "projects": {},
  ...,
  ...,
  "dataconnectEmulatorConfig": {
    "postgres": {
      "localConnectionString": "postgresql://postgresusername:postgrespassword@localhost:5432?sslmode=disable"
    }}
}

الاتصال بمثيل PostgreSQL المحلي

بعد إتمام هذه الإعدادات، للاتصال بقاعدة بياناتك المحلية:

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

الخطوات اللاحقة

ملاحظة: هل جذبت هذه الجولة التفصيلية اهتمامك بالمشاركة في برنامج "المعاينة الخاصة"؟ في هذه الحالة، اشترِك من خلال صفحة منتج Firebase Data Connect.