مفاتيح API (صفحة المطوّرين)

🌐 هذه الترجمة قيد المراجعة المجتمعية. هل لاحظت خطأً أو صياغة غير طبيعية؟ اضغط عدّل هذه الصفحة على GitHub في الأسفل واقترح تحسيناً.

إن كنت تبني شيئاً فوق معرض القرآن — مشروعاً جانبياً، لوحة شخصية، سيناريو أتمتة — فبإمكانك توليد مفاتيح API شخصية تثبت أن الطلب من قِبلك، دون الحاجة إلى جلسة متصفّح.

تُدار مفاتيح API كلها من صفحة المطوّرين في حسابك.

كيف تصل إلى صفحة المطوّرين

سجّل دخولك إلى accounts.qurangallery.com، ثم اذهب إلى accounts.qurangallery.com/developers. كثير من القوائم تربط إليها مباشرة.

ما هو مفتاح API

مفتاح API سلسلة سرّية طويلة شكلها:

qg_abc123def456...

البادئة qg_ تميّزه كمفتاح معرض القرآن. عند إرساله في ترويسة Authorization: Bearer ... على طلب إلى معرض القرآن، يعامله الخادم كأنّك أنت من أرسله. إذن مفتاح API بمثابة كلمة مرور لحسابك مخصّصة للاستخدام البرمجي — تعامل معه كذلك.

إنشاء مفتاح

1. على صفحة المطوّرين، اعثر على بطاقة Create New Key.
2. اكتب اسماً وصفياً — "سكريبت تصدير تقدّم الحفظ"، "لوحة Raspberry Pi"، "دف محلّي". الاسم لك فقط — يظهر في قائمة المفاتيح لتذكّر أيّها أيّ.
3. اضغط Create key.

يظهر المفتاح الجديد في أعلى الصفحة في بطاقة خضراء مع قيمته الكاملة. هذه المرة الوحيدة التي تراه فيها كاملاً. اضغط أيقونة النسخ لوضعه في حافظتك، ثم احفظه آمناً: مدير كلمات مرور، مدير أسرار سحابي، ملف .env خارج التحكّم بالإصدار.

بعد ضغطك Done، تختفي البطاقة الخضراء، ومن تلك اللحظة لا ترى إلا أول أحرف المفتاح (الـ”start”) في قائمة المفاتيح. لا توجد طريقة لاسترجاع القيمة الكاملة مرة أخرى — إن فقدته يجب إنشاء مفتاح جديد وحذف القديم.

قائمة المفاتيح

أسفل نموذج الإنشاء، ترى كل مفتاح موجود على حسابك.

لكل مفتاح:

• الاسم — ما كتبته عند الإنشاء.
• الحالة — Active (حبّة خضراء) أو Disabled (حبّة رمادية).
• البداية — أول أحرف المفتاح، مثل qg_abc12.... كافٍ لتحديد المفتاح دون كشف السر.
• تاريخ الإنشاء.

يميناً لكل صف، أيقونة سلّة تحذف المفتاح. الحذف دائم وفوري — أي سكريبت يستخدم المفتاح المحذوف يبدأ بتلقّي 401 على طلبه التالي.

استخدام مفتاح

أرسله في ترويسة Authorization على الطلبات:

Authorization: Bearer qg_abc123def456...

بطاقة الاستخدام تعرض الصيغة بالضبط. نفس المفتاح يصادقك عبر كل خدمات معرض القرآن التي تدعم مفاتيح API.

طلبات مفاتيح API تتجاوز جلسة المتصفّح، فيمكنك استخدامها من مهام CI أو مهام مجدولة أو تطبيقات هاتف.

حدود السرعة

كل مفتاح محدّد بـ 60 طلباً في الدقيقة، نافذة منزلقة. هذا يكفي للاستخدام الشخصي وأغلب السكربتات. إن تجاوزت، يعيد API رمز HTTP 429 مع ترويسات تخبرك متى تستطيع المحاولة. انتظر ثم استأنف.

مفاتيح API لحسابات موقوفة أو محذوفة تتوقّف فوراً.

تدوير المفاتيح

أفضل ممارسة دوّر المفاتيح كلّما:

• ضاع لابتوب أو جهاز يحوي المفتاح.
• شاركت المفتاح مع متعاون لم يعد يحتاج الوصول.
• مضى وقت طويل وترجو تجنّب سرّ غير مدوَّر.

التدوير عملية يدوية من خطوتين:

1. أنشئ مفتاحاً جديداً باسم وصفي.
2. حدّث سكريباتك لاستخدامه.
3. عند انتقال كل شيء، احذف القديم.

لا توجد ميزة تدوير آلية اليوم.

فقدت مفتاحي

لا يمكن لمعرض القرآن استرجاع مفتاح مفقود. احذف القديم من القائمة (حتى يتوقف عمله إن وقع بيد أحد) وأنشئ جديداً. حدِّث سكريبتك بالقيمة الجديدة.

قائمة فحص الأمان

• لا تُلصق مفتاحاً في git أبداً. استخدم ملف .env (وأضفه إلى .gitignore) أو مدير أسرار منصّتك.
• لا تُلصق مفتاحاً في Slack أو Discord أو GitHub أو محادثة AI عامة. عامله ككلمة مرور تماماً.
• استخدم مفتاحاً واحداً لكل مشروع لا واحداً لكل شيء.
• إن شككت في تسرّب مفتاح، احذفه أولاً ثم أنشئ جديداً. الترتيب مهم.
• لا تَخْبز مفاتيح في الكود الذي يعمل في المتصفّح أو ثنائيات تطبيقات الهاتف.

أخطاء شائعة