
درس مصغّر · العربية
كيف تُبقي مفاتيح API خارج الواجهة الأمامية
استخدم المثال المرفق الذي يعمل عبر الخادم لإبقاء مفتاح المزود خارج متصفح الزائر، وتحقق من الطلبات المسموحة والمرفوضة.
لمن هذا الدرس؟
لمن يربطون موقعًا بخدمة ذكاء اصطناعي أو خدمة أخرى تتطلب صلاحيات. يستطيع مساعد برمجة توصيل المشروع الجاهز؛ والمطلوب فهم موضع استخدام السر، لا كتابة كود الخادم.
قبل أن تبدأ
وصولك الخاص إلى API في Google AI Studio، ومشروع تدريب منفصل لدوال Netlify. استخدم مساعد برمجة مع الحزمة كاملة وإعداد بيئة خاصة. تحقق من النموذج وحدود استخدام الحساب، بما فيها أي رسوم محتملة، قبل إرسال الطلبات. يستخدم المختبر رمز تدريب منفصلًا لدى المالك؛ وليس خدمة AI عامة جاهزة.
الوقت المتوقع: 20–32 دقيقة
تقديرات باستخدام ملفات البداية المرفقة، مع جاهزية الحسابات والأدوات المطلوبة. يستغرق الإعداد وانتظار النشر وتسليم البريد وتحديث DNS وقتًا إضافيًا. قد يستغرق إعداد المزوّد والحساب وقتًا أطول. يخضع الاستخدام لشروط حسابك وحصته الحاليتين.
ما الذي ستتعلمه؟
- ضع سر المزود في بيئة الخادم الخاصة فقط.
- شغّل الإجراء المرفق دون كشف المفتاح للزوار.
- اختبر محاولات الوصول الناجحة والمرفوضة.
الخطوة 1
اعرف أي قيمة يجب أن تبقى خاصة
ينبغي أن يستخدم المتصفح الميزة دون أن يستلم سر المزود.
افتح المشروع المرفق مع مساعدك. حدّد مفتاح المزود بوصفه قيمة خاصة بالحساب، ورمز التدريب المنفصل بوصفه وسيلة المالك للتحكم في الوصول إلى هذا المختبر الصغير.
لا يكفي أن يُسمّى الملف .env إذا كان البناء ينسخ قيمته إلى سكربتات عامة. اطلب من المساعد فحص الملفات الفعلية التي تصل إلى الزائر.
مثال عملي
الحقل المخفي في النموذج يبقى داخل المتصفح ولا يستطيع إخفاء مفتاح المزود.
افتح حزمة تدريب مفتاح API الجاهزة وأرشدني إلى إعدادها باتباع run-locally.txt. أبقِ مفتاح المزود واختيار النموذج على الخادم، واستخدم رمز وصول منفصلًا للتدريب. لا تضع أسرارًا في ملفات عامة ولا تطلب مني لصقها في رسائل مشتركة. ساعدني في فحص ما يستلمه المتصفح واختبار الطلبات المسموحة والمرفوضة. اشرح الدليل الذي يمكن ملاحظته بدل اشتراط أن أنفذ نقطة الاتصال بنفسي.ملفات هذه الخطوة
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
How it works (optional)
أبقِ مفاتيح API ذات الامتيازات خارج شيفرة المتصفح
يستطيع متصفح الزائر فحص كل ملف ترسله إليه.
قد يجيز سر المزوّد الإنفاق أو عمليات ذات امتيازات. وضعه في JavaScript عام أو حقل مخفي أو متغير بيئة يُستبدل أثناء بناء الواجهة الأمامية لا يزال يرسله إلى المتصفح.
يسأل المثال Gemini سؤالًا تعليميًا ثابتًا عبر دالة خادمك. يتلقى المتصفح الإجابة؛ ويبقى مفتاح المزوّد في بيئة الخادم. ليس كل مفتاح سريًا: مفاتيح Supabase القابلة للنشر مصممة للاستخدام في المتصفح مع سياسات وصول، أما مفاتيحها السرية فلا.
مثال محلول
افتح insecure-example.txt. القيمة الزائفة ظاهرة لأنها في الشيفرة المرسلة. تصغير السطر نفسه سيجعله أقل قابلية للقراءة، لكنه لن يغيّر من يتلقاه.
Extra implementation exercise
يُخزن مفتاح في .env ثم يُدرج في حزمة JavaScript العامة أثناء البناء. هل هو خاص بعيدًا عن الزوار؟
عرض حل نموذجي مشروح
لا. لا يهم مكان ملفه الأصلي بعد إدراجه في حزمة عامة. انقل العملية ذات الامتيازات إلى دالة خادم وأبقِ القيمة هناك.
- تتبع المفتاح إلى الحزمة المرسلة.
- تميّز بيئة الخادم عن الاستبدال في الواجهة الأمامية.
خطأ شائع
اعتبار كل متغير اسمه SECRET خاصًا بصرف النظر عن مكان إرساله.
الخطوة 2
شغّل الإجراء المحمي المرفق
دع المساعد يضبط مسار الخادم الموجود.
اتبع run-locally.txt وserver-env.example.txt مع المساعد. تحقق من الحساب والنموذج المقصودين وشروط الاستخدام، وضع مفتاح المزود في الخادم بصورة خاصة، وأنشئ رمز تدريب مستقلًا. شغّل المشروع كاملًا وافتح رابط التطبيق المحلي. فحوص الإعداد هذه مطلوبة؛ أما كتابة كود الدالة فاختيارية.
ينبغي أن يتواصل المتصفح مع ميزة الخادم لديك، بينما يستدعي الخادم المزود بصورة خاصة. إن فشل الإعداد أو الوصول أو الحصة، فاذكر تلك المرحلة بدل اختلاق رد.
مثال عملي
رمز تدريب النموذج ليس مفتاح مزود Google.
واجهة Gemini generateContent API · مفاتيح Gemini API · Gemini: معرّفات النماذج الحالية وقدراتها · Node.js: حالة دعم الإصدارات
جرّب بنفسك
هل عمل الإجراء؟ وما مرحلة الإعداد الخاص أو المزود التي ما زالت متعذرة؟
عرض حل نموذجي مشروح
مثال نتيجة جاهزية: «فتح المشروع الكامل عند رابط الخادم الوسيط المحلي. أعاد إجراء الخادم، بعد استخدام رمز الوصول التدريبي، شرحًا موجزًا لخادم الموقع. بقيت بيانات اعتماد المزود واختيار النموذج في البيئة الخاصة».
مثال عائق: «يعمل التطبيق، لكن المزود يبلغ بعدم توفر حصة استخدام؛ ولم ألاحظ ردًا ناجحًا». تحقق من النماذج المسموحة وحدود الحساب والرسوم المحتملة قبل تكرار الطلبات؛ فالدرس لا يعد باستدعاءات مجانية أو غير محدودة.
- يسجل رابط التطبيق المحلي الفعلي وإجراءً مسموحًا ناجحًا، أو عائق إعداد أو مزود محددًا.
- يبقي بيانات اعتماد المزود واختيار النموذج في الخادم، ويفحص شروط الحساب قبل استدعائه.
ملفات هذه الخطوة
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
How it works (optional)
ضع استدعاء المزوّد خلف نقطة نهاية خاصة بك
اضبط الخادم، ثم أرسل الطلب الصغير الذي تحتاج إليه الميزة فقط.
اقرأ 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: حالة دعم الإصدارات
Extra implementation exercise
ما الطلبان اللذان ينبغي وجودهما في المسار، وأيهما يجب ألا يظهر في أدوات Network بالمتصفح؟
عرض حل نموذجي مشروح
يعرض المتصفح استدعاءه لدالتك والإجابة المعادة. يجري الخادم طلب المزوّد؛ ويجب ألا يظهر استدعاء Google الذي يحمل بيانات اعتماد بوصفه طلب متصفح.
- ترى طلب المتصفح إلى دالة موقعك.
- تُبقي طلب Google المصادَق عليه في الخادم.
خطأ شائع
نسخ مساعد الخادم إلى public/ لإصلاح خطأ مسار.
الخطوة 3
افحص الخصوصية والفشل معًا
الرد المفيد لا يبرر انكشاف مفتاح.
اطلب من المساعد فحص الملفات العامة المرسلة وطلبات المتصفح بحثًا عن سر المزود دون عرضه في سجلات مشتركة. جرّب رمز تدريب خاطئًا وحالة غياب إعداد في المشروع القابل للحذف.
يجب ألا يظهر المفتاح الفعلي في ملفات المتصفح أو طلباته. يجب أن تبقى الطلبات المرفوضة أو غير المتاحة حالات فشل، مع طريقة عملية لإعادة المحاولة.
مثال عملي
رد مقنع مع مفتاح مكشوف في app.js يظل مهمة غير مكتملة.
جرّب بنفسك
ماذا أظهر فحص المخرجات العامة والمحاولة المرفوضة فعلًا؟
عرض حل نموذجي مشروح
مثال سجل خصوصية وأخطاء: «فحص المساعد الملفات العامة وطلب المتصفح إلى خادمي؛ ولم يظهر مفتاح المزود. رُفض رمز تدريب خاطئ. وعند إزالة إعداد المزود الخاص في البيئة المؤقتة، فشل الإجراء بدل عرض شرح مختلق».
يسجل ذلك الحد الذي فُحص، لا تدقيقًا أمنيًا كاملًا. إذا وُجد مفتاح في الملفات العامة، فتوقف عن مشاركة تلك النسخة واستبدل بيانات الاعتماد المكشوفة لدى المزود قبل استخدامها مجددًا.
- يوضح الملفات أو الطلبات العامة التي فحصها دون إعادة نشر سر المزود.
- يسجل محاولة وصول مرفوضة ومحاولة دون الإعداد المطلوب بوصفهما فشلين.
ملفات هذه الخطوة
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
How it works (optional)
تحقق من الحد الفاصل والإجابة معًا
الرد الناجح وحده لا يثبت أن المفتاح ظل خاصًا.
ابحث عن مفتاح المزوّد الفعلي في HTML والسكربتات العامة المنشورة دون لصقه في لقطات شاشة أو سجلات مشتركة. افحص طلبات المتصفح: قد يكون رمز التدريب ظاهرًا لمالكه، لكن يجب ألا يظهر مفتاح Gemini.
اختبر رمز تدريب خاطئًا وإعداد مزوّد مفقودًا في المشروع القابل للاستغناء عنه. يجب أن يبقى الفشل فشلًا. قد تشير حالة المزوّد 429 إلى حدود الحصة أو المعدل؛ وقد تشير 401 أو 403 إلى مشكلات وصول أو إعداد. لا تحوّلها جميعًا إلى إجابة ذكاء اصطناعي مختلقة.
مثال محلول
ينبغي أن يعيد رمز تدريب صحيح مع إعدادات مزوّد صالحة إجابة حقيقية. وينبغي أن ترفض نقطة النهاية نفسها الرمز الخاطئ قبل أي طلب للمزوّد.
Extra implementation exercise
تعمل الإجابة، لكن مفتاح المزوّد يظهر أيضًا في public/app.js. هل اكتملت المهمة؟
عرض حل نموذجي مشروح
لا. أزل المفتاح من الملفات العامة، واستبدله لأنه كُشف، وحدّث إعداد الخادم، وافحص النشر الجديد وسجل المستودع بحثًا عن كشف متبقٍ.
- ترفض اعتبار المخرجات الناجحة دليلًا كافيًا.
- تزيل التسريب وتستبدل المفتاح المكشوف.
خطأ شائع
إخفاء قيمة مسربة في الواجهة مع تركها في سكربت قابل للتنزيل.
الخطوة 4
نفّذ تعديلًا واحدًا محددًا بأمان
حافظ على حدود السر نفسها عند تعديل الميزة.
اطلب من المساعد تكييف العملية الثابتة المرفقة لشرح DNS بإيجاز. حافظ على إعدادات النموذج والمفتاح في الخادم، وعلى قصر التدريب على المالك.
اختبر الرد المقصود ورمز وصول غير صالح مجددًا. قبل الاستخدام العام، حدّد مصادقة فعلية وضوابط استخدام مستمرة ومراقبة لميزانيتك لدى المزود.
مثال عملي
ينبغي ألا ينقل تغيير موضوع الإجابة قيم الحساب الخاصة إلى الصفحة.
جرّب بنفسك
مواد البداية
ملفات البداية ومحتوى الاختبار مرفقة. التحقق الفعلي يتطلب حسابك أو بريدك أو نطاقك وفق المتطلبات السابقة. الفحص المحلي ممكن؛ سجّل الخطوات الحية التي لم تنفّذها على أنها غير مختبرة.
قدّم الإجراء المعدل واختبارات الخصوصية والطلب الصالح وغير الصالح التي نفذتها بالفعل.
ما المطلوب إنجازه سجل لفصل المفتاح ونتائج الطلب الصالح وغير الصالح للإجراء المرفق، بعد إزالة المعلومات الحساسة.
عرض حل نموذجي مشروح
مثال سجل تعديل: «أصبحت العملية الثابتة تشرح DNS في جملتين. أعاد استدعاء تدريبي مسموح هذا الموضوع؛ ورُفض رمز تدريب خاطئ؛ ولم يجد فحص الملفات العامة مفتاح المزود».
«قبل فتح هذه الخدمة للغرباء، ما زلت بحاجة إلى مصادقة فعلية وحدود استخدام مستديمة ومراقبة ميزانية المزود». رمز التدريب المشترك حد صغير للمختبر، وليس دليلًا على اكتمال خدمة عامة.
- يغير موضوع الرد الثابت إلى DNS، مع إبقاء المفتاح والنموذج في الخادم فقط.
- يعيد اختبار الاستدعاءات المسموحة والمرفوضة ويحدد ضوابط التكلفة والوصول الباقية قبل الاستخدام العام.
ملفات هذه الخطوة
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
How it works (optional)
مهمتك: انقل عملية ثابتة ثانية
كرر الحد الفاصل عن قصد بدل توسيعه بالخطأ.
غيّر مطالبة الخادم الثابتة لتشرح DNS في جملتين. أبقِ بيانات الاعتماد واختيار النموذج وحد المخرجات على الخادم؛ وأبقِ المتصفح دون معرفة مفتاح المزوّد.
سجّل النتيجة مع رمز تدريب صحيح وآخر غير صحيح. اشرح ما ستضيفه قبل الوصول العام: مستخدمين مصادَقًا عليهم أو حد وصول آخر ذا معنى، وحدود استخدام دائمة، ومراقبة لميزانية المزوّد.
مثال محلول
يثبت تغيير مطالبة ثابتة فهمك لمكان التحكم في سلوك المزوّد. قبول نماذج أو نقاط نهاية أو حدود مخرجات اعتباطية من المتصفح يلغي ذلك التحكم.
يتوفر الشرح المرجعي الكامل في reference/assignment-walkthrough.txt. قارن خطواته بنتيجتك؛ واملأ سجل الاختبار بملاحظات من مشروعك أنت.
Extra implementation exercise
أنجز نسخة DNS وسجل اختبار قصيرًا للحد الفاصل.
عرض حل نموذجي مشروح
في دالة mini-explain الخاصة بالخادم فقط، استبدل السؤال الثابت عن خادم الموقع بـ«Explain DNS in two sentences for a beginner.»، أي اشرح DNS في جملتين لمبتدئ. أبقِ المفتاح والنموذج في متغيرات بيئة الخادم؛ تعرض الدالة المرجعية الكاملة التعديل الدقيق.
افحص السكربتات المرسلة إلى المتصفح وطلبات Network. يرسل المتصفح طلبه إلى دالتك أنت؛ ويجب ألا يرسل GEMINI_API_KEY إلى Google بنفسه. رمز المختبر الذي يدخله المالك منفصل عن مفتاح المزوّد.
جرّب رمز تدريب خاطئًا: توقع رفضًا قبل أي استدعاء للمزوّد. يجب أن يظل فشل حصة أو شبكة المزوّد فشلًا صادقًا، لا إجابة نجاح جاهزة. إذا كُشف سر حقيقي، فأزله واستبدله؛ تجاهل الملف بعد ذلك لا يلغي الانكشاف.
- لا يُرسل سر مزوّد إلى المتصفح.
- يُرفض الوصول الخاطئ ويظهر فشل المزوّد بصدق.
خطأ شائع
وصف الورشة المقيدة بأنها خدمة ذكاء اصطناعي عامة جاهزة للإنتاج.
هل أفادك هذا الدرس؟
اترك إعجابًا، أو شاركه مع شخص قد يستفيد منه.
واصل التعلّم
- كيف تنشئ أول موقع شخصي لك
- كيف تنشر موقعك من GitHub
- كيف تربط نطاقًا مخصصًا بموقعك
- كيف تعدّ البريد على نطاقك الخاص
- كيف تجعل موقعك قابلًا للاستخدام على الهواتف
- كيف تجعل صور موقعك تُحمّل أسرع
- كيف تصلك ملاحظات الموقع إلى صندوق بريدك
- كيف تضيف اشتراكات البريد إلى موقعك
- كيف ترسل رسائل بريد آلية من موقعك
- كيف تحفظ إرساليات النماذج في قاعدة بيانات
- كيف تتيح للناس تسجيل الدخول إلى موقعك
- كيف تُبقي صفحة خاصة
- كيف تتيح للمستخدمين تعديل معلومات ملفاتهم الشخصية
- كيف تتيح للمستخدمين رفع الصور
- كيف تعرض بيانات من واجهة API خارجية على موقعك
- كيف تضيف روبوت محادثة بالذكاء الاصطناعي إلى موقعك
- كيف تجعل روبوت محادثة يجيب من محتواك الخاص
- كيف تضيف مدونة إلى موقعك
- كيف تضيف بحثًا إلى موقعك
- كيف تضيف لغة أخرى إلى موقعك
- كيف تساعد Google على العثور على موقعك
- كيف تصلح معاينة موقعك عند مشاركة رابط
- كيف تقيس الزيارات والإجراءات المفيدة على موقعك
- كيف تتيح للزوار حجز موعد
- كيف تقبل دفعة مالية على موقعك
- كيف تعاين تغييرات موقعك قبل النشر
- كيف تتراجع عن نشر موقع معطّل
- كيف تنسخ بيانات موقعك احتياطيًا وتستعيدها
- كيف تجد الأخطاء في موقعك المنشور وتصلحها