Discord 服务器 API 教程：使用 JavaScript 获取实时统计数据

本教程将介绍如何生成 Noxyr 服务器 API 密钥，从 Node.js 和浏览器调用六个端点，并将实时 Discord 数据展示在公开页面上。如果你一直想在网站上显示一个真正的成员计数器，并且无需机器人连接即可自动更新，那么这正是你需要的。

第一步：生成密钥

打开 Noxyr 仪表盘，选择你的服务器，然后进入 API Access。点击 Generate API Key。密钥（以 nxr_ 开头）只会显示一次，请立即将其复制到环境变量中。服务器端只存储 SHA-256 哈希值，因此丢失的密钥只能重新生成。

第二步：设置权限范围

在密钥下方，有六个开关用于控制该密钥可以读取的内容：Server Overview、Tickets、Activity、Invoices、Reviews、Giveaways。关闭所有你不需要的项目。被禁用的权限范围会立即返回 403，因此即使密钥泄露，也无法读取你从未启用的范围。

第三步：Curl 冒烟测试

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

你应当会看到 JSON 格式的返回内容，包括服务器的 ID、名称、图标 URL、成员人数、在线人数和助推数。

第四步：从 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);

第五步：从浏览器调用

CORS 已开放，因此你可以直接从静态网站发起请求。请勿将密钥嵌入发送给真实用户的前端代码中：任何打开开发者工具的人都能看到它。以下是两种安全的做法：

• 位于代理之后的公开仪表盘：在你这边使用一个很小的无服务器函数，从环境变量中读取密钥，调用 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' }
        });
    }
};

第六步：渲染数据

<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 为何这样设计？请阅读Discord 机器人的 API 设计原则。