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

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

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

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

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

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

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

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

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

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

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

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

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

3. انتقِل إلى قسم Data Connect في وحدة تحكّم Firebase واتّبِع سير عمل إعداد المنتج.

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

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

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

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

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

Data Connect يتيح تجربتَي تطوير للنماذج الأولية:

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

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

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

3. نزِّل الإضافة، التي تم تجميعها كحزمة VSIX، من Firebase Storage.

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

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

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

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

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

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

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

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

npm install -g firebase-tools

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

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

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

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

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

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

إنشاء مخطط

في دليل مشروع Firebase، في ملف /dataconnect/schema/schema.gql، ابدأ بتحديد مخطّط GraphQL يتضمّن المستخدمين وعناوين البريد الإلكتروني.

مستخدم

في Data Connect، يتم ربط حقول 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.

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. انقر على الزر Run (التنفيذ) (الإصدار العلني).
   
4. كرِّر الخطوات السابقة لإضافة سجلّ إلى جدول Email مع توفير uid للمستخدم في الحقل fromUid، كما هو موضح في النموذج الذي تم إنشاؤه تغيُّر Email_insert

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

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

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

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

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

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

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

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

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

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

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

(اختياري) تثبيت PostgreSQL محليًا

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

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

تثبيت PostgreSQL

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

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

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

دوِّن اسم المضيف والمنفذ واسم المستخدم وكلمة المرور والمَعلمات ذات الصلة التي يتم عرضها أثناء تسلسل التثبيت.

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

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

استخدام مثيل PostgreSQL المحلي

يمكنك استخدام مثيل PostgreSQL محلي حالي عن طريق تحديث إعدادات المحاكي في "Data Connect"

firebase setup:emulators:dataconnect

أدخِل سلسلة اتصال PostgreSQL بالتنسيق التالي عندما يُطلب منك ذلك: postgresql://postgresusername:postgrespassword@localhost:5432/postgresdatabase?sslmode=disable

لمزيد من المعلومات عن سلسلة الاتصال، يُرجى الرجوع إلى مستندات PostgreSQL.

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

بعد الانتهاء من هذه الإعدادات، يُرجى اتّباع الخطوات التالية للاتصال بقاعدة البيانات المحلية:

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

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

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