المصادقة ومفاتيح API

يصادق Discuse API على كل طلب باستخدام مفتاح API. أرسله في ترويسة الطلب X-API-Key (أو كحقل api_key داخل جسم JSON). تبدأ المفاتيح بالبادئة disc_، وترتبط بمشروع واحد فقط، ولا تُعرض كاملة إلا مرة واحدة عند إنشائها. يوضح هذا الدليل كيفية الحصول عليها واستخدامها وتأمينها وتدويرها.

كيف تعمل المصادقة في Discuse؟

يجب أن يتضمن كل استدعاء API مفتاح API صالحًا. يستخدمه Discuse من أجل:

• تتبّع الاستخدام ضمن حصة مشروعك
• تطبيق تحديد معدل الاستخدام لكل مفتاح لمنع إساءة الاستخدام
• ربط الطلبات بالمشروع الصحيح وإعداداته
• التحكم في الوصول إلى موارد حسابك

الحصول على مفتاح API الخاص بك

الخطوة 1: إنشاء حساب

إذا لم تكن قد فعلت ذلك بعد، فسجّل للحصول على حساب Discuse على discuse.com. يمكنك البدء بالخطة Basic المجانية، التي تتضمن حصة شهرية من طلبات API بالإضافة إلى الوصول إلى فحوصات النصوص والرسائل المزعجة واللغة والصور. راجع صفحة الأسعار للاطلاع على الحدود الحالية لكل خطة.

الخطوة 2: الوصول إلى لوحة التحكم

بعد تسجيل الدخول، انتقل إلى لوحة التحكم الخاصة بك. ابحث عن قسم "API Keys" أو "Developer" في قائمة التنقل.

الخطوة 3: إنشاء مفتاح جديد

انقر على "Create New API Key" ويمكنك اختياريًا إدخال اسم أو وصف للمفتاح. يساعدك ذلك على معرفة الغرض من كل مفتاح إذا أنشأت عدة مفاتيح.

سيُعرض مفتاح API الجديد مرة واحدة فقط. انسخه فورًا واحفظه في مكان آمن - فلن تتمكن من عرض المفتاح كاملًا مرة أخرى.

استخدام مفتاح API الخاص بك

ضمّن مفتاح API في ترويسة X-API-Key لكل طلب:

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345" \
  -d '{
    "content": {
      "text": "Content to analyze"
    }
  }'

يمكنك بدلًا من ذلك تمرير المفتاح كحقل api_key داخل جسم JSON بدلًا من الترويسة — لكن يُفضّل استخدام الترويسة حتى لا ينتهي المفتاح في سجلات أجسام الطلبات.

مثال JavaScript

const response = await fetch('https://api.discuse.com/api/v2/check', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.DISCUSE_API_KEY
  },
  body: JSON.stringify({
    content: { text: 'Content to analyze' }
  })
});

مثال Python

import requests
import os

response = requests.post(
    'https://api.discuse.com/api/v2/check',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['DISCUSE_API_KEY']
    },
    json={
        'content': {'text': 'Content to analyze'}
    }
)

أفضل ممارسات أمان مفتاح API

لا تكشف المفاتيح أبدًا في كود جهة العميل

يجب ألا تُضمَّن مفاتيح API أبدًا في JavaScript الذي يعمل داخل المتصفح. فكود جهة العميل مرئي لأي شخص يطّلع على مصدر صفحتك.

// WRONG - Don't do this!
const API_KEY = 'disc_aB3dEf6...'; // Exposed in browser

// CORRECT - Use a backend proxy
const response = await fetch('/api/moderate', {
  method: 'POST',
  body: JSON.stringify({ text: userInput })
});

استخدم متغيرات البيئة

احفظ مفاتيح API في متغيرات البيئة، وليس في قاعدة الكود لديك:

# .env file (add to .gitignore!)
DISCUSE_API_KEY=disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345

// Access in Node.js
const apiKey = process.env.DISCUSE_API_KEY;

دوّر المفاتيح بانتظام

دوّر مفاتيح API الخاصة بك دوريًا، خاصة إذا كنت تشتبه في احتمال تعرّضها للاختراق:

1. أنشئ مفتاح API جديدًا
2. حدّث تطبيقك لاستخدام المفتاح الجديد
3. تحقّق من أن كل شيء يعمل بشكل صحيح
4. ألغِ المفتاح القديم

ملاحظة: قد يظل المفتاح الملغى قابلًا للاستخدام لمدة تصل إلى نحو 5 دقائق لأن المفاتيح التي تم التحقق منها تُخزَّن مؤقتًا. خطط لعمليات التدوير مع وضع هذا التداخل القصير في الحسبان بدلًا من توقع الانتقال الفوري.

استخدم مفاتيح منفصلة للبيئات المختلفة

أنشئ مفاتيح API مختلفة للتطوير ومرحلة الاختبار والإنتاج:

البيئة	الغرض من المفتاح
التطوير	الاختبار والتطوير المحلي
مرحلة الاختبار	الاختبار قبل الإنتاج
الإنتاج	حركة مرور التطبيق الفعلية

يتيح لك ذلك إلغاء مفتاح مخترق دون التأثير في البيئات الأخرى.

كيف يعمل تحديد معدل الاستخدام؟

يُطبَّق تحديد معدل الاستخدام لكل مفتاح API، وليس لكل خطة. لكل مفتاح حد لعدد الطلبات في الدقيقة (RPM) يُحدَّد عند إنشاء المفتاح؛ وإذا لم تحدد حدًا، فسيكون الافتراضي 60 طلبًا في الدقيقة. يمكن أن تحمل مفاتيح مختلفة على الحساب نفسه حدودًا مختلفة، بحيث يمكنك منح خدمة ذات إنتاجية عالية معدل RPM أعلى من تكامل لمرة واحدة.

عندما يتجاوز مفتاح حد RPM الخاص به، يفشل الطلب بحالة HTTP 429 Too Many Requests وتوضح قيمة message أن حد معدل الاستخدام قد تم تجاوزه. تُصفَّر عدادات تحديد المعدل ضمن نافذة متحركة مدتها دقيقة واحدة.

التعامل مع حدود معدل الاستخدام

تراجع ثم أعد المحاولة عند ظهور 429 (وكذلك عند أخطاء 5xx العابرة). وبما أن النافذة مدتها دقيقة واحدة، فإن التراجع الأُسّي الذي يبدأ بنحو ثانية واحدة ثم يزداد يعمل جيدًا:

async function checkWithRetry(content, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('https://api.discuse.com/api/v2/check', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.DISCUSE_API_KEY
      },
      body: JSON.stringify({ content })
    });

    if (response.status === 429 || response.status >= 500) {
      const delay = 1000 * Math.pow(2, attempt); // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response.json();
  }
  throw new Error('Max retries exceeded');
}

ما استجابات الخطأ التي يمكن أن أتلقاها؟

الحالة	حالة HTTP
طلب غير صحيح البنية (محتوى فارغ، نص يتجاوز 10,000 حرف، عدد كبير جدًا من عناوين URL)	400 التحقق من صحة الطلب
مفتاح API مفقود أو غير صالح	401
تم تجاوز حد معدل الاستخدام للمفتاح	429
نفدت حصة فترة الفوترة	200 مع message و usage (ليست حالة خطأ)

استنفاد الحصة ليس خطأ HTTP عن قصد: فما زالت استجابة /api/v2/check تُرجع 200 مع has_violations: false، وmessage يصف الحصة المستنفدة، وكائن usage يعرض api_requests_remaining: 0. افحص هذه الحقول بدلًا من الاعتماد على رمز الحالة. تُرجع حالات فشل المصادقة 401، وحدود معدل الاستخدام 429، وحالات فشل التحقق من صحة الطلب 400. راجع مرجع رموز الأخطاء والاستجابات للاطلاع على القائمة الكاملة.

إدارة مفاتيح متعددة

بالنسبة إلى الفرق الأكبر أو التطبيقات المعقدة، قد تحتاج إلى عدة مفاتيح API:

حالات استخدام المفاتيح المتعددة

1. مفاتيح لكل بيئة: مفاتيح منفصلة للتطوير ومرحلة الاختبار والإنتاج
2. مفاتيح لكل خدمة: مفاتيح مختلفة للخدمات المصغّرة المختلفة
3. مفاتيح لكل فريق: عزل الاستخدام حسب الفريق لأغراض الفوترة الداخلية
4. مفاتيح مؤقتة: مفاتيح قصيرة العمر للمقاولين أو التكاملات

أفضل ممارسات إدارة المفاتيح

• سمِّ المفاتيح بأسماء وصفية: "Production - User Service", "Staging - Backend"
• وثّق استخدام المفاتيح: احتفظ بسجلات توضّح أين يُستخدم كل مفتاح
• أعدّ التنبيهات: راقب أنماط الاستخدام غير المعتادة
• أجرِ مراجعات منتظمة: راجع المفاتيح غير المستخدمة ونظّفها كل ثلاثة أشهر

الخطوات التالية

• دليل البدء السريع - أجرِ أول استدعاء API لك
• تحليل النصوص - تعرّف على اكتشاف المشاعر
• توسيع نطاق الإشراف على المحتوى - أنماط التنفيذ عالية الحجم