إضافة Cloud Firestore وAuthentication إلى تطبيقك على Google AI Studio

يمكن لوضع الإنشاء في Google AI Studio إعداد ودمج Cloud Firestore وFirebase Authentication تلقائيًا في تطبيقات الويب، ما يسهّل إنشاء تطبيقات تتضمّن تخزينًا دائمًا للبيانات وعمليات تسجيل دخول آمنة. من خلال طلب واحد وبضع نقرات فقط، يمكنك السماح Google AI Studio للوكيل بإعداد مشروع Firebase وربط تطبيقك بهذا المشروع وإنشاء جميع رموز Cloud Firestore وAuthentication مباشرةً في تطبيقك.

نظرة عامة: إضافة خادم خلفي إلى تطبيق Google AI Studio

1. وصف فكرتك: أنشئ تطبيقًا جديدًا في Google AI Studio واشرح ميزة تتطلّب قاعدة بيانات أو مصادقة. على سبيل المثال، يمكنك إدخال الطلب: Build a shared to-do list app using Firebase as a backend.

2. تفعيل عملية الدمج مع Firebase: في البطاقة التي تظهر، اضبط إعداداتك على النحو التالي:

   • تخصيص المشروع أو الموقع الجغرافي (اختياري): انقر على رمز الإعدادات settings، ثم اختَر موقعًا جغرافيًا أو المشروع Google Cloud الذي تريد استخدامه.
   • تأكيد اختيارك: للمتابعة، انقر على الزر تفعيل Firebase.

   بعد ذلك، يربط الوكيل تطبيقك تلقائيًا بمشروع Firebase وينشئ الرمز اللازم Cloud Firestore وAuthentication، بما في ذلك ملف /src/lib/firebase.ts وملف firestore.rules.

3. النشر: بعد أن يصبح تطبيق الويب جاهزًا، استخدِم الخيار مشاركة > نشر لنشر تطبيق الويب الخاص بك إلى Cloud Run. سيتم نشر تطبيقك تلقائيًا في المشروع نفسه الذي اخترته أثناء عملية الإعداد.

   قبل مشاركة تطبيقك أو نشره، احرص أيضًا على مراجعة Firebase Security Rules الذي تم إنشاؤه باستخدام الذكاء الاصطناعي.

إضافة Firebase إلى تطبيق أثناء التطوير

إذا أردت إضافة عملية دمج Firebase إلى تطبيق تعمل عليه في Google AI Studio، يمكنك إجراء ذلك في أي وقت خلال مرحلة التكرار باستخدام أحد الخيارَين التاليَين:

• التحدّث إلى الوكيل: اطلب من الوكيل إضافة ميزة تتطلّب قاعدة بيانات أو مصادقة (مثل Add a Firestore database to this app).
• استخدام قائمة الإعدادات: انتقِل إلى الإعدادات > عمليات الدمج وانقر على مربّع Firebase Firestore & Auth.

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

بعد تفعيل عملية الدمج، يمكنك مراجعة إعداداتها، بما في ذلك المشروع والموقع الجغرافي والبريد الإلكتروني المخصّص للدعم بشأن التطبيق ومعرّف قاعدة البيانات، في أي وقت من خلال الانتقال إلى الإعدادات > عمليات الدمج والنقر على مربّع Firebase Firestore & Auth.

التعرّف على الحصة المشترَكة لـ Cloud Firestore

استنادًا إلى تاريخ إنشاء تطبيقك وأهليّة حسابك، قد تتم استضافة قواعد البيانات في مشروع Google Cloud Starter Tier أو في مشروع عادي. ومع ذلك، في كلتا الحالتين، يتم وضع جميع قواعد البيانات التي يوفّرها عامل Google AI Studio في مجموعة قواعد البيانات نفسها ضمن "الحصة المشتركة للذكاء الاصطناعي" في مشروعك.Cloud Firestore وتشترك جميعها في الخصائص التالية:

• الحصة المشتركة: تشترك جميع قواعد البيانات في المجموعة في حصة استخدام (اطّلِع على التفاصيل أدناه).
• لا يلزم توفّر حساب Cloud Billing: يمكنك إنشاء تطبيقك واختباره بدون إضافة معلومات الفوترة. يمكنك الاطّلاع على التفاصيل أدناه حول إضافة معلومات الفوترة بشكل اختياري.
• عمليات إعادة الضبط اليومية: إذا بلغت الحدّ الأقصى للحصة اليومية (على سبيل المثال، 50 ألف عملية قراءة في اليوم)، سيتوقف التطبيق مؤقتًا لجميع قواعد البيانات ضِمن المجموعة، وسيتم استئنافه في اليوم التالي في منتصف الليل تقريبًا بتوقيت المحيط الهادئ.

تتشارك قواعد بيانات Cloud Firestore في مجموعة الحصص المشتركة الحدود التالية:

(اختياري) إضافة معلومات الفوترة للحصول على حصة أكبر من Cloud Firestore

إذا حقّق تطبيقك رواجًا واحتجت إلى تجاوز حدود الاستخدام بدون تكلفة Cloud Firestore، يمكنك إضافة معلومات الفوترة التي تؤدي إلى ترقية مشروع Firebase إلى خطة Blaze المَرِنة بنظام الدفع حسب الاستخدام.

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

الخطوة 1: إضافة معلومات الفوترة (إذا لم يسبق لك ذلك)

يمكنك إعداد الفوترة مباشرةً في Google AI Studio.

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

الخطوة 2: ترقية قاعدة البيانات

حتى بعد إضافة الفوترة، تظل قواعد بيانات Cloud Firestore التي أنشأها وكيل Google AI Studio في مجموعة الحصة المشتركة. لتفعيل التوسيع الكامل المدفوع لقاعدة بيانات معيّنة، عليك ترقيتها يدويًا.

1. انتقِل إلى وحدة تحكّم Firebase واختَر المشروع الذي يحتوي على قاعدة البيانات التي تريد ترقيتها.
2. من لوحة التنقّل اليمنى، انتقِل إلى قواعد البيانات ومساحة التخزين > Firestore.
3. إذا كان مشروعك يحتوي على عدة مثيلات لقاعدة بيانات Cloud Firestore، اختَر المثيل الذي تريد ترقيته.
4. ابحث عن بانر بالقرب من أعلى الصفحة يشير إلى أنّ قاعدة البيانات تخضع لحدود الحصة المشتركة التي تفرضها ميزة "الذكاء الاصطناعي". لترقية قاعدة البيانات، انقر على ترقية قاعدة البيانات > الترقية إلى خطة الدفع حسب الاستخدام.إذا لم يظهر لك هذا البانر، يعني ذلك أنّ قاعدة البيانات لم يتم إنشاؤها بواسطة وكيل Google AI Studio، وأنّها ليست جزءًا من مجموعة الحصة المشتركة، أو أنّه تمّت ترقيتها من قبل.

من المفترض أن يسري التغيير لإيقاف الحصة المشتركة وتفعيل الفوترة حسب الاستخدام لقاعدة البيانات في غضون دقائق قليلة.

إنشاء المحتوى باستخدام "Security Rules"

ينشئ Google AI Studio الوكيل Firebase Security Rules تلقائيًا استنادًا إلى منطق تطبيقك. تم تصميم هذه Security Rules لتكون "رفضًا تلقائيًا"، ما يعني أنّه لا يمكن للمستخدمين النهائيين لتطبيقك الوصول إلا إلى البيانات التي يملكونها.

يُرجى العِلم أنّه في حال تعديل Security Rules يدويًا في وحدة تحكّم Firebase، لن يعلم وكيل Google AI Studio بالتغييرات، وسيتم استبدالها أثناء عمليات تكرار التطبيق اللاحقة. ننصحك باستخدام وكيل Google AI Studio لتعديل Firebase Security Rules لضمان الحفاظ على التغييرات ومواءمتها مع منطق تطبيقك.

استخدام مشروع حالي

عند تفعيل عملية الدمج مع Firebase لأول مرة، يمكنك اختياريًا اختيار مشروع Google Cloud حالي تملكه:

1. في البطاقة التي تظهر، انقر على رمز الإعدادات settings.
2. اختَر مشروعك، ثم انقر على تفعيل Firebase.

أثناء تكرار تطبيقك، يمكنك أيضًا توجيه الوكيل لاستخدام مشروع مختلف من خلال طلب مثل:

Add Firestore to this app using project PROJECT_ID.

عند اختيار مشروع، يتم تنفيذ الإجراءات التالية:

• سيتم توفير قاعدة بيانات Cloud Firestore جديدة في هذا المشروع باستخدام الحصة المشترَكة.
• سيتم ضبط Firebase Authentication باستخدام ميزة "تسجيل الدخول باستخدام حساب Google".
• سيتم منح حساب خدمة إذن الوصول إلى قاعدة بيانات Cloud Firestore. للسماح للمشرف بالوصول من Google AI Studio، سيتم منح حساب خدمة جديد باسم ais-sandbox@PROJECT_ID.iam.gservice.com إذن الوصول إلى قاعدة بيانات Cloud Firestore. هذا الحساب مرتبط فقط بتطبيقاتك على Google AI Studio.
• القيود: إذا كان مشروع Firebase يتضمّن Cloud Firestore قاعدة بيانات، لن يتمكّن البرنامج من إضافة قاعدة بيانات أخرى. عليك اختيار مشروع مختلف أو إنشاء مشروع جديد فارغ لاستخدامه.

استخدام وحدة تحكّم Firebase

يمكنك الاطّلاع على بيانات تطبيقك وإعداداته في وحدة تحكّم Firebase. إليك كيفية الوصول إلى مشروع Firebase المرتبط بـ Google AI Studio:

1. انتقِل إلى وحدة تحكّم Firebase واختَر المشروع الذي يحمل التصنيف AI Studio.

2. من جزء التنقّل الأيمن، استكشِف الخدمات المفعَّلة في مشروعك:

   • للاطّلاع على بيانات Cloud Firestore المخزَّنة وتعديلها، انتقِل إلى قواعد البيانات والتخزين > Firestore.
   • لعرض إعدادات Authentication وبياناتها أو ضبطها، انتقِل إلى الأمان > المصادقة.

تحديد المشاكل وحلّها والأسئلة الشائعة

يمكنك العثور على إجابات عن الأسئلة الشائعة والتعرّف على كيفية حلّ المشاكل عند دمج Firebase مع تطبيق Google AI Studio.

كيف يتم اختيار Google Cloud / مشروع Firebase وموقعه الجغرافي؟

عند طلب خادم خلفي على Firebase لتطبيق، يمكنك اختياريًا تحديد موقع جغرافي ومشروع في البطاقة التي تظهر:

• تخصيص المشروع أو الموقع الجغرافي (اختياري): انقر على رمز الإعدادات settings، واختَر موقعًا جغرافيًا أو مشروع Google Cloud الذي تريد استخدامه، ثم انقر على تفعيل Firebase.

يرجى الإحاطة علمًا بالتالي:

• موقع قاعدة البيانات نهائي: بعد اختيار موقع لقاعدة البيانات، لا يمكنك تغييره لهذا المشروع. سيتم استخدام هذا الخيار كإعداد تلقائي لخدمات الخلفية الأخرى.
• اتّساق المشروع: لضمان عملية دمج سلسة، تستخدم Google AI Studio تلقائيًا المشروع نفسه لكل من الخلفية وعملية النشر. لا يمكنك استخدام مشاريع مختلفة لخدمات مختلفة ضمن التطبيق نفسه.

ما هي طرق المصادقة المتاحة؟

يُعدّ Google AI Studio وكيل الإعداد عملية "تسجيل الدخول باستخدام حساب Google" عندما تطلب إعداد Authentication أو شاشة تسجيل الدخول. في ما يلي كيفية إضافة طرق إضافية لتسجيل الدخول إلى تطبيقك:

1. في وحدة تحكّم Firebase، انتقِل إلى صفحة الأمان > المصادقة > طريقة تسجيل الدخول، وأعِدّ أي طرق تسجيل دخول مطلوبة.

2. ارجع إلى Google AI Studio واطلب من أحد موظفي الدعم المساعدة في تعديل قاعدة الرموز البرمجية باستخدام طريقة تسجيل الدخول الجديدة.Google AI Studio

هل يمكنني إنشاء تطبيق متوافق مع الأجهزة الجوّالة (مثل Android أو iOS) باستخدام Google AI Studio؟

يتيح وكيل Google AI Studio إنشاء كل من تطبيقات الويب وتطبيقات Android.

ومع ذلك، يُرجى العِلم أنّ عملية الدمج مع Firebase (إضافة Cloud Firestore وAuthentication) متاحة حاليًا لتطبيقات الويب فقط، وليس لتطبيقات Android. إذا كنت تنشئ تطبيق Android، عليك دمج Firebase يدويًا إذا كنت بحاجة إلى هذه الخدمات.

يمكنك الاطّلاع على مزيد من المعلومات حول الميزات المتوفّرة في مستندات وكيل Google AI Studio.

يُرجى العِلم أنّه يمكن الوصول إلى تطبيقات الويب التي تم إنشاؤها باستخدام Google AI Studio كتطبيقات ويب متوافقة مع الأجهزة الجوّالة من خلال المتصفّحات المثبّتة على الأجهزة الجوّالة، تمامًا كما هو الحال مع جميع تطبيقات الويب.

ما هو ملف firebase-blueprint.json؟

هذا ملف وسيط يستخدمه وكيل Google AI Studio لفهم قاعدة الرموز البرمجية لتطبيقك. لا تعدِّل هذا الملف يدويًا، فقد يؤدي ذلك إلى أن ينشئ الوكيل رمزًا غير صحيح أو Security Rules غير آمن.

ماذا أفعل إذا تلقّيت رسالة الخطأ "تم تجاوز الحصة"؟

يعني بلوغ الحد الأقصى للحصة Cloud Firestore أنّ تطبيقك قد وصل إلى الحد الأقصى للاستخدام اليومي لقاعدة بيانات Cloud Firestore ضمن مجموعة الحصص المشتركة. هناك طريقتان لحلّ هذه المشكلة:

• الخيار 1: الانتظار: تتم إعادة ضبط الحصص يوميًا في منتصف الليل بتوقيت المحيط الهادئ.
• الخيار 2: الترقية: يمكنك الترقية إلى خطة Blaze المَرِنة للدفع حسب الاستخدام.
  • إذا Google AI Studio أعدّ وكيل Cloud Firestore لك، عليك بعد ذلك استخدام الزر ترقية قاعدة البيانات الموضّح في إضافة الفوترة للحصول على المزيد من حصة Cloud Firestore لنقل قاعدة البيانات إلى حالة مدفوعة عادية. إذا أعددت Cloud Firestore يدويًا، لن تحتاج إلى استخدام الزر ترقية قاعدة البيانات.

ماذا أفعل إذا تلقّيت رسالة الخطأ "الأذونات غير متوفّرة أو غير كافية"؟

يحدث هذا الخطأ عندما يحاول تطبيقك قراءة البيانات أو كتابتها في قاعدة بيانات Cloud Firestore، ولكن يتم رفض الطلب من خلال Security Rules. يشير هذا الخطأ إلى أنّ Security Rules لا تسمح بتنفيذ العملية المطلوبة استنادًا إلى حالة المصادقة الحالية أو مسار البيانات. انقر على الزر إصلاح الخطأ لطلب المساعدة من وكيل Google AI Studio في محاولة تصحيح Security Rules.

ماذا يحدث لخادم Firebase الخلفي عند حذف تطبيق Google AI Studio؟

لا يؤدي حذف تطبيقك في Google AI Studio إلى حذف مشروع Firebase المرتبط أو قاعدة بيانات Cloud Firestore أو إعدادات Firebase Authentication تلقائيًا.

إذا أضفت خلفية Firebase، عليك الانتقال يدويًا إلى وحدة تحكّم Firebase وحذف المشروع أو تنظيف الموارد الفردية (مثل مثيل قاعدة بيانات Cloud Firestore وموفّري Authentication) لضمان إزالة جميع البيانات وعمليات الإعداد.

هل يمكن لوكيل Google AI Studio حذف البيانات أو تعديلها في قاعدة بيانات Cloud Firestore؟

تم تصميم الوكيل Google AI Studio للمساعدة في توفير موارد الخلفية اللازمة وإنشاء الرموز البرمجية وSecurity Rules. على الرغم من أنّ الوكيل نفسه لا يمكنه حذف إدخالات البيانات أو تعديلها أو معالجتها مباشرةً في قاعدة بيانات Cloud Firestore، يمكنه كتابة رمز في تطبيقك مصمَّم لتنفيذ هذه الإجراءات. لتنفيذ مهام إدارة البيانات، مثل حذف الإدخالات، انتقِل إلى صفحة قواعد البيانات ومساحة التخزين > Firestore في وحدة تحكّم Firebase.

أنا أنتمي إلى مؤسسة تستخدم Google Cloud. هل يمكنني ربط تطبيق Google AI Studio بمشروع حالي ضمن بيئة Google Cloud الخاصة بمؤسستي؟

نعم. تأكَّد من وضع مشروع Firebase الخاص بك في مجلد مؤسستك Google Cloud، ثم اربط مشروعك باستخدام إحدى الطريقتَين التاليتَين:

• أثناء التفعيل: عند تفعيل عملية الدمج مع Firebase لأول مرة في Google AI Studio، اختَر مشروعك الحالي في البطاقة التي تظهر. انقر على رمز الإعدادات settings واختَر مشروعك.

• أثناء التكرار: إذا سبق لك تفعيل Firebase أو أردت تبديل المشاريع لاحقًا، يمكنك توجيه العامل لاستخدام مشروعك الحالي من خلال طلب مثل:

    Add Firestore to this app using project PROJECT_ID.
  

لماذا لا يمكنني العثور على مستندات معيّنة في وحدة تحكّم Firebase؟

عندما يحفظ وكيل AI Studio البيانات في مسار متداخل (مثل /users/user1/messages/msg1) بدون إنشاء المستند الرئيسي أولاً (user1)، ينشئ ما يُعرف باسم المستند الرئيسي غير الموجود. لا يتم عرض هذه المستندات في وحدة تحكّم Firebase، ما قد يصعّب العثور عليها عند تصفّح قاعدة بيانات Cloud Firestore. على الرغم من أنّ ذلك لا يؤثر في طريقة تشغيل تطبيقك، يمكنك غالبًا وصف المشكلة لبرنامج AI Studio لكي يطلب إنشاء المستندات الرئيسية الناقصة.

لمزيد من التفاصيل، يُرجى الاطّلاع على المستندات الرئيسية غير المتوفّرة.

هل يمكنني اختيار الموقع الجغرافي لقاعدة بيانات Cloud Firestore؟

نعم. عند تفعيل عملية الدمج مع Firebase لأول مرة في Google AI Studio، يمكنك اختيار الموقع الجغرافي Cloud Firestore لقاعدة البيانات.

يُرجى العِلم أنّ الموقع الجغرافي الذي تختاره ينطبق على جميع Cloud Firestore قواعد البيانات التي ينشئها وكيل Google AI Studio في مشروع Firebase هذا. وبعد ضبطه، لا يمكن تغيير هذا الموقع الجغرافي لقواعد البيانات هذه.

بعد ترقية قاعدة بيانات Cloud Firestore، هل يمكنني إعادتها إلى مجموعة الحصص المشتركة؟

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

• ‫PROJECT_ID : رقم تعريف مشروع Firebase يمكنك العثور على رقم التعريف هذا في صفحة settings الإعدادات > عام في وحدة تحكّم Firebase.

• ‫DATABASE_ID : معرّف قاعدة بيانات Cloud Firestore، والذي سيتطابق مع معرّف التطبيق الصغير. يمكنك العثور على رقم تعريف قاعدة البيانات هذا في Google AI Studio من خلال الانتقال إلى الإعدادات > عمليات الدمج والنقر على مربّع Firebase Firestore & Auth.

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://firestore.googleapis.com/v1/projects/PROJECT_ID/databases/DATABASE_ID?updateMask=free_tier_limited" \
-d '{"free_tier_limited": true}'

كيف تستخدم Google بياناتي (مثل الرموز والطلبات) في Google AI Studio؟

يُرجى الرجوع إلى بنود الخدمة الإضافية الخاصة بـ Gemini API للحصول على تفاصيل حول كيفية استخدام بياناتك.

تلقّيت رسالة إلكترونية من Google Cloud بشأن "مفتاح Google API متاح للجميع لمشروعك Google Cloud". ما هو الإجراء الواجب اتّخاذه؟

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

• وهو مفتاح واجهة برمجة التطبيقات الذي تستخدمه لتطبيق Firebase وفقط لخدمات Firebase. ويُطلق على هذه المفاتيح عادةً Browser key (auto created by Firebase) أو Android key (auto created by Firebase) أو iOS key (auto created by Firebase).
• يجب أن يتضمّن جميع واجهات برمجة التطبيقات المطلوبة والمتعلّقة بمنصّة Firebase والمضمّنة في القائمة المسموح بها ضمن "قيود واجهة برمجة التطبيقات" الخاصة بالمفتاح.
• لا تتضمّن أي واجهات برمجة تطبيقات أخرى في القائمة المسموح بها ضمن "قيود واجهة برمجة التطبيقات". على وجه الخصوص، يجب ألّا تتضمّن القائمة Generative Language API.

تأكَّد أيضًا من استخدام Firebase Security Rules وApp Check على النحو الموصى به لمنتجات Firebase التي تستخدمها.

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