HTTP-Anfragen im Spiel

Sie können HttpService verwenden, um allgemeine HTTP-Anfragen an Drittanbieter-Webdienste für Anwendungsfälle wie Analysen, Datenspeicherung oder Fehlerprotokollierung zu senden. HttpService unterstützt auch bestimmte Open Cloud-Endpunkte.

HTTP-Anfragen aktivieren

Die Methoden HttpService:GetAsync(), HttpService:PostAsync() und HttpService:RequestAsync() sind standardmäßig nicht aktiviert. Um Anfragen zu senden, müssen Sie HTTP-Anfragen erlauben unter Erlebnis-Einstellungen für Ihr Spiel.

Verwendung in Plugins

Sie können HttpService in Studio-Plugins verwenden, um nach Updates zu suchen, Inhalte herunterzuladen oder andere logische Geschäftsabläufe durchzuführen. Beim ersten Versuch eines Plugins, den Dienst zu nutzen, könnte der Benutzer aufgefordert werden, dem Plugin die Erlaubnis zu erteilen, mit der bestimmten Webadresse zu kommunizieren. Benutzer können diese Berechtigungen jederzeit über das Plugin-Management-Fenster akzeptieren, ablehnen oder widerrufen.

Plugins können auch mit anderer Software auf demselben Computer über die Hosts localhost und 127.0.0.1 kommunizieren. Durch das Ausführen von Programmen, die mit solchen Plugins kompatibel sind, können Sie die Funktionalität Ihres Plugins über die normalen Fähigkeiten von Studio hinaus erweitern, z. B. indem Sie mit dem Dateisystem Ihres Computers interagieren. Beachten Sie, dass solche Software separat von dem Plugin selbst verteilt werden muss und Sicherheitsrisiken darstellen kann.

Verwendung mit Open Cloud

HttpService kann derzeit eine Teilmenge der Open Cloud-Endpunkte aufrufen. Sie können diese Endpunkte auf die gleiche Weise aufrufen, wie Sie andere Endpunkte über HttpService aufrufen würden. Der einzige Unterschied besteht darin, dass Sie einen Open Cloud API-Schlüssel in der Anfrage einfügen müssen:

1. Erstellen Sie einen Open Cloud API-Schlüssel.
2. Speichern Sie den API-Schlüssel in Ihrem Geheimnisspeicher.
3. Stellen Sie die Anfrage.

Das folgende Codebeispiel zeigt, wie Sie die Gruppenmitgliedschaft eines Benutzers innerhalb eines Spiels aktualisieren können:

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", -- Beim Senden von JSON setzen Sie dies!
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- In Creator Hub festgelegt
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("Die Antwort war erfolgreich:", response.StatusCode, response.StatusMessage)
	else
		print("Die Antwort gab einen Fehler zurück:", response.StatusCode, response.StatusMessage)
	end
	print("Antwortinhalt:\n", response.Body)
	print("Antwortheader:\n", HttpService:JSONEncode(response.Headers))
end

-- Wickeln Sie die Funktion in pcall() zur Sicherheit ein
local success, errorMessage = pcall(request)
if not success then
	print("Die HTTP-Anfrage konnte nicht gesendet werden:", errorMessage)
end

Unterstützte Open Cloud-Endpunkte

Die folgenden Endpunkte sind unterstützt. Aufgrund aktueller Einschränkungen von HttpService ist der ..-String in URL-Pfadparametern zu Roblox-Domänen nicht erlaubt. Das bedeutet zum Beispiel, dass Datenspeicher und Einträge, die diesen String enthalten, derzeit von HttpService nicht zugänglich sind.

Assets

• GetAsset
• ListAssetVersions
• GetAssetVersion

Sperren und Blockierungen

• ListUserRestrictions (Platz)
• GetUserRestriction (Platz)
• UpdateUserRestriction (Platz)
• ListUserRestrictions (Universum)
• GetUserRestriction (Universum)
• UpdateUserRestriction (Universum)
• ListUserRestrictionLogs (Universum)

Konfigurationen

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

Creator Store

• CreateCreatorStoreProduct
• GetCreatorStoreProduct
• UpdateCreatorStoreProduct
• CreatorStoreAssetsSearch

Entwicklerprodukte

• CreateDeveloperProduct
• UpdateDeveloperProduct
• GetDeveloperProductConfig
• ListDeveloperProductConfigsByUniverse

Spielpässe

• CreateGamePass
• UpdateGamePass
• GetGamePassConfig
• ListGamePassConfigsByUniverse

Daten- und Speicherspeicher

Datenspeicher:

• ListDataStores
• SnapshotDataStores
• ListDataStoreEntries
• CreateDataStoreEntry
• GetDataStoreEntry
• DeleteDataStoreEntry
• UpdateDataStoreEntry
• IncrementDataStoreEntry
• ListDataStoreEntryRevisions
• ListDataStoreEntries (Mit Bereich)
• CreateDataStoreEntry (Mit Bereich)
• GetDataStoreEntry (Mit Bereich)
• DeleteDataStoreEntry (Mit Bereich)
• UpdateDataStoreEntry (Mit Bereich)
• IncrementDataStoreEntry (Mit Bereich)
• ListDataStoreEntryRevisions (Mit Bereich)

Speicher:

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

Bestellte Datenspeicher:

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

Gruppen

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

Inventare

• ListInventoryItems

Luau-Ausführung

• CreateLuauExecutionSessionTaskBinaryInput
• CreateLuauExecutionSessionTask
• CreateLuauExecutionSessionTask (mit Version)
• GetLuauExecutionSessionTask
• ListLuauExecutionSessionTaskLogs

Benachrichtigungen

• CreateUserNotification

Orte

• GetPlace
• UpdatePlace
• GetInstance
• UpdateInstance

Universen

• UpdateUniverse
• GetUniverse
• PublishUniverseMessage
• RestartUniverseServers

Benutzer

• GetUser
• GenerateUserThumbnail

Einschränkungen

• Nur die Header x-api-key und content-type sind erlaubt.
• Der Header x-api-key muss ein Secret sein. Siehe Geheimnisspeicher.
• Der ".."-String ist in URL-Pfadparametern nicht erlaubt.
• Nur das HTTPS-Protokoll wird unterstützt.
• Sie können den Port 1194 oder einen Port unter 1024 nicht verwenden, außer 80 und 443. Wenn Sie einen blockierten Port verwenden, erhalten Sie entweder einen 403 Forbidden oder ERR_ACCESS_DENIED-Fehler.

Ratenlimits

Für jeden Roblox-Spielserver gibt es ein Limit von 2500 Open Cloud-Anfragen pro Minute. Wenn dieses Limit überschritten wird, kann dies dazu führen, dass die Methoden zum Senden von Anfragen etwa 30 Sekunden lang pausieren. Ihr pcall() kann ebenfalls mit einer Meldung von Anzahl der Open Cloud-Anfragen überschreitet das Limit fehlschlagen.

• Open Cloud-Anfragen verbrauchen nicht dasselbe Gesamtlimit von 500 HTTP-Anfragen pro Minute, das für alle anderen Anfragen gelten.
• Jeder Endpunkt hat sein eigenes Limit pro API-Schlüssel-Inhaber (kann ein Benutzer oder eine Gruppe sein), das unabhängig davon durchgesetzt wird, woher die Aufrufe stammen (HttpService, das Web usw.).

Für detaillierte Informationen zu Open Cloud-Ratenlimits, authentifizierungsbasiertem Raten-Limiting und Best Practices siehe Ratenlimits.

Best Practices

Um die Nutzung von HttpService zu optimieren und das Überschreiten der Limits zu vermeiden, wenden Sie die folgenden Best Practices an:

• Behandeln Sie Fehler elegant. Web-Anfragen können aus vielen Gründen fehlschlagen. Verwenden Sie pcall() und haben Sie einen Plan, wenn Anfragen fehlschlagen. Darüber hinaus validieren und sanitieren Sie alle empfangenen Daten von externen APIs streng und stellen Sie sicher, dass die Daten korrekt sind, wo es möglich ist.

• Verwenden Sie exponentielles Backoff, um unter den Limits zu bleiben.

  Wenn eine Anfrage einen wiederherstellbaren Fehler zurückgibt, warten Sie anstelle eines sofortigen erneuten Versuchs zwei Sekunden, dann vier, acht usw. zwischen den Versuchen. Dies hilft, die Überlastung zu begrenzen und erhöht die Chance auf eine erfolgreiche Anfrage, indem es dem Endpunkt Zeit gibt, „abzukühlen“.

• Aggregieren und senden Sie Daten gebündelt.

  Wenn möglich, empfiehlt es sich, Ihren Server alle benötigten Daten sammeln zu lassen, um eine HTTP-Anfrage zu senden, anstatt mehrere kleine Anfragen. Wenn Sie beispielsweise für jeden Spieler in Ihrem Server eine HTTP-Anfrage senden, überprüfen Sie, ob die API einen Bulk-/Batch-Endpunkt hat, und falls ja, sammeln Sie die Informationen von allen Spielern und senden Sie alles in einer Anfrage.

  In einigen Fällen müssen Sie möglicherweise HttpService:RequestAsync() verwenden, um Daten im Body der Anfrage einzuschließen.

• Verwenden Sie HTTP/2-Endpunkte. HTTP/2 bietet erhebliche Leistungssteigerungen durch Funktionen wie Header-Kompression und Multiplexing von Anfrage/Antwort über eine einzige Verbindung. HttpService verwendet automatisch HTTP/2, wenn verfügbar. Beachten Sie, dass die HTTP/2-Spezifikation erfordert, dass alle Header-Namen in Kleinbuchstaben gesendet werden.

Beobachtbarkeit

Das Beobachtungs-Dashboard bietet Einblicke und Analysen zur Überwachung und Fehlersuche bei der Nutzung Ihres HttpService. Das Dashboard verfügt über zwei Hauptdiagramme: Anzahl der Anfragen, die das Volumen der HttpService-Anfragen aus Ihrem Spiel trackt, und Antwortzeit, die die Latenz misst, mit der Endpunkte antworten.

Die verfügbaren Dimensionen für Filterung und Aufschlüsselung sind wie folgt definiert:

Anfragetyp

• GET
• POST
• PUT
• PATCH
• DELETE
• Andere (für nicht spezifizierte Anfragearten)

Status

• Erfolgreich (HTTP 1xx und 2xx Statuscodes)
• Weiterleitung (HTTP 3xx Statuscodes)
• 400 (Bad Request)
• 401 (Unauthorized)
• 403 (Forbidden)
• 404 (Not Found)
• 429 (Too Many Requests)
• 500 (Internal Server Error)
• 503 (Service Unavailable)
• ExternalError (alle anderen nicht spezifizierten Fehlercodes, die vom externen Dienst zurückgegeben werden)
• InternalError (ein Problem, das von HttpService innerhalb von Roblox zurückgegeben wurde)

Das Diagramm Antwortzeit ist nicht mit den Statusdaten korreliert. Wenn Sie "Status" als Aufschlüsselung oder Filter auswählen, wird dieses Diagramm keine Daten anzeigen.

Zusätzliche Überlegungen

• Anfragen sollten eine sichere Form der Authentifizierung bereitstellen, wie einen vorab geteilten geheimen Schlüssel, damit böswillige Akteure sich nicht als einer Ihrer Roblox-Server ausgeben können.
• Seien Sie sich der allgemeinen Kapazitäts- und Ratenbegrenzungsrichtlinien der Webserver, an die Anfragen gesendet werden, bewusst.