Żądania HTTP w grze

*Ta zawartość została przetłumaczona przy użyciu narzędzi AI (w wersji beta) i może zawierać błędy. Aby wyświetlić tę stronę w języku angielskim, kliknij tutaj.

Możesz użyć HttpService, aby wysyłać ogólne żądania HTTP do zewnętrznych usług internetowych w takich przypadkach jak analityka, przechowywanie danych lub rejestrowanie błędów. HttpService obsługuje również niektóre punkty końcowe Open Cloud.

Włącz żądania HTTP

Metody HttpService:GetAsync(), HttpService:PostAsync() i HttpService:RequestAsync() nie są domyślnie włączone. Aby wysyłać żądania, musisz Zezwolić na żądania HTTP w Plik ⟩ Ustawienia doświadczenia ⟩ Bezpieczeństwo w Studio.

Użycie w wtyczkach

Możesz używać HttpService w wtyczkach Studio, aby sprawdzać aktualizacje, pobierać treści lub realizować inne logiki biznesowe. Przy pierwszej próbie użycia usługi przez wtyczkę użytkownik może zostać poproszony o udzielenie wtyczce zgody na komunikację z danym adresem internetowym. Użytkownicy mogą akceptować, odrzucać i cofać te uprawnienia w dowolnym momencie za pośrednictwem okna Zarządzanie wtyczkami.

Wtyczki mogą również komunikować się z innym oprogramowaniem działającym na tym samym komputerze za pośrednictwem hostów localhost i 127.0.0.1. Uruchamiając programy kompatybilne z takimi wtyczkami, możesz rozszerzyć funkcjonalność swojej wtyczki poza normalne możliwości Studio, takie jak interakcja z systemem plików komputera. Uważaj, że takie oprogramowanie musi być dystrybuowane oddzielnie od samej wtyczki i może stwarzać zagrożenia bezpieczeństwa.

Użycie z Open Cloud

HttpService może obecnie wywoływać podzbiór punktów końcowych Open Cloud. Możesz wywoływać te punkty końcowe w ten sam sposób, w jaki wywołujesz inne punkty końcowe za pośrednictwem HttpService. Jedyną różnicą jest to, że musisz dołączyć klucz API Open Cloud do żądania:

Utwórz klucz API Open Cloud.
Zapisz klucz API w swoim magazynie sekretów.
Wykonaj żądanie.

Poniższy przykład kodu demonstruje, jak zaktualizować członkostwo użytkownika w grupie z poziomu gry:

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", -- Przy wysyłaniu JSON, ustaw to!
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- Ustawione w Creator Hub
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("Odpowiedź była pomyślna:", response.StatusCode, response.StatusMessage)
	else
		print("Odpowiedź zwróciła błąd:", response.StatusCode, response.StatusMessage)
	end
	print("Treść odpowiedzi:\n", response.Body)
	print("Nagłówki odpowiedzi:\n", HttpService:JSONEncode(response.Headers))
end

-- Owiń funkcję w pcall() dla bezpieczeństwa
local success, errorMessage = pcall(request)
if not success then
	print("Żądanie HTTP nie powiodło się:", errorMessage)
end

Obsługiwane punkty końcowe Open Cloud

Poniższe punkty końcowe są obsługiwane. Z powodu obecnych ograniczeń w HttpService, ciąg .. nie jest dozwolony w parametrach ścieżki URL do domen Roblox. Oznacza to, że na przykład magazyny danych i wpisy zawierające ten ciąg są obecnie niedostępne z HttpService.

Aktywa

Zakazy i blokady

Konfiguracje

Sklep twórcy

Produkty dewelopera

Przepustki do gier

Magazyny danych i pamięci

Magazyny danych:

Magazyny pamięci:

Zamówione magazyny danych:

Grupy

Inwentarze

ListInventoryItems

Wykonanie Luau

Powiadomienia

CreateUserNotification

Miejsca

Wszechświaty

Użytkownicy

Ograniczenia

Dozwolone są tylko nagłówki x-api-key i content-type.
Nagłówek x-api-key musi być Secret. Zobacz Magazyny sekretów.
Ciąg ".." nie jest dozwolony w parametrach ścieżki URL.
Obsługiwany jest tylko protokół HTTPS.
Nie możesz używać portu 1194 ani żadnego portu poniżej 1024, z wyjątkiem 80 i 443. Jeśli spróbujesz użyć zablokowanego portu, otrzymasz błąd 403 Forbidden lub ERR_ACCESS_DENIED.

Limity szybkości

Dla każdego serwera gry Roblox istnieje limit 2500 żądań Open Cloud na minutę. Przekroczenie tego limitu może spowodować, że metody wysyłania żądań będą się zatrzymywać na około 30 sekund. Twój pcall() może również zakończyć się niepowodzeniem z komunikatem Liczba żądań Open Cloud przekroczyła limit.

Żądania Open Cloud nie zużywają tego samego ogólnego limitu 500 żądań HTTP na minutę, który jest egzekwowany dla wszystkich innych żądań.
Każdy punkt końcowy ma swój własny limit dla właściciela klucza API (może to być użytkownik lub grupa), który jest egzekwowany niezależnie od tego, skąd pochodzą wywołania (HttpService, sieć itp.).

Aby uzyskać szczegółowe informacje na temat limitów szybkości Open Cloud, ograniczeń opartych na uwierzytelnianiu i najlepszych praktyk, zobacz Limity szybkości.

Najlepsze praktyki

Aby zoptymalizować użycie HttpService i uniknąć przekroczenia limitów, zastosuj następujące najlepsze praktyki:

Obsługuj błędy w sposób elegancki. Żądania internetowe mogą nie powieść się z wielu powodów. Użyj pcall() i miej plan na wypadek, gdyby żądania się nie powiodły. Ponadto ściśle waliduj i oczyszczaj wszystkie otrzymane dane z zewnętrznych API, zapewniając poprawne dane tam, gdzie to możliwe.
Użyj exponential backoff, aby pozostać poniżej limitów.

Jeśli żądanie zwróci błąd, który można naprawić, zamiast natychmiastowego ponownego próbowania, poczekaj dwie sekundy, potem cztery, osiem itd. między próbami. To pomaga ograniczyć zator i zwiększa szansę na pomyślne żądanie, dając punktowi końcowemu czas na "schłodzenie się".
Agreguj i wysyłaj dane w partiach.

Kiedy to możliwe, zaleca się, aby serwer zbierał wszystkie niezbędne dane, aby wysłać jedno żądanie HTTP, a nie wiele małych żądań. Na przykład, jeśli wysyłasz żądanie HTTP dla każdego gracza na swoim serwerze, sprawdź, czy API ma punkt końcowy do zbiorczego przetwarzania i, jeśli tak, zbierz informacje od wszystkich graczy i wyślij je w jednym żądaniu.

W niektórych przypadkach może być konieczne użycie HttpService:RequestAsync(), aby dołączyć dane do treści żądania.
Używaj punktów końcowych HTTP/2. HTTP/2 zapewnia znaczące korzyści wydajnościowe dzięki funkcjom takim jak kompresja nagłówków i multiplexing żądań/odpowiedzi przez jedno połączenie. HttpService automatycznie używa HTTP/2, gdy jest dostępne. Należy pamiętać, że specyfikacja HTTP/2 wymaga, aby wszystkie nazwy nagłówków były wysyłane małymi literami.

Obserwowalność

Panel Obserwowalności dostarcza informacji i analiz do monitorowania i rozwiązywania problemów z użyciem HttpService. Panel zawiera dwa główne wykresy: Liczba żądań, który śledzi liczbę żądań HttpService z twojej gry, oraz Czas odpowiedzi, który mierzy opóźnienie w odpowiedzi punktów końcowych.

Dostępne wymiary do filtrowania i podziału są zdefiniowane w następujący sposób:

Typ żądania

GET
POST
PUT
PATCH
DELETE
Inne (dla niesprecyzowanych typów żądań)

Status

Sukces (kody statusu HTTP 1xx i 2xx)
Przekierowanie (kody statusu HTTP 3xx)
400 (Złe żądanie)
401 (Nieautoryzowany)
403 (Zabronione)
404 (Nie znaleziono)
429 (Za dużo żądań)
500 (Błąd wewnętrzny serwera)
503 (Usługa niedostępna)
ExternalError (wszystkie inne niesprecyzowane kody błędów zwrócone przez zewnętrzną usługę)
InternalError (problem zwrócony przez HttpService w Roblox)

Wykres Czas odpowiedzi nie jest skorelowany z danymi statusu. Jeśli wybierzesz "Status" jako podział lub filtr, ten wykres nie wyświetli danych.

Dodatkowe uwagi

Żądania powinny zapewniać bezpieczną formę uwierzytelnienia, taką jak wcześniej ustalony klucz tajny, aby złe podmioty nie mogły podszywać się pod jeden z twoich serwerów Roblox.
Bądź świadomy ogólnych polityk pojemności i limitów szybkości serwerów internetowych, do których wysyłane są żądania.

Polski