درس Server API لديسكورد: إحصاءات مباشرة بـ JavaScript

يشرح هذا الدرس إنشاء مفتاح Noxyr Server API، واستدعاء النقاط الست من Node.js والمتصفح، ووضع بيانات ديسكورد المباشرة على صفحة عامة. إذا كنت تريد يوماً عدّاد أعضاء حقيقياً على موقعك يتحدّث دون اتصال بوت، فهذا هو الحل.

الخطوة 1: أنشئ المفتاح

افتح لوحة تحكم Noxyr، واختر سيرفرك، وانتقل إلى API Access. اضغط Generate API Key. يظهر المفتاح (يبدأ بـ nxr_) مرة واحدة فقط، فانسخه إلى متغير بيئة الآن. لا يُخزَّن على الخادم سوى هاش SHA-256، لذا إذا فُقد المفتاح فيجب إنشاء واحد جديد.

الخطوة 2: حدّد النطاقات

تحت المفتاح، ستة مفاتيح تبديل تتحكم فيما يستطيع المفتاح قراءته: Server Overview وTickets وActivity وInvoices وReviews وGiveaways. أوقف أي شيء لا تحتاجه؛ فالنطاق المعطّل يعيد 403 فوراً، لذا حتى لو تسرّب المفتاح لا يستطيع قراءة نطاقات لم تفعّلها.

الخطوة 3: اختبار سريع بـ curl

curl https://noxyrbot.com/api/v1/server \
  -H "Authorization: Bearer nxr_YOUR_KEY"

يفترض أن ترى JSON يحتوي على معرّف سيرفرك واسمه ورابط أيقونته وعدد أعضائه وعدد المتصلين والتعزيزات (boosts).

الخطوة 4: استدعِه من Node.js

const KEY = process.env.NOXYR_API_KEY;

async function getStats() {
    const [server, tickets, activity] = await Promise.all([
        fetch('https://noxyrbot.com/api/v1/server',              { headers: { Authorization: `Bearer ${KEY}` } }),
        fetch('https://noxyrbot.com/api/v1/tickets',             { headers: { Authorization: `Bearer ${KEY}` } }),
        fetch('https://noxyrbot.com/api/v1/activity?days=7',     { headers: { Authorization: `Bearer ${KEY}` } })
    ]);
    return {
        server:   await server.json(),
        tickets:  await tickets.json(),
        activity: await activity.json()
    };
}

getStats().then(console.log);

الخطوة 5: استدعِه من المتصفح

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

• لوحة عامة خلف وسيط (proxy): دالة serverless صغيرة من جهتك تقرأ المفتاح من متغير بيئة، وتستدعي Noxyr، وتمرر JSON إلى المتصفح.
• أداة داخلية موثوقة: احمِ الصفحة بمصادقتك الخاصة، ثم أدخل المفتاح.

// Cloudflare Worker / Vercel Edge - key stays on the server
export default {
    async fetch(request, env) {
        const upstream = await fetch('https://noxyrbot.com/api/v1/server', {
            headers: { Authorization: `Bearer ${env.NOXYR_API_KEY}` }
        });
        return new Response(await upstream.text(), {
            headers: { 'content-type': 'application/json', 'cache-control': 'public, max-age=60' }
        });
    }
};

الخطوة 6: اعرضه

<div id="members">…</div>
<script>
    fetch('/api/live-server-stats')
        .then((r) => r.json())
        .then((data) => {
            document.getElementById('members').textContent =
                `${data.memberCount.toLocaleString()} members · ${data.onlineCount} online`;
        });
</script>

حدود الطلبات والتخزين المؤقت

60 طلباً في الدقيقة لكل مفتاح. التحديث الفوري رائع في لوحة خاصة، لكنه مُهدِر على موقع عام؛ خزّن استجابات المصدر مؤقتاً لمدة 30 إلى 60 ثانية في طبقة الوسيط لديك، ولن تقترب من الحد أبداً.

رسائل الخطأ

• 401 unauthorized: المفتاح مفقود أو غير صالح.
• 403 key_disabled: المفتاح معطّل من لوحة التحكم.
• 403 scope_disabled: نطاق نقطة النهاية معطّل؛ أصلحه من لوحة التحكم.
• 404 guild_unavailable: أُزيل البوت من ذلك السيرفر.
• 429 rate_limited: خفّف السرعة.

تريد معرفة سبب تصميم الـ API بهذا الشكل؟ مبادئ تصميم الـ API لروبوتات ديسكورد.