دليل البدء السريع

لإدارة المحتوى باستخدام Discuse، أرسل طلب POST إلى https://api.discuse.com/api/v2/check مع ترويسة X-API-Key وجسم JSON يحتوي على النص أو عناوين URL للصور أو عناوين URL للملفات التي تريد فحصها. تُرجع الاستجابة تفصيلاً حسب كل فئة، إضافةً إلى علم واحد هو has_violations. يرشدك هذا الدليل خلال أول استدعاء، وتنسيق الاستجابة، والتعامل الأساسي مع الأخطاء — في نحو خمس دقائق من البداية إلى النهاية.

المتطلبات الأساسية

قبل أن تبدأ، تأكد من توفر ما يلي لديك:

1. حساب Discuse (سجّل في discuse.com)
2. مفتاح API من لوحة التحكم لديك
3. أداة لإجراء طلبات HTTP (مثل cURL أو Postman أو شيفرة تطبيقك)

الخطوة 1: احصل على مفتاح API الخاص بك

بعد التسجيل، انتقل إلى لوحة التحكم لديك وابحث عن قسم مفاتيح API. انقر على "إنشاء مفتاح جديد" لإنشاء مفتاح API جديد. احتفظ بهذا المفتاح في مكان آمن - فهو يتيح الوصول إلى حسابك وحصة الاستخدام الخاصة بك.

يبدأ كل مفتاح من Discuse بالبادئة disc_، على سبيل المثال:

disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345-_6789

الخطوة 2: نفّذ أول استدعاء API لك

أبسط طريقة لاختبار API هي إرسال طلب تحليل نص. إليك مثالاً أساسياً باستخدام cURL:

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": {
      "text": "Hello, this is a test message to analyze!"
    }
  }'

الخطوة 3: افهم الاستجابة

يعيد الطلب الناجح استجابة JSON تتضمن نتائج التحليل:

{
  "has_violations": false,
  "cached": false,
  "results": {
    "hits": false,
    "sentiment": {
      "is_negative": false,
      "is_toxic": false,
      "score": 0.03,
      "toxic": 0.02,
      "profanity": 0.01,
      "threat": 0.00,
      "insult": 0.03,
      "hit": false
    },
    "spamfinder": {
      "label": "ham",
      "confidence": 0.08,
      "is_spam": false,
      "hit": false
    },
    "language": {
      "language": "en",
      "confidence": 0.98
    }
  },
  "usage": {
    "api_requests_used": 42,
    "api_requests_limit": 1000,
    "api_requests_remaining": 958
  }
}

لا يتم تضمين processing_time_ms إلا عند تفعيل قياس الوقت في إعدادات مشروعك، ولا يتم تعيين message إلا في استجابات تجاوز الحصة — لذلك تم حذفهما معاً من المثال أعلاه.

شرح حقول الاستجابة

الحقل	الوصف
has_violations	قيمة منطقية: true إذا أشّر أي فحص مفعّل على المحتوى (تعكس results.hits)
cached	ما إذا كانت هذه النتيجة قد قُدّمت من ذاكرة التخزين المؤقت (ولا تزال تُحتسب طلباً واحداً من الحصة)
results.hits	علم الإصابة الإجمالي عبر جميع الفحوص
results.sentiment	درجات السُميّة من 0.0 (آمن) إلى 1.0 (شديد السُميّة)، بالإضافة إلى أعلام القرار is_toxic/hit
results.spamfinder	حكم الرسائل غير المرغوب فيها: label وconfidence وis_spam (خام) وhit (يراعي العتبة)
results.language	رمز language المكتشف ودرجة confidence
usage	عدد طلبات API لديك، والحد الأقصى، والحصة المتبقية لفترة الفوترة الحالية

الخطوة 4: حلّل صورة

لفحص صورة بحثاً عن محتوى NSFW، ضمّن عنوان URL للصورة في طلبك:

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": {
      "image_urls": ["https://example.com/image.jpg"]
    },
    "settings": {
      "check_images": true
    }
  }'

الخطوة 5: اجمع عدة فحوص

يمكنك تحليل النصوص والصور معاً في طلب واحد:

{
  "content": {
    "text": "Check out this amazing photo!",
    "image_urls": ["https://example.com/photo.jpg"]
  },
  "settings": {
    "check_sentiment": true,
    "check_spam": true,
    "check_images": true,
    "check_language": true
  }
}

أمثلة التكامل

JavaScript/Node.js

async function checkContent(text) {
  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 }
    })
  });

  return response.json();
}

// Usage
const result = await checkContent('Hello world!');
if (result.has_violations) {
  console.log('Content flagged:', result.message);
}

Python

import requests
import os

def check_content(text):
    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': text}
        }
    )
    return response.json()

# Usage
result = check_content('Hello world!')
if result['has_violations']:
    print(f"Content flagged: {result['message']}")

هل يُحتسب التخزين المؤقت من حصتي؟

يخزّن Discuse نتائج المحتوى المتطابق مؤقتاً لبضع دقائق. عندما تعود الاستجابة وفيها "cached": true، فهذا يعني أنها قُدّمت من ذاكرة التخزين المؤقت، لذا تعود بشكل أسرع وتتجاوز إعادة تشغيل الفحوص. لا يزال الطلب يُحتسب كطلب API واحد من حصتك، لكنك لا تُحاسَب مجدداً على عمليات الفحص الأساسية لكل ميزة (الصور، مكافحة الفيروسات). يفيد التخزين المؤقت أساساً عندما يُرسَل المحتوى نفسه مراراً خلال فترة قصيرة.

كيف أتعامل مع الأخطاء؟

يعيد الفحص الناجح HTTP 200. أما المفتاح غير الصحيح، أو تجاوز حد المعدل، أو الطلب سيئ التنسيق فيعيد حالة ليست من فئة 2xx. لاحظ أن استنفاد الحصة ليس خطأ HTTP: عند استهلاك حصة فترة الفوترة لديك بالكامل، لا يزال API يعيد 200 مع has_violations: false وmessage تشرح أن الحصة قد تم تجاوزها — افحص حقلي message وusage بدلاً من الاعتماد على رمز الحالة.

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

  if (!response.ok) {
    if (response.status === 401 || response.status === 403) {
      throw new Error('Invalid or unauthorized API key');
    } else if (response.status === 429) {
      throw new Error('Rate limit exceeded - slow down requests');
    }
    throw new Error(`API error: ${response.status}`);
  }

  const result = await response.json();

  // Quota exhaustion is returned as a 200 with a message, not an error status.
  if (result.message && result.usage && result.usage.api_requests_remaining === 0) {
    console.warn('Quota exceeded:', result.message);
  }

  return result;
} catch (error) {
  console.error('Content check failed:', error);
  throw error;
}

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

بعد أن نفّذت أول استدعاء API لك، استكشف هذه الموارد:

• المصادقة ومفاتيح API - تعرّف على الإدارة الآمنة للمفاتيح
• تحليل النصوص - تعمّق في رصد المشاعر والرسائل غير المرغوب فيها
• اكتشاف صور NSFW - احمِ منصتك من الصور غير الملائمة
• تهيئة العتبات - اضبط حساسية الاكتشاف بدقة