إضافة 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 أو مشروع عادي. ومع ذلك، في كلتا الحالتَين، يتم وضع جميع Cloud Firestore قواعد البيانات التي يوفّرها الوكيل Google AI Studio في مجموعة قواعد البيانات نفسها ضمن "الحصة المشترَكة للذكاء الاصطناعي" في مشروعك. وتشترك جميعها في الخصائص التالية:

• الحصة المشترَكة: تشترك جميع قواعد البيانات في المجموعة في حصة استخدام (اطّلِع على التفاصيل أدناه).
• لا يلزم توفّر حساب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. في البطاقة التي تظهر، انقر على رمز الإعدادات icon 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، عليك بعد ذلك استخدام الز2}ترقية قاعدة البيانات الموضّح في إضافة الفوترة للحصول على حصة أكبر في Cloud Firestore لنقل قاعدة بياناتك إلى حالة مدفوعة عادية. إذا أعددت Cloud Firestore يدويًا، لن يكون من الضروري استخدام الزر ترقية قاعدة البيانات.

ماذا يجب أن أفعل إذا ظهر لي الخطأ "الأذونات غير متوفّرة أو غير كافية"؟

يظهر هذا الخطأ عندما يحاول تطبيقك قراءة البيانات أو كتابتها في قاعدة بيانات Cloud Firestore، ولكن يتم رفض الطلب من خلال Security Rules. يشير ذلك إلى أنّ Security Rules لا تسمح بالعملية التي تمّت محاولتها استنادًا إلى حالة المصادقة الحالية أو مسار البيانات. انقر على الز0}إصلاح الخطأ لتوجيه وكيل 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 Google Cloud، ثم اربط مشروعك باستخدام إحدى الطريقتَين التاليتَين:

• أثناء التفعيل: عند تفعيل التكامل مع Firebase لأول مرة في Google AI Studio، اختَر مشروعك الحالي في البطاقة التي تظهر. انقر على رمز الإعدادات icon 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" وكان مفتاح واجهة برمجة التطبيقات المُدرَج في الرسالة الإلكترونية هو مفتاح واجهة برمجة التطبيقات على Firebase، تأكَّد من أنّ مفتاح واجهة برمجة التطبيقات يستوفي المتطلبات التالية ليكون آمنًا عند تضمينه في الرمز البرمجي أو ملفات الإعداد. يمكنك التحقّق مما يلي في صفحة واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد في وحدة تحكّم 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 وإدارتها