게임 내 HTTP 요청

*이 콘텐츠는 AI(베타)를 사용해 번역되었으며, 오류가 있을 수 있습니다. 이 페이지를 영어로 보려면 여기를 클릭하세요.

HttpService를 사용하여 분석, 데이터 저장 또는 오류 로깅과 같은 사용 사례를 위해 타사 웹 서비스에 일반 HTTP 요청을 보낼 수 있습니다. HttpService는 특정 Open Cloud 엔드포인트도 지원합니다.

HTTP 요청 활성화

HttpService:GetAsync(), HttpService:PostAsync(), 및 HttpService:RequestAsync() 메서드는 기본적으로 활성화되어 있지 않습니다. 요청을 보내려면 Studio의 파일 ⟩ 경험 설정 ⟩ 보안에서 HTTP 요청 허용을 선택해야 합니다.

Studio 플러그인에서 HttpService를 사용하여 업데이트를 확인하거나 콘텐츠를 다운로드하거나 기타 비즈니스 로직을 수행할 수 있습니다. 플러그인이 서비스를 처음 사용하려고 할 때, 사용자는 특정 웹 주소와 통신하기 위해 플러그인에 권한을 부여하라는 메시지를 받을 수 있습니다. 사용자는 플러그인 관리 창을 통해 언제든지 이러한 권한을 수락, 거부 및 취소할 수 있습니다.

플러그인은 또한 localhost 및 127.0.0.1 호스트를 통해 동일한 컴퓨터에서 실행 중인 다른 소프트웨어와 통신할 수 있습니다. 이러한 플러그인과 호환되는 프로그램을 실행하면 플러그인의 기능을 Studio의 일반적인 기능을 넘어 확장할 수 있으며, 예를 들어 컴퓨터의 파일 시스템과 상호작용할 수 있습니다. 이러한 소프트웨어는 플러그인 자체와 별도로 배포되어야 하며 보안 위험을 초래할 수 있습니다.

Open Cloud와 함께 사용

HttpService는 현재 Open Cloud 엔드포인트의 하위 집합을 호출할 수 있습니다. 이러한 엔드포인트는 HttpService를 통해 다른 엔드포인트를 호출하는 것과 동일한 방식으로 호출할 수 있습니다. 유일한 차이점은 요청에 Open Cloud API 키를 포함해야 한다는 것입니다:

다음 코드 샘플은 게임 내에서 사용자의 그룹 멤버십을 업데이트하는 방법을 보여줍니다:

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", -- JSON을 보낼 때는 이 값을 설정하세요!
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- Creator Hub에서 설정
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("응답이 성공적이었습니다:", response.StatusCode, response.StatusMessage)
	else
		print("응답에 오류가 발생했습니다:", response.StatusCode, response.StatusMessage)
	end
	print("응답 본문:\n", response.Body)
	print("응답 헤더:\n", HttpService:JSONEncode(response.Headers))
end

-- 안전을 위해 함수를 pcall()로 감싸기
local success, errorMessage = pcall(request)
if not success then
	print("HTTP 요청 전송에 실패했습니다:", errorMessage)
end

지원되는 Open Cloud 엔드포인트

다음 엔드포인트가 지원됩니다. 현재 HttpService의 제한으로 인해 Roblox 도메인에 대한 URL 경로 매개변수에 .. 문자열이 허용되지 않습니다. 즉, 예를 들어, 이 문자열이 포함된 데이터 저장소 및 항목은 현재 HttpService에서 접근할 수 없습니다.

자산

차단 및 제한

설정

크리에이터 상점

개발자 제품

게임 패스

데이터 및 메모리 저장소

데이터 저장소:

메모리 저장소:

정렬된 데이터 저장소:

그룹

인벤토리

ListInventoryItems

Luau 실행

알림

CreateUserNotification

장소

유니버스

사용자

제한 사항

x-api-key 및 content-type 헤더만 허용됩니다.
x-api-key 헤더는 Secret이어야 합니다. 비밀 저장소를 참조하세요.
URL 경로 매개변수에 ".." 문자열이 허용되지 않습니다.
HTTPS 프로토콜만 지원됩니다.
포트 1194 또는 1024 미만의 포트를 사용할 수 없으며, 80 및 443을 제외합니다. 차단된 포트를 사용하려고 하면 403 Forbidden 또는 ERR_ACCESS_DENIED 오류가 발생합니다.

비율 제한

각 Roblox 게임 서버에 대해 분당 2500개의 Open Cloud 요청 제한이 있습니다. 이를 초과하면 요청 전송 메서드가 약 30초 동안 중단될 수 있습니다. pcall()도 Open Cloud 요청 수가 제한을 초과했습니다라는 메시지와 함께 실패할 수 있습니다.

Open Cloud 요청은 다른 모든 요청에 대해 시행되는 분당 500개의 HTTP 요청의 동일한 전체 제한을 소비하지 않습니다.
각 엔드포인트는 API 키 소유자(사용자 또는 그룹일 수 있음)마다 자체 제한이 있으며, 호출이 어디에서 오든(HttpService, 웹 등) 이 제한이 시행됩니다.

Open Cloud 비율 제한, 인증 기반 비율 제한 및 모범 사례에 대한 자세한 정보는 비율 제한을 참조하세요.

모범 사례

HttpService 사용을 최적화하고 제한을 초과하지 않도록 다음 모범 사례를 적용하세요:

오류를 우아하게 처리하세요. 웹 요청은 여러 가지 이유로 실패할 수 있습니다. pcall()을 사용하고 요청이 실패할 때의 계획을 세우세요. 또한 외부 API에서 수신한 모든 데이터를 엄격하게 검증하고 정리하여 올바른 데이터를 보장하세요.
지수 백오프를 사용하여 제한을 초과하지 않도록 하세요.

요청이 복구 가능한 오류를 반환하면 즉시 재시도하는 대신 두 초, 네 초, 여덟 초 등으로 대기한 후 시도하세요. 이는 혼잡을 제한하고 엔드포인트가 "식을" 시간을 주어 성공적인 요청의 가능성을 높입니다.
데이터를 집계하고 일괄 전송하세요.

가능하다면 서버가 필요한 모든 데이터를 수집하여 여러 개의 작은 요청 대신 하나의 HTTP 요청을 보내는 것이 좋습니다. 예를 들어, 서버의 모든 플레이어에 대해 HTTP 요청을 보내는 경우 API에 일괄/배치 엔드포인트가 있는지 확인하고, 있다면 모든 플레이어의 정보를 수집하여 하나의 요청으로 전송하세요.

경우에 따라 요청 본문에 데이터를 포함하기 위해 HttpService:RequestAsync()를 사용해야 할 수도 있습니다.
HTTP/2 엔드포인트를 사용하세요. HTTP/2는 헤더 압축 및 단일 연결을 통한 요청/응답 다중화와 같은 기능을 통해 상당한 성능 이점을 제공합니다. HttpService는 사용 가능한 경우 자동으로 HTTP/2를 사용합니다. HTTP/2 사양은 모든 헤더 이름이 소문자로 전송되어야 함을 요구합니다.

관찰 가능성

관찰 가능성 대시보드는 HttpService 사용을 모니터링하고 문제를 해결하기 위한 통찰력과 분석을 제공합니다. 대시보드는 두 가지 주요 차트를 특징으로 합니다: 요청 수는 게임에서의 HttpService 요청의 양을 추적하고, 응답 시간은 엔드포인트가 응답하는 지연 시간을 측정합니다.

필터링 및 분해를 위한 사용 가능한 차원은 다음과 같이 정의됩니다:

요청 유형

GET
POST
PUT
PATCH
DELETE
기타 (지정되지 않은 요청 유형의 경우)

상태

성공 (HTTP 1xx 및 2xx 상태 코드)
리디렉션 (HTTP 3xx 상태 코드)
400 (잘못된 요청)
401 (권한 없음)
403 (금지됨)
404 (찾을 수 없음)
429 (요청이 너무 많음)
500 (내부 서버 오류)
503 (서비스를 사용할 수 없음)
ExternalError (외부 서비스에서 반환된 기타 비지정 오류 코드)
InternalError (HttpService 내에서 발생한 문제)

응답 시간 차트는 상태 데이터와 상관관계가 없습니다. "상태"를 분해 또는 필터로 선택하면 이 차트는 데이터를 표시하지 않습니다.

추가 고려 사항

요청은 사전 공유된 비밀 키와 같은 안전한 인증 형태를 제공해야 하며, 이를 통해 악의적인 행위자가 귀하의 Roblox 서버 중 하나로 가장할 수 없도록 해야 합니다.
요청이 전송되는 웹 서버의 일반적인 용량 및 비율 제한 정책을 인식해야 합니다.

한국어