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 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 nelle Impostazioni dell'esperienza per il tuo gioco.

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 cerca di utilizzare il servizio, all'utente potrebbe essere chiesto di concedere al plugin il permesso di comunicare con un determinato indirizzo web. 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, poiché tali software devono essere distribuiti separatamente dal plugin stesso e possono comportare rischi per la sicurezza.

Utilizzo con Open Cloud

HttpService può attualmente chiamare un sottoinsieme di endpoint di Open Cloud. Puoi chiamare questi endpoint allo 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 dall'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 così!
			["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 efficace:", 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:", errorMessage)
end

Endpoint 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 e le voci contenenti questa stringa sono attualmente inaccessibili da HttpService.

Asset

• GetAsset
• ListAssetVersions
• GetAssetVersion

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

• CreateCreatorStoreProduct
• GetCreatorStoreProduct
• UpdateCreatorStoreProduct
• CreatorStoreAssetsSearch

Prodotti per sviluppatori

• CreateDeveloperProduct
• UpdateDeveloperProduct
• GetDeveloperProductConfig
• ListDeveloperProductConfigsByUniverse

Pass dominatori

• CreateGamePass
• UpdateGamePass
• GetGamePassConfig
• ListGamePassConfigsByUniverse

Archivi e memorie

Archivi:

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

Memorie:

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

Archivi 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 alcuna porta inferiore a 1024, tranne 80 e 443. Se provi a utilizzare una porta bloccata, riceverai un errore 403 Forbidden o ERR_ACCESS_DENIED.

Limiti di frequenza

Per ciascun server di gioco Roblox, ci sono un limite di 2500 richieste Open Cloud al minuto. Superare questo limite può causare ritardi nei metodi di invio delle richieste di 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 un proprio limite per proprietario della chiave API (che può essere un utente o un gruppo) che è applicato indipendentemente da dove provengano le chiamate (HttpService, il web, ecc.).

Per informazioni dettagliate sui limiti di frequenza di Open Cloud, limitazione della frequenza basata sull'autenticazione e pratiche migliori, vedi Limiti di frequenza.

Pratiche migliori

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

• Gestisci gli errori in modo adeguato. Le richieste web possono fallire per vari motivi. Usa pcall() e avere un piano per quando le richieste falliscono. Inoltre, valida e sanitizza rigorosamente tutti i dati ricevuti dalle API esterne, assicurandoti che i dati siano corretti quando possibile.

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

  Se una richiesta restituisce un errore recuperabile, anziché 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 di successo dando tempo all'endpoint di "raffreddarsi".

• Aggrega e invia dati in blocco.

  Quando possibile, è consigliabile lasciare che il tuo server raccoglie 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, controlla se l'API ha un endpoint bulk/batch e, se sì, raccogli le informazioni da tutti i giocatori e invialo tutto in una richiesta.

  In alcuni casi potrebbe essere necessario utilizzare HttpService:RequestAsync() per includere dati nel corpo della richiesta.

• Utilizza endpoint HTTP/2. HTTP/2 fornisce notevoli vantaggi in termini di prestazioni tramite funzionalità come la compressione dell'intestazione e il multiplexing di richiesta/risposta 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 approfondimenti e analisi per il monitoraggio e la risoluzione dei problemi dell'uso di HttpService. Il dashboard presenta due grafici principali: Conteggio delle Richieste che tiene traccia del volume delle richieste di 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 (qualunque altro codice di errore non specificato restituito dal servizio esterno)
• InternalError (un problema restituito da HttpService all'interno di Roblox)

Il grafico di 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 devono fornire una forma sicura di autenticazione, come una chiave segreta precondivisa, in modo che attori mal-intenzionati non possano spacciarsi per uno dei tuoi server Roblox.
• Fai attenzione alle politiche di capacità generale e di limitazione della frequenza dei server web a cui vengono inviate le richieste.