このチュートリアルでは、Noxyrサーバー APIキーの生成、Node.jsとブラウザからの6つのエンドポイントの呼び出し、そして公開ページへのライブのDiscordデータの表示を説明します。ボットに接続しなくても更新される、本物のメンバーカウンターをWebサイトに置きたいと思ったことがあるなら、これがその方法です。

A key is generated, a curl request is sent, and the JSON response renders as live text on a page. 1 nxr_••••••••• 2 curl /api/v1/server 3 { memberCount: 812 } 812 members online

手順1：キーを生成する

Noxyrのダッシュボードを開き、サーバーを選んでAPI Accessに進みます。Generate API Keyをクリックします。キー（nxr_ で始まります）は一度だけ表示されるので、今すぐ環境変数にコピーしてください。サーバー側に保存されるのはSHA-256のハッシュだけなので、キーを紛失した場合は再生成が必要になります。

手順2：スコープを設定する

キーの下にある6つのトグルで、キーが読み取れる内容を制御します。サーバー概要、チケット、アクティビティ、インボイス、レビュー、ギブアウェイです。不要なものはオフにしてください。無効にされたスコープには即座に403が返るので、キーが漏えいしても、有効にしていないスコープは読み取られません。

手順3：curlで動作確認する

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

サーバーのID、名前、アイコンのURL、メンバー数、オンライン数、ブーストを含むJSONが表示されるはずです。

手順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は開放されているので、静的サイトから直接fetchできます。実際のユーザーに配信するクライアント側のコードにキーを埋め込まないでください。DevToolsを開いた人なら誰でもキーを見られてしまいます。安全なパターンは2つあります。

  • プロキシの裏にある公開ダッシュボード：お使いのサーバー側にある小さなサーバーレス関数が、環境変数からキーを読み取り、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>

レート制限とキャッシュ

キーごとに1分あたり60リクエストです。プライベートなダッシュボードではリアルタイムが快適ですが、公開サイトでは無駄になります。プロキシ層で上流のレスポンスを30〜60秒キャッシュすれば、上限にはまず近づきません。

エラーレスポンス

  • 401 unauthorized：キーがない、または不正です。
  • 403 key_disabled：ダッシュボードでキーがオフになっています。
  • 403 scope_disabled：そのエンドポイントのスコープがオフになっています。ダッシュボードで修正してください。
  • 404 guild_unavailable：ボットがそのサーバーから削除されています。
  • 429 rate_limited：リクエストの速度を落としてください。

APIがこの形をしている理由を知りたい場合は、Discordボットの API設計の原則をご覧ください。