HTTP-verzoeken in het spel | Documentatie

Je kunt HttpService gebruiken om generieke HTTP-verzoeken te verzenden naar externe webservices voor gebruiksgevallen zoals analytics, gegevensopslag of foutlogging. HttpService ondersteunt ook bepaalde Open Cloud-eindpunten.

HTTP-verzoeken inschakelen

De methoden HttpService:GetAsync(), HttpService:PostAsync() en HttpService:RequestAsync() zijn standaard niet ingeschakeld. Om verzoeken te verzenden, moet je HTTP-verzoeken toestaan onder Bestand ⟩ Ervaringsinstellingen ⟩ Beveiliging in Studio.

Gebruik in plugins

Je kunt HttpService gebruiken in Studio-plugins om te controleren op updates, inhoud te downloaden of andere bedrijfslogica. De eerste keer dat een plugin probeert de service te gebruiken, kan de gebruiker worden gevraagd om de plugin toestemming te geven om te communiceren met het specifieke webadres. Gebruikers kunnen deze toestemmingen op elk moment accepteren, weigeren en intrekken via het venster Pluginbeheer.

Plugins kunnen ook communiceren met andere software die op dezelfde computer draait via de hosts localhost en 127.0.0.1. Door programma's te draaien die compatibel zijn met dergelijke plugins, kun je de functionaliteit van je plugin uitbreiden buiten de normale mogelijkheden van Studio, zoals interactie met het bestandssysteem van je computer. Wees voorzichtig, want dergelijke software moet apart van de plugin zelf worden verspreid en kan beveiligingsrisico's met zich meebrengen.

Gebruik met Open Cloud

HttpService kan momenteel een subset van de Open Cloud-eindpunten aanroepen. Je kunt deze eindpunten op dezelfde manier aanroepen als je andere eindpunten via HttpService zou aanroepen. Het enige verschil is dat je een Open Cloud API-sleutel in het verzoek moet opnemen:

Maak een Open Cloud API-sleutel.
Sla de API-sleutel op in je geheimenopslag.
Doe het verzoek.

De volgende codevoorbeeld laat zien hoe je het groepslidmaatschap van een gebruiker vanuit een spel kunt bijwerken:

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.test1709.icu/cloud/v2/groups/{groupId}/memberships/{membershipId}`,
		Method = "PATCH",
		Headers = {
			["Content-Type"] = "application/json", -- Wanneer je JSON verzendt, stel dit in!
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- Ingesteld in Creator Hub
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("Het antwoord was succesvol:", response.StatusCode, response.StatusMessage)
	else
		print("Het antwoord gaf een fout terug:", response.StatusCode, response.StatusMessage)
	end
	print("Antwoord lichaam:\n", response.Body)
	print("Antwoord headers:\n", HttpService:JSONEncode(response.Headers))
end

-- Wikkel de functie in pcall() voor veiligheid
local success, errorMessage = pcall(request)
if not success then
	print("Het HTTP-verzoek kon niet worden verzonden:", errorMessage)
end

Ondersteunde Open Cloud-eindpunten

De volgende eindpunten worden ondersteund. Vanwege huidige beperkingen op HttpService is de .. string niet toegestaan in URL-padparameters naar Roblox-domeinen. Dit betekent bijvoorbeeld dat gegevensopslag en -invoeren die deze string bevatten momenteel niet toegankelijk zijn vanuit HttpService.

Activa

Verboden en blokkades

Configuraties

Creator Store

Ontwikkelaarsproducten

Gamepassen

Gegevens- en geheugenopslag

Gegevensopslag:

Geheugenopslag:

Geordende gegevensopslag:

Groepen

Inventarissen

ListInventoryItems

Luau-uitvoering

Meldingen

CreateUserNotification

Plaatsen

Universums

Gebruikers

Beperkingen

Alleen de headers x-api-key en content-type zijn toegestaan.
De header x-api-key moet een Secret zijn. Zie Geheimenopslag.
De string ".." is niet toegestaan in URL-padparameters.
Alleen het HTTPS-protocol wordt ondersteund.
Je kunt poort 1194 of een poort onder 1024 niet gebruiken, behalve 80 en 443. Als je probeert een geblokkeerde poort te gebruiken, ontvang je een 403 Forbidden of ERR_ACCESS_DENIED fout.

Snelheidslimieten

Voor elke Roblox-game-server is er een limiet van 2500 Open Cloud-verzoeken per minuut. Het overschrijden hiervan kan ervoor zorgen dat de methoden voor het verzenden van verzoeken ongeveer 30 seconden stagneren. Je pcall() kan ook mislukken met een bericht van Aantal Open Cloud-verzoeken overschreed limiet.

Open Cloud-verzoeken verbruiken niet dezelfde totale limiet van 500 HTTP-verzoeken per minuut die op alle andere verzoeken wordt afgedwongen.
Elk eindpunt heeft zijn eigen limiet per eigenaar van de API-sleutel (kan een gebruiker of een groep zijn) die wordt afgedwongen, ongeacht waar de oproepen vandaan komen (HttpService, het web, enz.).

Voor gedetailleerde informatie over Open Cloud-snelheidslimieten, authenticatie-gebaseerde snelheidslimitering en best practices, zie Snelheidslimieten.

Best practices

Om je gebruik van HttpService te optimaliseren en te voorkomen dat je de limieten overschrijdt, pas je de volgende best practices toe:

Behandel fouten op een nette manier. Webverzoeken kunnen om veel redenen mislukken. Gebruik pcall() en heb een plan voor wanneer verzoeken mislukken. Valideer en saniteer bovendien strikt alle ontvangen gegevens van externe API's, zodat je waar mogelijk correcte gegevens hebt.
Gebruik exponentiële backoff om onder de limieten te blijven.

Als een verzoek een herstelbare fout retourneert, wacht dan in plaats van onmiddellijk opnieuw te proberen twee seconden, dan vier, acht, enzovoort tussen pogingen. Dit helpt congestie te beperken en verbetert de kans op een succesvol verzoek door de eindpunt tijd te geven om "af te koelen."
Verzamel en verzend gegevens in bulk.

Wanneer mogelijk, is het aan te raden om je server alle benodigde gegevens te laten verzamelen om één HTTP-verzoek te verzenden, in plaats van meerdere kleine verzoeken. Als je bijvoorbeeld een HTTP-verzoek verzendt voor elke speler op je server, controleer dan of de API een bulk/batch-eindpunt heeft en, zo ja, verzamel de informatie van alle spelers en verzend deze allemaal in één verzoek.

In sommige gevallen moet je mogelijk HttpService:RequestAsync() gebruiken om gegevens in de body van het verzoek op te nemen.
Gebruik HTTP/2-eindpunten. HTTP/2 biedt aanzienlijke prestatievoordelen door functies zoals headercompressie en multiplexing van verzoeken/antwoorden over één enkele verbinding. HttpService gebruikt automatisch HTTP/2 wanneer beschikbaar. Houd er rekening mee dat de HTTP/2-specificatie vereist dat alle header-namen in kleine letters worden verzonden.

Observeerbaarheid

Het Observeerbaarheid Dashboard biedt inzichten en analyses voor het monitoren en oplossen van problemen met je gebruik van HttpService. Het dashboard bevat twee primaire grafieken: Verzoektelling die het volume van HttpService-verzoeken vanuit je spel bijhoudt, en Antwoordtijd die de latentie meet voor eindpunten om te reageren.

De beschikbare dimensies voor filtering en uitsplitsing zijn als volgt gedefinieerd:

Verzoektype

GET
POST
PUT
PATCH
DELETE
Overig (voor niet-gespecificeerde verzoektypes)

Status

Succes (HTTP 1xx en 2xx statuscodes)
Omleiden (HTTP 3xx statuscodes)
400 (Slechte aanvraag)
401 (Niet gemachtigd)
403 (Verboden)
404 (Niet gevonden)
429 (Te veel verzoeken)
500 (Interne serverfout)
503 (Dienst niet beschikbaar)
ExternalError (elke andere niet-gespecificeerde foutcodes die door de externe service worden geretourneerd)
InternalError (een probleem dat door HttpService binnen Roblox is geretourneerd)

De Antwoordtijd-grafiek is niet gecorreleerd met statusgegevens. Als je "Status" selecteert als uitsplitsing of filter, wordt deze grafiek geen gegevens weergeven.

Aanvullende overwegingen

Verzoeken moeten een veilige vorm van authenticatie bieden, zoals een vooraf gedeeld geheim sleutel, zodat kwaadwillenden zich niet als een van je Roblox-servers kunnen voordoen.
Wees je bewust van de algemene capaciteit en snelheidslimiteringsbeleid van de webservers waarnaar verzoeken worden verzonden.