Nota: A partire dall'API v10, il dominio delle API Discord è cambiato da discordapp.com a discord.com. Il componente è stato aggiornato per utilizzare la versione 10 dell'API e il nuovo dominio.
I gateway sono la forma di comunicazione in tempo reale di Discord tramite WebSocket sicuri. I client ricevono eventi e dati tramite il gateway a cui sono connessi e inviano dati tramite l'API REST.
Prima di tutto è necessario generare un nuovo Bot e copiare il Bot Token che verrà utilizzato per autenticarsi tramite API. Quindi impostare questo token nel Componente API.
TsgcWSAPI_Discord1.DiscordOptions.BotOptions.Token := '...bot token here...';
Mantenere un'applicazione con stato può essere difficile quando si tratta della quantità di dati che ci si aspetta di elaborare, specialmente su larga scala. I Gateway Intents sono un sistema che aiuta a ridurre tale onere computazionale.
Durante l'identificazione presso il gateway, è possibile specificare un parametro intents che consente di sottoscriversi in modo condizionale a "intenti" predefiniti, gruppi di eventi definiti da Discord. Se non si specifica un determinato intento, non si riceverà nessuno degli eventi gateway raggruppati in quel gruppo. Gli intenti validi sono (il valore zero indica che tutti gli eventi vengono ricevuti):
GUILDS (1 << 0) = Integer (1)
- GUILD_CREATE
- GUILD_DELETE
- GUILD_ROLE_CREATE
- GUILD_ROLE_UPDATE
- GUILD_ROLE_DELETE
- CHANNEL_CREATE
- CHANNEL_UPDATE
- CHANNEL_DELETE
- CHANNEL_PINS_UPDATE
GUILD_MEMBERS (1 << 1) = Integer (2)
- GUILD_MEMBER_ADD
- GUILD_MEMBER_UPDATE
- GUILD_MEMBER_REMOVE
GUILD_BANS (1 << 2) = Integer (4)
- GUILD_BAN_ADD
- GUILD_BAN_REMOVE
GUILD_EMOJIS (1 << 3) = Integer (8)
- GUILD_EMOJIS_UPDATE
GUILD_INTEGRATIONS (1 << 4) = Integer (16)
- GUILD_INTEGRATIONS_UPDATE
GUILD_WEBHOOKS (1 << 5) = Integer (32)
- WEBHOOKS_UPDATE
GUILD_INVITES (1 << 6) = Integer (64)
- INVITE_CREATE
- INVITE_DELETE
GUILD_VOICE_STATES (1 << 7) = Integer (128)
- VOICE_STATE_UPDATE
GUILD_PRESENCES (1 << 8) = Integer (256)
- PRESENCE_UPDATE
GUILD_MESSAGES (1 << 9) = Integer (512)
- MESSAGE_CREATE
- MESSAGE_UPDATE
- MESSAGE_DELETE
GUILD_MESSAGE_REACTIONS (1 << 10) = Integer (1024)
- MESSAGE_REACTION_ADD
- MESSAGE_REACTION_REMOVE
- MESSAGE_REACTION_REMOVE_ALL
- MESSAGE_REACTION_REMOVE_EMOJI
GUILD_MESSAGE_TYPING (1 << 11) = Integer (2048)
- TYPING_START
DIRECT_MESSAGES (1 << 12) = Integer (4096)
- CHANNEL_CREATE
- MESSAGE_CREATE
- MESSAGE_UPDATE
- MESSAGE_DELETE
- CHANNEL_PINS_UPDATE
DIRECT_MESSAGE_REACTIONS (1 << 13) = Integer (8192)
- MESSAGE_REACTION_ADD
- MESSAGE_REACTION_REMOVE
- MESSAGE_REACTION_REMOVE_ALL
- MESSAGE_REACTION_REMOVE_EMOJI
DIRECT_MESSAGE_TYPING (1 << 14) = Integer (16384)
- TYPING_START
Gli heartbeat sono gestiti automaticamente dal componente, quindi non deve preoccuparsene. Quando il client si connette al server, il server invia una risposta HELLO con un intervallo di heartbeat, e il componente legge la risposta e regola automaticamente l'heartbeat per inviare un ping ogni x secondi. A volte il server può inviare un ping al client; anche questo viene gestito automaticamente dal client.
Quando la connessione è pronta, dopo un accesso e un'autorizzazione riusciti da parte del server, viene sollevato l'evento OnDiscordReady e quindi è possibile iniziare a ricevere aggiornamenti dal server.
Se la connessione si chiude in modo imprevisto, quando il client tenta di riconnettersi, chiama l'evento OnDiscordBeforeReconnect. Il componente salva automaticamente tutti i dati necessari per effettuare una ripresa riuscita, ma i parametri possono essere modificati se necessario. Se non desidera riconnettersi e avviare una nuova sessione pulita, imposti semplicemente Reconnect su False.
Se la sessione viene ripristinata, viene generato l'evento OnDiscordResumed. Se si tratta di una nuova sessione, verrà generato OnDiscordReady.
Gli eventi vengono distribuiti tramite OnDiscordDispatch, quindi qui è possibile leggere gli eventi inviati dal server al client.
procedure OnDiscordDispatch(Sender: TObject; const aEvent, RawData: string);
begin
DoLog('#discord dispatch: ' + aEvent + ' ' + RawData);
end;
aEvent il parametro contiene il nome dell'evento.
RawData contiene il messaggio JSON completo.
Per richiedere informazioni su guild, utenti o per aggiornare dati... invece di utilizzare i messaggi del gateway websocket, Discord richiede l'uso di richieste HTTP. Di seguito sono elencati tutti i metodi disponibili per effettuare una richiesta HTTP:
function GET_Request(const aPath: String): string;
function POST_Request(const aPath, aMessage: String): string;
function PUT_Request(const aPath, aMessage: String): string;
function PATCH_Request(const aPath, aMessage: String): string;
function DELETE_Request(const aPath: String): string;
Esempio: ottieni le informazioni sull'utente corrente
result := GET_Request('/users/@me');
risposta di esempio dal server:
{
"id": "637423922035480852",
"username": "test",
"avatar": null,
"discriminator": "5125",
"bot": true,
"email": null,
"verified": true,
"locale": "en-US",
"mfa_enabled": false,
"flags": 0
}