Richieste HTTP in-game

Puoi utilizzare HttpService per inviare richieste HTTP generiche a servizi web di terze parti per casi d'uso come analisi, archiviazione dati o registrazione degli errori. HttpService supporta anche alcuni endpoint di Open Cloud.

Abilitare le richieste HTTP

I metodi HttpService:GetAsync(), HttpService:PostAsync() e HttpService:RequestAsync() non sono abilitati per impostazione predefinita. Per inviare richieste, devi Consentire le richieste HTTP sotto File ⟩ Impostazioni esperienza ⟩ Sicurezza in Studio.

Utilizzo nei plugin

Puoi utilizzare HttpService nei plugin di Studio per controllare aggiornamenti, scaricare contenuti o altre logiche aziendali. La prima volta che un plugin tenta di utilizzare il servizio, all'utente potrebbe essere chiesto di concedere al plugin il permesso di comunicare con l'indirizzo web specifico. Gli utenti possono accettare, rifiutare e revocare questi permessi in qualsiasi momento tramite la finestra Gestione plugin.

I plugin possono anche comunicare con altri software in esecuzione sullo stesso computer tramite gli host localhost e 127.0.0.1. Eseguendo programmi compatibili con tali plugin, puoi estendere la funzionalità del tuo plugin oltre le normali capacità di Studio, come interagire con il file system del tuo computer. Fai attenzione che tale software deve essere distribuito separatamente dal plugin stesso e può comportare rischi per la sicurezza.

Utilizzo con Open Cloud

HttpService può attualmente chiamare un sottoinsieme degli endpoint di Open Cloud. Puoi chiamare questi endpoint nello stesso modo in cui chiameresti qualsiasi altro endpoint tramite HttpService. L'unica differenza è che devi includere una chiave API di Open Cloud nella richiesta:

1. Crea una chiave API di Open Cloud.
2. Salva la chiave API nel tuo archivio segreti.
3. Effettua la richiesta.

Il seguente esempio di codice dimostra come aggiornare l'appartenenza a un gruppo di un utente all'interno di un gioco:

local HttpService = game:GetService("HttpService")

local groupId = "your_group_id"
local membershipId = "your_membership_id"
local roleId = "your_role_id"

local function request()
	local response = HttpService:RequestAsync({
		Url = `https://apis.roblox.com/cloud/v2/groups/{groupId}/memberships/{membershipId}`,
		Method = "PATCH",
		Headers = {
			["Content-Type"] = "application/json", -- Quando si invia JSON, impostalo!
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- Impostato in Creator Hub
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("La risposta è stata positiva:", response.StatusCode, response.StatusMessage)
	else
		print("La risposta ha restituito un errore:", response.StatusCode, response.StatusMessage)
	end
	print("Corpo della risposta:\n", response.Body)
	print("Intestazioni della risposta:\n", HttpService:JSONEncode(response.Headers))
end

-- Avvolgi la funzione in pcall() per sicurezza
local success, errorMessage = pcall(request)
if not success then
	print("La richiesta HTTP non è riuscita a essere inviata:", errorMessage)
end

Endpoint di Open Cloud supportati

I seguenti endpoint sono supportati. A causa delle attuali limitazioni su HttpService, la stringa .. non è consentita nei parametri del percorso URL per i domini Roblox. Ciò significa, ad esempio, che gli archivi dati e le voci contenenti questa stringa sono attualmente inaccessibili da HttpService.

Risorse

• GetAsset
• ListAssetVersions
• GetAssetVersion

Divieti e blocchi

• ListUserRestrictions (Luogo)
• GetUserRestriction (Luogo)
• UpdateUserRestriction (Luogo)
• ListUserRestrictions (Universo)
• GetUserRestriction (Universo)
• UpdateUserRestriction (Universo)
• ListUserRestrictionLogs (Universo)

Configurazioni

• GetConfigRepositoryValues
• GetConfigRepositoryDraft
• UpdateDraft
• DeleteDraft
• OverwriteDraft
• GetConfigRepositoryFull
• PublishDraft
• ListRevisions
• RestoreRevision

Negozio Creatore

• CreateCreatorStoreProduct
• GetCreatorStoreProduct
• UpdateCreatorStoreProduct
• CreatorStoreAssetsSearch

Prodotti per sviluppatori

• CreateDeveloperProduct
• UpdateDeveloperProduct
• GetDeveloperProductConfig
• ListDeveloperProductConfigsByUniverse

Pass di gioco

• CreateGamePass
• UpdateGamePass
• GetGamePassConfig
• ListGamePassConfigsByUniverse

Archivi dati e memorie

Archivi dati:

• ListDataStores
• SnapshotDataStores
• ListDataStoreEntries
• CreateDataStoreEntry
• GetDataStoreEntry
• DeleteDataStoreEntry
• UpdateDataStoreEntry
• IncrementDataStoreEntry
• ListDataStoreEntryRevisions
• ListDataStoreEntries (Con Scopo)
• CreateDataStoreEntry (Con Scopo)
• GetDataStoreEntry (Con Scopo)
• DeleteDataStoreEntry (Con Scopo)
• UpdateDataStoreEntry (Con Scopo)
• IncrementDataStoreEntry (Con Scopo)
• ListDataStoreEntryRevisions (Con Scopo)

Memorie:

• CreateMemoryStoreQueueItem
• DiscardMemoryStoreQueueItems
• ReadMemoryStoreQueueItems
• ListMemoryStoreSortedMapItems
• CreateMemoryStoreSortedMapItem
• GetMemoryStoreSortedMapItem
• DeleteMemoryStoreSortedMapItem
• UpdateMemoryStoreSortedMapItem
• FlushMemoryStore

Archivi dati ordinati:

• ListOrderedDataStoreEntries
• CreateOrderedDataStoreEntry
• GetOrderedDataStoreEntry
• DeleteOrderedDataStoreEntry
• UpdateOrderedDataStoreEntry
• IncrementOrderedDataStoreEntry

Gruppi

• GetGroup
• ListGroupJoinRequests
• AcceptGroupJoinRequest
• DeclineGroupJoinRequest
• ListGroupMemberships
• UpdateGroupMembership
• ListGroupRoles
• GetGroupRole
• GetGroupShout

Inventari

• ListInventoryItems

Esecuzione Luau

• CreateLuauExecutionSessionTaskBinaryInput
• CreateLuauExecutionSessionTask
• CreateLuauExecutionSessionTask (con versione)
• GetLuauExecutionSessionTask
• ListLuauExecutionSessionTaskLogs

Notifiche

• CreateUserNotification

Luoghi

• GetPlace
• UpdatePlace
• GetInstance
• UpdateInstance

Universi

• UpdateUniverse
• GetUniverse
• PublishUniverseMessage
• RestartUniverseServers

Utenti

• GetUser
• GenerateUserThumbnail

Limitazioni

• Solo le intestazioni x-api-key e content-type sono consentite.
• L'intestazione x-api-key deve essere un Secret. Vedi Archivi segreti.
• La stringa ".." non è consentita nei parametri del percorso URL.
• Solo il protocollo HTTPS è supportato.
• Non puoi utilizzare la porta 1194 o qualsiasi porta inferiore a 1024, eccetto 80 e 443. Se provi a utilizzare una porta bloccata, ricevi un errore 403 Forbidden o ERR_ACCESS_DENIED.

Limiti di frequenza

Per ogni server di gioco Roblox, c'è un limite di 2500 richieste Open Cloud al minuto. Superare questo limite può causare un'interruzione dei metodi di invio delle richieste per circa 30 secondi. Il tuo pcall() potrebbe anche fallire con un messaggio di Numero di richieste Open Cloud superato il limite.

• Le richieste Open Cloud non consumano lo stesso limite complessivo di 500 richieste HTTP al minuto imposto su tutte le altre richieste.
• Ogni endpoint ha il proprio limite per proprietario della chiave API (può essere un utente o un gruppo) che è imposto indipendentemente da dove provengano le chiamate (HttpService, il web, ecc.).

Per informazioni dettagliate sui limiti di frequenza di Open Cloud, sul limitamento della frequenza basato sull'autenticazione e sulle migliori pratiche, vedi Limiti di frequenza.

Migliori pratiche

Per ottimizzare l'uso di HttpService e evitare di superare i limiti, applica le seguenti migliori pratiche:

• Gestisci gli errori in modo elegante. Le richieste web possono fallire per molti motivi. Usa pcall() e pianifica cosa fare quando le richieste falliscono. Inoltre, valida e sanitizza rigorosamente tutti i dati ricevuti dalle API esterne, assicurandoti che i dati siano corretti dove possibile.

• Usa il backoff esponenziale per rimanere al di sotto dei limiti.

  Se una richiesta restituisce un errore recuperabile, invece di riprovare immediatamente, aspetta due secondi, poi quattro, otto, ecc. tra i tentativi. Questo aiuta a limitare la congestione e migliora la possibilità di una richiesta riuscita dando all'endpoint il tempo di "raffreddarsi".

• Aggrega e invia dati in blocco.

  Quando possibile, è consigliabile lasciare che il tuo server raccolga tutti i dati necessari per inviare una richiesta HTTP, piuttosto che più piccole richieste. Ad esempio, se stai inviando una richiesta HTTP per ogni giocatore nel tuo server, verifica se l'API ha un endpoint di bulk/batch e, in tal caso, raccogli le informazioni da tutti i giocatori e inviale tutte in una richiesta.

  In alcuni casi potresti dover utilizzare HttpService:RequestAsync() per includere dati nel corpo della richiesta.

• Utilizza gli endpoint HTTP/2. HTTP/2 offre significativi vantaggi in termini di prestazioni attraverso funzionalità come la compressione delle intestazioni e il multiplexing delle richieste/risposte su una singola connessione. HttpService utilizza automaticamente HTTP/2 quando disponibile. Nota che la specifica HTTP/2 richiede che tutti i nomi delle intestazioni siano inviati in minuscolo.

Osservabilità

Il Dashboard di Osservabilità fornisce informazioni e analisi per monitorare e risolvere i problemi relativi all'uso di HttpService. Il dashboard presenta due grafici principali: Conteggio delle richieste che tiene traccia del volume delle richieste HttpService dal tuo gioco, e Tempo di risposta che misura la latenza per gli endpoint a rispondere.

Le dimensioni disponibili per il filtraggio e la suddivisione sono definite come segue:

Tipo di richiesta

• GET
• POST
• PUT
• PATCH
• DELETE
• Altro (per tipi di richiesta non specificati)

Stato

• Successo (codici di stato HTTP 1xx e 2xx)
• Reindirizzamento (codici di stato HTTP 3xx)
• 400 (Richiesta non valida)
• 401 (Non autorizzato)
• 403 (Vietato)
• 404 (Non trovato)
• 429 (Troppe richieste)
• 500 (Errore interno del server)
• 503 (Servizio non disponibile)
• ExternalError (qualsiasi altro codice di errore non specificato restituito dal servizio esterno)
• InternalError (un problema restituito da HttpService all'interno di Roblox)

Il grafico Tempo di risposta non è correlato ai dati di stato. Se selezioni "Stato" come suddivisione o filtro, questo grafico non mostrerà dati.

Considerazioni aggiuntive

• Le richieste dovrebbero fornire una forma sicura di autenticazione, come una chiave segreta pre-condivisa, in modo che attori malintenzionati non possano spacciarsi per uno dei tuoi server Roblox.
• Fai attenzione alla capacità generale e alle politiche di limitazione della frequenza dei server web a cui vengono inviate le richieste.