Samouczek API serwera na Discordzie: statystyki na żywo w JavaScript

Ten samouczek przeprowadzi cię przez wygenerowanie klucza API serwera Noxyr, wywoływanie sześciu endpointów z Node.js i przeglądarki oraz wyświetlanie danych z Discorda na żywo na publicznej stronie. Jeśli kiedykolwiek chciałeś mieć na swojej stronie prawdziwy licznik członków, który aktualizuje się bez połączenia z botem, to właśnie to.

Krok 1: wygeneruj klucz

Otwórz panel Noxyr, wybierz swój serwer i przejdź do Dostęp do API. Kliknij Wygeneruj klucz API. Klucz (zaczyna się od nxr_) jest pokazywany tylko raz, więc od razu skopiuj go do zmiennej środowiskowej. Po stronie serwera przechowywany jest wyłącznie hash SHA-256, więc zgubiony klucz oznacza konieczność wygenerowania nowego.

Krok 2: ustaw zakresy

Pod kluczem sześć przełączników określa, co klucz może odczytać: Przegląd serwera, Tickety, Aktywność, Faktury, Recenzje, Giveaway. Wyłącz wszystko, czego nie potrzebujesz - wyłączony zakres zwraca od razu 403, więc nawet wyciekły klucz nie odczyta zakresów, których nigdy nie włączyłeś.

Krok 3: test curl

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

Powinieneś zobaczyć JSON z identyfikatorem serwera, nazwą, adresem URL ikony, liczbą członków, liczbą osób online i boostami.

Krok 4: wywołaj z 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);

Krok 5: wywołaj z przeglądarki

CORS jest otwarty, więc możesz pobierać dane bezpośrednio ze statycznej strony. Nie osadzaj klucza w kodzie po stronie klienta, który trafia do prawdziwych użytkowników: każdy, kto otworzy DevTools, go zobaczy. Dwa bezpieczne wzorce:

• Publiczny panel za proxy: niewielka funkcja serverless po twojej stronie odczytuje klucz ze zmiennej środowiskowej, wywołuje Noxyr i przekazuje JSON do przeglądarki.
• Zaufane narzędzie wewnętrzne: zabezpiecz stronę własnym uwierzytelnianiem, a dopiero potem wstaw klucz.

// 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' }
        });
    }
};

Krok 6: wyrenderuj dane

<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>

Limity żądań i cache

60 żądań na minutę na klucz. Odświeżanie w czasie rzeczywistym dobrze wygląda na prywatnym panelu, ale na publicznej stronie jest marnotrawstwem - buforuj odpowiedzi z upstreamu przez 30–60 sekund w warstwie proxy, a nigdy nie zbliżysz się do limitu.

Odpowiedzi z błędami

• 401 unauthorized: brakujący lub nieprawidłowy klucz.
• 403 key_disabled: klucz wyłączony w panelu.
• 403 scope_disabled: zakres tego endpointu jest wyłączony; napraw to w panelu.
• 404 guild_unavailable: bot został usunięty z tego serwera.
• 429 rate_limited: zwolnij.

Chcesz wiedzieć, dlaczego API ma taki kształt? Zasady projektowania API dla botów Discord.