درس مصغّر · العربية

كيف تُبقي مفاتيح API خارج الواجهة الأمامية

استخدم المثال المرفق الذي يعمل عبر الخادم لإبقاء مفتاح المزود خارج متصفح الزائر، وتحقق من الطلبات المسموحة والمرفوضة.

ابدأ الدرس التفاعلياقرأ ملاحظات الدرس

لمن هذا الدرس؟

لمن يربطون موقعًا بخدمة ذكاء اصطناعي أو خدمة أخرى تتطلب صلاحيات. يستطيع مساعد برمجة توصيل المشروع الجاهز؛ والمطلوب فهم موضع استخدام السر، لا كتابة كود الخادم.

قبل أن تبدأ

وصولك الخاص إلى API في Google AI Studio، ومشروع تدريب منفصل لدوال Netlify. استخدم مساعد برمجة مع الحزمة كاملة وإعداد بيئة خاصة. تحقق من النموذج وحدود استخدام الحساب، بما فيها أي رسوم محتملة، قبل إرسال الطلبات. يستخدم المختبر رمز تدريب منفصلًا لدى المالك؛ وليس خدمة AI عامة جاهزة.

الوقت المتوقع: 20–32 دقيقة

تقديرات باستخدام ملفات البداية المرفقة، مع جاهزية الحسابات والأدوات المطلوبة. يستغرق الإعداد وانتظار النشر وتسليم البريد وتحديث DNS وقتًا إضافيًا. قد يستغرق إعداد المزوّد والحساب وقتًا أطول. يخضع الاستخدام لشروط حسابك وحصته الحاليتين.

ما الذي ستتعلمه؟

  • ضع سر المزود في بيئة الخادم الخاصة فقط.
  • شغّل الإجراء المرفق دون كشف المفتاح للزوار.
  • اختبر محاولات الوصول الناجحة والمرفوضة.

ملفات ورشة العمل

الخطوة 1

اعرف أي قيمة يجب أن تبقى خاصة

ينبغي أن يستخدم المتصفح الميزة دون أن يستلم سر المزود.

افتح المشروع المرفق مع مساعدك. حدّد مفتاح المزود بوصفه قيمة خاصة بالحساب، ورمز التدريب المنفصل بوصفه وسيلة المالك للتحكم في الوصول إلى هذا المختبر الصغير.

لا يكفي أن يُسمّى الملف .env إذا كان البناء ينسخ قيمته إلى سكربتات عامة. اطلب من المساعد فحص الملفات الفعلية التي تصل إلى الزائر.

مثال عملي

الحقل المخفي في النموذج يبقى داخل المتصفح ولا يستطيع إخفاء مفتاح المزود.

افتح حزمة تدريب مفتاح API الجاهزة وأرشدني إلى إعدادها باتباع run-locally.txt. أبقِ مفتاح المزود واختيار النموذج على الخادم، واستخدم رمز وصول منفصلًا للتدريب. لا تضع أسرارًا في ملفات عامة ولا تطلب مني لصقها في رسائل مشتركة. ساعدني في فحص ما يستلمه المتصفح واختبار الطلبات المسموحة والمرفوضة. اشرح الدليل الذي يمكن ملاحظته بدل اشتراط أن أنفذ نقطة الاتصال بنفسي.

ملفات هذه الخطوة

Start hereملفات ورشة العمل

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 العامة أثناء البناء. هل هو خاص بعيدًا عن الزوار؟

عرض حل نموذجي مشروح

لا. لا يهم مكان ملفه الأصلي بعد إدراجه في حزمة عامة. انقل العملية ذات الامتيازات إلى دالة خادم وأبقِ القيمة هناك.

  • تتبع المفتاح إلى الحزمة المرسلة.
  • تميّز بيئة الخادم عن الاستبدال في الواجهة الأمامية.

الخطوة 2

شغّل الإجراء المحمي المرفق

دع المساعد يضبط مسار الخادم الموجود.

اتبع run-locally.txt وserver-env.example.txt مع المساعد. تحقق من الحساب والنموذج المقصودين وشروط الاستخدام، وضع مفتاح المزود في الخادم بصورة خاصة، وأنشئ رمز تدريب مستقلًا. شغّل المشروع كاملًا وافتح رابط التطبيق المحلي. فحوص الإعداد هذه مطلوبة؛ أما كتابة كود الدالة فاختيارية.

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

مثال عملي

رمز تدريب النموذج ليس مفتاح مزود Google.

واجهة Gemini generateContent API · مفاتيح Gemini API · Gemini: معرّفات النماذج الحالية وقدراتها · Node.js: حالة دعم الإصدارات

ملفات هذه الخطوة

Start hereملفات ورشة العمل

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 المصادَق عليه في الخادم.

الخطوة 3

افحص الخصوصية والفشل معًا

الرد المفيد لا يبرر انكشاف مفتاح.

اطلب من المساعد فحص الملفات العامة المرسلة وطلبات المتصفح بحثًا عن سر المزود دون عرضه في سجلات مشتركة. جرّب رمز تدريب خاطئًا وحالة غياب إعداد في المشروع القابل للحذف.

يجب ألا يظهر المفتاح الفعلي في ملفات المتصفح أو طلباته. يجب أن تبقى الطلبات المرفوضة أو غير المتاحة حالات فشل، مع طريقة عملية لإعادة المحاولة.

مثال عملي

رد مقنع مع مفتاح مكشوف في app.js يظل مهمة غير مكتملة.

ملفات هذه الخطوة

Start hereملفات ورشة العمل

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 بإيجاز. حافظ على إعدادات النموذج والمفتاح في الخادم، وعلى قصر التدريب على المالك.

اختبر الرد المقصود ورمز وصول غير صالح مجددًا. قبل الاستخدام العام، حدّد مصادقة فعلية وضوابط استخدام مستمرة ومراقبة لميزانيتك لدى المزود.

مثال عملي

ينبغي ألا ينقل تغيير موضوع الإجابة قيم الحساب الخاصة إلى الصفحة.

ملفات هذه الخطوة

Start hereملفات ورشة العمل

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 بنفسه. رمز المختبر الذي يدخله المالك منفصل عن مفتاح المزوّد.

جرّب رمز تدريب خاطئًا: توقع رفضًا قبل أي استدعاء للمزوّد. يجب أن يظل فشل حصة أو شبكة المزوّد فشلًا صادقًا، لا إجابة نجاح جاهزة. إذا كُشف سر حقيقي، فأزله واستبدله؛ تجاهل الملف بعد ذلك لا يلغي الانكشاف.

  • لا يُرسل سر مزوّد إلى المتصفح.
  • يُرفض الوصول الخاطئ ويظهر فشل المزوّد بصدق.

هل أفادك هذا الدرس؟

اترك إعجابًا، أو شاركه مع شخص قد يستفيد منه.

واصل التعلّم

استكشف الدروس الأخرى