
درس مصغّر 15 من 30 · الحسابات والوصول
اعرف أي قيمة يجب أن تبقى خاصة
لمن هذا الدرس؟
لمن يربطون موقعًا بخدمة ذكاء اصطناعي أو خدمة أخرى تتطلب صلاحيات. يستطيع مساعد برمجة توصيل المشروع الجاهز؛ والمطلوب فهم موضع استخدام السر، لا كتابة كود الخادم.
ينبغي أن يستخدم المتصفح الميزة دون أن يستلم سر المزود.
هدف هذا الدرس
- ضع سر المزود في بيئة الخادم الخاصة فقط.
- شغّل الإجراء المرفق دون كشف المفتاح للزوار.
- اختبر محاولات الوصول الناجحة والمرفوضة.
شرح ومثال محلول وتدريب
قبل أن تبدأ
وصولك الخاص إلى API في Google AI Studio، ومشروع تدريب منفصل لدوال Netlify. استخدم مساعد برمجة مع الحزمة كاملة وإعداد بيئة خاصة. تحقق من النموذج وحدود استخدام الحساب، بما فيها أي رسوم محتملة، قبل إرسال الطلبات. يستخدم المختبر رمز تدريب منفصلًا لدى المالك؛ وليس خدمة AI عامة جاهزة.
تحقّق من مهارات البداية
هذه مهارات مفيدة وليست دروسًا إلزامية تمنع الدخول. ابدأ هنا إن كنت تتقنها، وإلا افتح التحضير المرتبط. ملفات البداية مرفقة، فلا تحتاج إلى موقع شخصي سابق.
- كيف تنشر موقعك من GitHub
اربط مستودعًا تجريبيًا بالاستضافة.
الوقت المتوقع: 20–32 دقيقة
تقديرات باستخدام ملفات البداية المرفقة، مع جاهزية الحسابات والأدوات المطلوبة. يستغرق الإعداد وانتظار النشر وتسليم البريد وتحديث DNS وقتًا إضافيًا. قد يستغرق إعداد المزوّد والحساب وقتًا أطول. يخضع الاستخدام لشروط حسابك وحصته الحاليتين.
افهم الفكرة
افتح المشروع المرفق مع مساعدك. حدّد مفتاح المزود بوصفه قيمة خاصة بالحساب، ورمز التدريب المنفصل بوصفه وسيلة المالك للتحكم في الوصول إلى هذا المختبر الصغير.
لا يكفي أن يُسمّى الملف .env إذا كان البناء ينسخ قيمته إلى سكربتات عامة. اطلب من المساعد فحص الملفات الفعلية التي تصل إلى الزائر.
مثال عملي
الحقل المخفي في النموذج يبقى داخل المتصفح ولا يستطيع إخفاء مفتاح المزود.
افتح حزمة تدريب مفتاح API الجاهزة وأرشدني إلى إعدادها باتباع run-locally.txt. أبقِ مفتاح المزود واختيار النموذج على الخادم، واستخدم رمز وصول منفصلًا للتدريب. لا تضع أسرارًا في ملفات عامة ولا تطلب مني لصقها في رسائل مشتركة. ساعدني في فحص ما يستلمه المتصفح واختبار الطلبات المسموحة والمرفوضة. اشرح الدليل الذي يمكن ملاحظته بدل اشتراط أن أنفذ نقطة الاتصال بنفسي.ملفات هذه الخطوة
افتح الملفات أدناه أو نزّلها منفردة. عند حفظ المشروع، احتفظ بمسارات المجلدات الموضحة في أسماء الملفات.
جرّب بنفسك
أي قيمة يجب أن تبقى خارج صفحة الزائر؟ وما الدليل الذي ستطلب من المساعد فحصه؟
عرض حل نموذجي مشروح
مثال خطة خصوصية: «GEMINI_API_KEY بيانات اعتماد المزود الخاصة. وLAB_TOKEN رمز تدريب منفصل، وليس اسمًا بديلًا لذلك المفتاح. سيفحص المساعد السكربتات العامة التي تصل إلى الزائر وطلبات المتصفح للتأكد من عدم كشف بيانات اعتماد عرضًا».
وجود اسم ملف خاص وحده ليس دليلًا؛ فقد تنسخ عملية البناء محتواه إلى الملفات العامة. سأبقي القيم الحقيقية خارج لقطات الشاشة والملاحظات المشتركة.
ما تتضمنه الإجابة السليمة
- يحدد مفتاح المزود سرًا، ورمز الوصول التدريبي حدًا مستقلًا للتجربة.
- يحدد الملفات العامة وطلبات المتصفح مواضع يجب فحصها بحثًا عن تسرب المفتاح دون قصد.
كيف يعمل؟ (اختياري)
أبقِ مفاتيح API ذات الامتيازات خارج شيفرة المتصفح
يستطيع متصفح الزائر فحص كل ملف ترسله إليه.
قد يجيز سر المزوّد الإنفاق أو عمليات ذات امتيازات. وضعه في JavaScript عام أو حقل مخفي أو متغير بيئة يُستبدل أثناء بناء الواجهة الأمامية لا يزال يرسله إلى المتصفح.
يسأل المثال Gemini سؤالًا تعليميًا ثابتًا عبر دالة خادمك. يتلقى المتصفح الإجابة؛ ويبقى مفتاح المزوّد في بيئة الخادم. ليس كل مفتاح سريًا: مفاتيح Supabase القابلة للنشر مصممة للاستخدام في المتصفح مع سياسات وصول، أما مفاتيحها السرية فلا.
مثال محلول
افتح insecure-example.txt. القيمة الزائفة ظاهرة لأنها في الشيفرة المرسلة. تصغير السطر نفسه سيجعله أقل قابلية للقراءة، لكنه لن يغيّر من يتلقاه.
تمرين تقني إضافي
يُخزن مفتاح في .env ثم يُدرج في حزمة JavaScript العامة أثناء البناء. هل هو خاص بعيدًا عن الزوار؟
عرض حل نموذجي مشروح
لا. لا يهم مكان ملفه الأصلي بعد إدراجه في حزمة عامة. انقل العملية ذات الامتيازات إلى دالة خادم وأبقِ القيمة هناك.
- تتبع المفتاح إلى الحزمة المرسلة.
- تميّز بيئة الخادم عن الاستبدال في الواجهة الأمامية.

الخطوة 1 · كيف تُبقي مفاتيح API خارج الواجهة الأمامية
شغّل الإجراء المحمي المرفق
دع المساعد يضبط مسار الخادم الموجود.
شرح ومثال محلول وتدريب
افهم الفكرة
اتبع run-locally.txt وserver-env.example.txt مع المساعد. تحقق من الحساب والنموذج المقصودين وشروط الاستخدام، وضع مفتاح المزود في الخادم بصورة خاصة، وأنشئ رمز تدريب مستقلًا. شغّل المشروع كاملًا وافتح رابط التطبيق المحلي. فحوص الإعداد هذه مطلوبة؛ أما كتابة كود الدالة فاختيارية.
ينبغي أن يتواصل المتصفح مع ميزة الخادم لديك، بينما يستدعي الخادم المزود بصورة خاصة. إن فشل الإعداد أو الوصول أو الحصة، فاذكر تلك المرحلة بدل اختلاق رد.
مثال عملي
رمز تدريب النموذج ليس مفتاح مزود Google.
ملفات هذه الخطوة
افتح الملفات أدناه أو نزّلها منفردة. عند حفظ المشروع، احتفظ بمسارات المجلدات الموضحة في أسماء الملفات.
جرّب بنفسك
هل عمل الإجراء؟ وما مرحلة الإعداد الخاص أو المزود التي ما زالت متعذرة؟
عرض حل نموذجي مشروح
مثال نتيجة جاهزية: «فتح المشروع الكامل عند رابط الخادم الوسيط المحلي. أعاد إجراء الخادم، بعد استخدام رمز الوصول التدريبي، شرحًا موجزًا لخادم الموقع. بقيت بيانات اعتماد المزود واختيار النموذج في البيئة الخاصة».
مثال عائق: «يعمل التطبيق، لكن المزود يبلغ بعدم توفر حصة استخدام؛ ولم ألاحظ ردًا ناجحًا». تحقق من النماذج المسموحة وحدود الحساب والرسوم المحتملة قبل تكرار الطلبات؛ فالدرس لا يعد باستدعاءات مجانية أو غير محدودة.
ما تتضمنه الإجابة السليمة
- يسجل رابط التطبيق المحلي الفعلي وإجراءً مسموحًا ناجحًا، أو عائق إعداد أو مزود محددًا.
- يبقي بيانات اعتماد المزود واختيار النموذج في الخادم، ويفحص شروط الحساب قبل استدعائه.
كيف يعمل؟ (اختياري)
ضع استدعاء المزوّد خلف نقطة نهاية خاصة بك
اضبط الخادم، ثم أرسل الطلب الصغير الذي تحتاج إليه الميزة فقط.
اقرأ netlify/functions/mini-explain.mjs وانشر المشروع المنفصل واضبط GEMINI_API_KEY وGEMINI_MODEL وLAB_TOKEN في خادمه. اختر نموذج نص مدعومًا في حسابك بدل نسخ اسم نموذج قديم من شرح تعليمي.
أدخل رمز التدريب المستقل في النموذج. يستدعي المتصفح /.netlify/functions/mini-explain؛ وتستدعي تلك الدالة نقطة HTTPS ثابتة لدى Google باستخدام x-goog-api-key. الرمز قيد مختبر خاص بالمالك، وليس بيانات اعتماد Gemini ولا نظام حصص عامًا كاملًا.
GEMINI_MODEL هو معرّف النموذج الدقيق المتاح لحساب API الخاص بك، وليس تسمية عرض منسوخة من لقطة شاشة. generate دالة مساعدة في ملف دالة الخادم نفسه. لا مكان لمفتاح المزوّد ولا لتلك الدالة المساعدة في public/. قد يفشل طلب صحيح أيضًا عندما ينفد رصيد المزوّد أو لا يكون متاحًا.
للتسلسل المحلي الكامل، افتح run-locally.txt: جهز بيئة الجذر الخاصة، واربط مشروع التدريب فقط، وابدأ وكيل دوال Netlify. يسرد server-env.example.txt أسماء المتغيرات دون أسرار حقيقية. فتح HTML وحده لا يشغّل الخادم.
استخدم دليل النماذج الحالي أدناه، أو شغّل list-text-models.mjs من جذر الورشة الخاص ببيئتك. يسرد مرشحي generateContent المرئيين للحساب دون طباعة المفتاح. اختر نموذج نص مدعومًا وافحص شروطه وحصته، ثم انسخ معرّف API الدقيق إلى إعداد GEMINI_MODEL في الخادم.
قبل أول طلب للدالة، شغّل مساعد قائمة النماذج واختر نموذج نص حاليًا يدعم حقول طلب generateContent المستخدمة هنا، بما فيها systemInstruction. تحدد القائمة مرشحين، لا الحصة أو كل قدرات النموذج. يعمل ملف netlify/functions/mini-explain.mjs كله على الخادم؛ ويُرسل public/app.js لكل زائر. افحص أيضًا مهلة دوال خطة الاستضافة: مهلة المزوّد ذات الـ20 ثانية لا تمدد حد مضيف أقصر.
مثال محلول
المطالبة المقدمة للمزوّد ثابتة على الخادم، فلا يستطيع مقدم الطلب تحويل هذا المسار إلى مطالبات كبيرة اعتباطية. وتحد الدالة أيضًا المخرجات وتنتظر طلب المزوّد 20 ثانية كحد أقصى.
واجهة Gemini generateContent API · مفاتيح Gemini API · Gemini: معرّفات النماذج الحالية وقدراتها · Node.js: حالة دعم الإصدارات
تمرين تقني إضافي
ما الطلبان اللذان ينبغي وجودهما في المسار، وأيهما يجب ألا يظهر في أدوات Network بالمتصفح؟
عرض حل نموذجي مشروح
يعرض المتصفح استدعاءه لدالتك والإجابة المعادة. يجري الخادم طلب المزوّد؛ ويجب ألا يظهر استدعاء Google الذي يحمل بيانات اعتماد بوصفه طلب متصفح.
- ترى طلب المتصفح إلى دالة موقعك.
- تُبقي طلب Google المصادَق عليه في الخادم.

الخطوة 2 · كيف تُبقي مفاتيح API خارج الواجهة الأمامية
افحص الخصوصية والفشل معًا
الرد المفيد لا يبرر انكشاف مفتاح.
شرح ومثال محلول وتدريب
افهم الفكرة
اطلب من المساعد فحص الملفات العامة المرسلة وطلبات المتصفح بحثًا عن سر المزود دون عرضه في سجلات مشتركة. جرّب رمز تدريب خاطئًا وحالة غياب إعداد في المشروع القابل للحذف.
يجب ألا يظهر المفتاح الفعلي في ملفات المتصفح أو طلباته. يجب أن تبقى الطلبات المرفوضة أو غير المتاحة حالات فشل، مع طريقة عملية لإعادة المحاولة.
مثال عملي
رد مقنع مع مفتاح مكشوف في app.js يظل مهمة غير مكتملة.
ملفات هذه الخطوة
افتح الملفات أدناه أو نزّلها منفردة. عند حفظ المشروع، احتفظ بمسارات المجلدات الموضحة في أسماء الملفات.
جرّب بنفسك
ماذا أظهر فحص المخرجات العامة والمحاولة المرفوضة فعلًا؟
عرض حل نموذجي مشروح
مثال سجل خصوصية وأخطاء: «فحص المساعد الملفات العامة وطلب المتصفح إلى خادمي؛ ولم يظهر مفتاح المزود. رُفض رمز تدريب خاطئ. وعند إزالة إعداد المزود الخاص في البيئة المؤقتة، فشل الإجراء بدل عرض شرح مختلق».
يسجل ذلك الحد الذي فُحص، لا تدقيقًا أمنيًا كاملًا. إذا وُجد مفتاح في الملفات العامة، فتوقف عن مشاركة تلك النسخة واستبدل بيانات الاعتماد المكشوفة لدى المزود قبل استخدامها مجددًا.
ما تتضمنه الإجابة السليمة
- يوضح الملفات أو الطلبات العامة التي فحصها دون إعادة نشر سر المزود.
- يسجل محاولة وصول مرفوضة ومحاولة دون الإعداد المطلوب بوصفهما فشلين.
كيف يعمل؟ (اختياري)
تحقق من الحد الفاصل والإجابة معًا
الرد الناجح وحده لا يثبت أن المفتاح ظل خاصًا.
ابحث عن مفتاح المزوّد الفعلي في HTML والسكربتات العامة المنشورة دون لصقه في لقطات شاشة أو سجلات مشتركة. افحص طلبات المتصفح: قد يكون رمز التدريب ظاهرًا لمالكه، لكن يجب ألا يظهر مفتاح Gemini.
اختبر رمز تدريب خاطئًا وإعداد مزوّد مفقودًا في المشروع القابل للاستغناء عنه. يجب أن يبقى الفشل فشلًا. قد تشير حالة المزوّد 429 إلى حدود الحصة أو المعدل؛ وقد تشير 401 أو 403 إلى مشكلات وصول أو إعداد. لا تحوّلها جميعًا إلى إجابة ذكاء اصطناعي مختلقة.
مثال محلول
ينبغي أن يعيد رمز تدريب صحيح مع إعدادات مزوّد صالحة إجابة حقيقية. وينبغي أن ترفض نقطة النهاية نفسها الرمز الخاطئ قبل أي طلب للمزوّد.
تمرين تقني إضافي
تعمل الإجابة، لكن مفتاح المزوّد يظهر أيضًا في public/app.js. هل اكتملت المهمة؟
عرض حل نموذجي مشروح
لا. أزل المفتاح من الملفات العامة، واستبدله لأنه كُشف، وحدّث إعداد الخادم، وافحص النشر الجديد وسجل المستودع بحثًا عن كشف متبقٍ.
- ترفض اعتبار المخرجات الناجحة دليلًا كافيًا.
- تزيل التسريب وتستبدل المفتاح المكشوف.

الخطوة 3 · كيف تُبقي مفاتيح API خارج الواجهة الأمامية
نفّذ تعديلًا واحدًا محددًا بأمان
حافظ على حدود السر نفسها عند تعديل الميزة.
شرح ومثال محلول وتدريب
افهم الفكرة
اطلب من المساعد تكييف العملية الثابتة المرفقة لشرح DNS بإيجاز. حافظ على إعدادات النموذج والمفتاح في الخادم، وعلى قصر التدريب على المالك.
اختبر الرد المقصود ورمز وصول غير صالح مجددًا. قبل الاستخدام العام، حدّد مصادقة فعلية وضوابط استخدام مستمرة ومراقبة لميزانيتك لدى المزود.
مثال عملي
ينبغي ألا ينقل تغيير موضوع الإجابة قيم الحساب الخاصة إلى الصفحة.
ملفات هذه الخطوة
افتح الملفات أدناه أو نزّلها منفردة. عند حفظ المشروع، احتفظ بمسارات المجلدات الموضحة في أسماء الملفات.
جرّب بنفسك
قدّم الإجراء المعدل واختبارات الخصوصية والطلب الصالح وغير الصالح التي نفذتها بالفعل.
ما المطلوب إنجازه: سجل لفصل المفتاح ونتائج الطلب الصالح وغير الصالح للإجراء المرفق، بعد إزالة المعلومات الحساسة.
عرض حل نموذجي مشروح
مثال سجل تعديل: «أصبحت العملية الثابتة تشرح DNS في جملتين. أعاد استدعاء تدريبي مسموح هذا الموضوع؛ ورُفض رمز تدريب خاطئ؛ ولم يجد فحص الملفات العامة مفتاح المزود».
«قبل فتح هذه الخدمة للغرباء، ما زلت بحاجة إلى مصادقة فعلية وحدود استخدام مستديمة ومراقبة ميزانية المزود». رمز التدريب المشترك حد صغير للمختبر، وليس دليلًا على اكتمال خدمة عامة.
ما تتضمنه الإجابة السليمة
- يغير موضوع الرد الثابت إلى DNS، مع إبقاء المفتاح والنموذج في الخادم فقط.
- يعيد اختبار الاستدعاءات المسموحة والمرفوضة ويحدد ضوابط التكلفة والوصول الباقية قبل الاستخدام العام.
كيف يعمل؟ (اختياري)
مهمتك: انقل عملية ثابتة ثانية
كرر الحد الفاصل عن قصد بدل توسيعه بالخطأ.
غيّر مطالبة الخادم الثابتة لتشرح DNS في جملتين. أبقِ بيانات الاعتماد واختيار النموذج وحد المخرجات على الخادم؛ وأبقِ المتصفح دون معرفة مفتاح المزوّد.
سجّل النتيجة مع رمز تدريب صحيح وآخر غير صحيح. اشرح ما ستضيفه قبل الوصول العام: مستخدمين مصادَقًا عليهم أو حد وصول آخر ذا معنى، وحدود استخدام دائمة، ومراقبة لميزانية المزوّد.
مثال محلول
يثبت تغيير مطالبة ثابتة فهمك لمكان التحكم في سلوك المزوّد. قبول نماذج أو نقاط نهاية أو حدود مخرجات اعتباطية من المتصفح يلغي ذلك التحكم.
يتوفر الشرح المرجعي الكامل في reference/assignment-walkthrough.txt. قارن خطواته بنتيجتك؛ واملأ سجل الاختبار بملاحظات من مشروعك أنت.
تمرين تقني إضافي
أنجز نسخة DNS وسجل اختبار قصيرًا للحد الفاصل.
عرض حل نموذجي مشروح
في دالة mini-explain الخاصة بالخادم فقط، استبدل السؤال الثابت عن خادم الموقع بـ«Explain DNS in two sentences for a beginner.»، أي اشرح DNS في جملتين لمبتدئ. أبقِ المفتاح والنموذج في متغيرات بيئة الخادم؛ تعرض الدالة المرجعية الكاملة التعديل الدقيق.
افحص السكربتات المرسلة إلى المتصفح وطلبات Network. يرسل المتصفح طلبه إلى دالتك أنت؛ ويجب ألا يرسل GEMINI_API_KEY إلى Google بنفسه. رمز المختبر الذي يدخله المالك منفصل عن مفتاح المزوّد.
جرّب رمز تدريب خاطئًا: توقع رفضًا قبل أي استدعاء للمزوّد. يجب أن يظل فشل حصة أو شبكة المزوّد فشلًا صادقًا، لا إجابة نجاح جاهزة. إذا كُشف سر حقيقي، فأزله واستبدله؛ تجاهل الملف بعد ذلك لا يلغي الانكشاف.
- لا يُرسل سر مزوّد إلى المتصفح.
- يُرفض الوصول الخاطئ ويظهر فشل المزوّد بصدق.
هل أفادك هذا الدرس؟
اترك إعجابًا، أو شاركه مع شخص قد يستفيد منه.