HTTP-Anfragen im Spiel

*Dieser Inhalt wurde mit KI (Beta) übersetzt und kann Fehler enthalten. Um diese Seite auf Englisch zu sehen, klicke hier.

Sie können HttpService verwenden, um allgemeine HTTP-Anfragen an Drittanbieter-Webdienste für Anwendungsfälle wie Analytik, 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 zulassen unter Datei ⟩ Erlebnis-Einstellungen ⟩ Sicherheit im Studio.

Verwendung in Plugins

Sie können HttpService in Studio-Plugins verwenden, um nach Updates zu suchen, Inhalte herunterzuladen oder andere Geschäftslogik zu implementieren. Beim ersten Versuch eines Plugins, den Dienst zu nutzen, wird der Benutzer möglicherweise aufgefordert, dem Plugin die Erlaubnis zu erteilen, mit der bestimmten Webadresse zu kommunizieren. Benutzer können diese Berechtigungen jederzeit über das Fenster Plugin-Verwaltung akzeptieren, ablehnen oder widerrufen.

Plugins können auch mit anderer Software kommunizieren, die auf demselben Computer läuft, über die Hosts localhost und 127.0.0.1. Durch das Ausführen von Programmen, die mit solchen Plugins kompatibel sind, können Sie die Funktionalität Ihres Plugins über die normalen Möglichkeiten des Studios hinaus erweitern, z. B. durch Interaktion mit dem Dateisystem Ihres Computers. Beachten Sie, dass solche Software separat vom 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 jeden anderen Endpunkt ü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:

Erstellen Sie einen Open Cloud-API-Schlüssel.
Speichern Sie den API-Schlüssel in Ihrem Geheimnisspeicher.
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"), -- Im 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("Antwortkörper:\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 werden unterstützt. Aufgrund der aktuellen Einschränkungen von HttpService ist der ..-String in URL-Pfadparametern zu Roblox-Domains nicht erlaubt. Das bedeutet beispielsweise, dass Datenspeicher und Einträge, die diesen String enthalten, derzeit von HttpService nicht zugänglich sind.

Assets

Sperren und Blockieren

Konfigurationen

Creator Store

Entwicklerprodukte

Spielpässe

Daten- und Speicherdienste

Datenspeicher:

Speicherdienste:

Bestellte Datenspeicher:

Gruppen

Inventare

ListInventoryItems

Luau-Ausführung

Benachrichtigungen

CreateUserNotification

Orte

Universen

Benutzer

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 versuchen, einen blockierten Port zu 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, können die Methoden zum Senden von Anfragen für etwa 30 Sekunden blockiert werden. Ihr pcall() kann ebenfalls mit einer Nachricht von Anzahl der Open Cloud-Anfragen überschritt das Limit fehlschlagen.

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

Für detaillierte Informationen zu Open Cloud-Ratenlimits, authentifizierungsbasiertem Ratenlimit und bewährten Verfahren siehe Ratenlimits.

Bewährte Verfahren

Um die Nutzung von HttpService zu optimieren und die Limits nicht zu überschreiten, wenden Sie die folgenden bewährten Verfahren an:

Behandeln Sie Fehler elegant. Webanfragen können aus vielen Gründen fehlschlagen. Verwenden Sie pcall() und haben Sie einen Plan, wenn Anfragen fehlschlagen. Darüber hinaus sollten Sie alle empfangenen Daten von externen APIs streng validieren und bereinigen, um korrekte Daten sicherzustellen, wo immer Sie können.
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, Staus zu begrenzen und erhöht die Wahrscheinlichkeit einer erfolgreichen Anfrage, indem der Endpunkt Zeit zum "Abkühlen" gegeben wird.
Aggregieren und senden Sie Daten in großen Mengen.

Wenn möglich, wird empfohlen, dass Ihr Server alle erforderlichen Daten sammelt, um eine HTTP-Anfrage zu senden, anstatt mehrere kleine Anfragen zu senden. Wenn Sie beispielsweise eine HTTP-Anfrage für jeden Spieler auf Ihrem Server senden, überprüfen Sie, ob die API einen Bulk-/Batch-Endpunkt hat, und wenn ja, sammeln Sie die Informationen von allen Spielern und senden Sie sie 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 Leistungsverbesserungen durch Funktionen wie Header-Kompression und Multiplexing von Anfragen/Antworten über eine einzige Verbindung. HttpService verwendet automatisch HTTP/2, wenn verfügbar. Beachten Sie, dass die HTTP/2-Spezifikation erfordert, dass alle Headernamen in Kleinbuchstaben gesendet werden.

Beobachtbarkeit

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

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 Anfragetypen)

Status

Erfolg (HTTP 1xx und 2xx Statuscodes)
Umleitung (HTTP 3xx Statuscodes)
400 (Ungültige Anfrage)
401 (Nicht autorisiert)
403 (Verboten)
404 (Nicht gefunden)
429 (Zu viele Anfragen)
500 (Interner Serverfehler)
503 (Dienst nicht verfügbar)
ExternalError (alle anderen nicht spezifizierten Fehlercodes, die vom externen Dienst zurückgegeben werden)
InternalError (ein Problem, das von HttpService innerhalb von Roblox zurückgegeben wird)

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 bieten, wie z. B. 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 bewusst, an die Anfragen gesendet werden.

Deutsch