احراز هویت و کلیدهای API

Discuse API هر درخواست را با یک کلید API احراز هویت می‌کند. آن را در سربرگ درخواست X-API-Key بفرستید (یا به‌صورت فیلد api_key در بدنه JSON). کلیدها با پیشوند disc_ شروع می‌شوند، به یک پروژه واحد متصل‌اند، و فقط یک‌بار هنگام ایجاد به‌طور کامل نمایش داده می‌شوند. این راهنما توضیح می‌دهد چگونه آن‌ها را دریافت، استفاده، ایمن‌سازی و چرخش دهید.

احراز هویت Discuse چگونه کار می‌کند؟

هر فراخوانی API باید شامل یک کلید API معتبر باشد. Discuse از آن برای موارد زیر استفاده می‌کند:

• ردیابی مصرف نسبت به سهمیه پروژه شما
• اعمال محدودسازی نرخ برای هر کلید جهت جلوگیری از سوءاستفاده
• اتصال درخواست‌ها به پروژه درست و تنظیمات آن
• کنترل دسترسی به منابع حساب شما

دریافت کلید API شما

گام ۱: ایجاد حساب

اگر هنوز این کار را انجام نداده‌اید، در discuse.com برای یک حساب Discuse ثبت‌نام کنید. می‌توانید با طرح رایگان Basic شروع کنید که شامل سهمیه ماهانه‌ای از درخواست‌های API به‌همراه دسترسی به بررسی‌های متن، اسپم، زبان و تصویر است. برای محدودیت‌های فعلی هر طرح، صفحه قیمت‌گذاری را ببینید.

گام ۲: دسترسی به داشبورد

پس از ورود، به داشبورد خود بروید. در منوی ناوبری، بخش "API Keys" یا "Developer" را پیدا کنید.

گام ۳: ایجاد یک کلید جدید

روی "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. کلید قدیمی را لغو کنید

نکته: یک کلید لغوشده ممکن است تا حدود ۵ دقیقه همچنان قابل استفاده بماند، چون کلیدهای اعتبارسنجی‌شده در کش نگه داشته می‌شوند. هنگام برنامه‌ریزی چرخش‌ها، این هم‌پوشانی کوتاه را در نظر بگیرید و انتظار تغییر آنی نداشته باشید.

برای محیط‌های مختلف از کلیدهای جداگانه استفاده کنید

برای توسعه، staging و production کلیدهای API متفاوت ایجاد کنید:

محیط	هدف کلید
توسعه	آزمایش و توسعه محلی
Staging	آزمایش پیش از production
Production	ترافیک برنامه زنده

این کار به شما اجازه می‌دهد یک کلید در معرض خطر را بدون تأثیر گذاشتن بر محیط‌های دیگر لغو کنید.

محدودسازی نرخ چگونه کار می‌کند؟

محدودسازی نرخ برای هر کلید API اعمال می‌شود، نه برای هر طرح. هر کلید هنگام ایجاد، یک محدودیت درخواست در دقیقه (RPM) دارد؛ اگر مقداری مشخص نکنید، مقدار پیش‌فرض آن ۶۰ درخواست در دقیقه است. کلیدهای مختلف در یک حساب می‌توانند محدودیت‌های متفاوتی داشته باشند، بنابراین می‌توانید برای یک سرویس پرترافیک 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
درخواست بدشکل (محتوای خالی، متن بیش از ۱۰٬۰۰۰ کاراکتر، 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. کلیدهای مخصوص هر محیط: کلیدهای جداگانه برای dev، staging و production
2. کلیدهای مخصوص هر سرویس: کلیدهای متفاوت برای میکروسرویس‌های مختلف
3. کلیدهای مخصوص هر تیم: جداسازی مصرف بر اساس تیم برای صورتحساب داخلی
4. کلیدهای موقت: کلیدهای کوتاه‌مدت برای پیمانکاران یا یکپارچه‌سازی‌ها

بهترین روش‌های مدیریت کلید

• برای کلیدها نام‌های توصیفی بگذارید: "Production - User Service"، "Staging - Backend"
• مصرف کلیدها را مستندسازی کنید: سوابقی نگه دارید که نشان دهد هر کلید کجا استفاده می‌شود
• هشدارها را تنظیم کنید: الگوهای مصرف غیرعادی را پایش کنید
• ممیزی‌های منظم انجام دهید: کلیدهای استفاده‌نشده را هر سه‌ماه یک‌بار بررسی و پاک‌سازی کنید

گام‌های بعدی

• راهنمای شروع سریع - اولین فراخوانی API خود را انجام دهید
• تحلیل متن - درباره تشخیص احساسات یاد بگیرید
• مقیاس‌پذیر کردن تعدیل محتوا - الگوهای پیاده‌سازی برای حجم بالا