게임 내 HTTP 요청

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

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

HTTP 요청 활성화

HttpService:GetAsync(), HttpService:PostAsync(), 및 HttpService:RequestAsync() 메소드는 기본적으로 비활성화되어 있습니다. 요청을 보내려면 게임에 대해 경험 설정에서 HTTP 요청 허용을 활성화해야 합니다.

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

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

Open Cloud와 함께 사용

현재 HttpService는 Open Cloud 엔드포인트의 하위 집합을 호출할 수 있습니다. 이러한 엔드포인트는 다른 엔드포인트를 호출할 때와 같은 방식으로 호출할 수 있습니다. 유일한 차이점은 요청에 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의 제한으로 인해 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에 배치/bulk 엔드포인트가 있는지 확인하고, 그렇다면 모든 플레이어의 정보를 수집하여 하나의 요청으로 보내세요.

경우에 따라 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에서 반환된 문제)

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

추가 고려사항

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

한국어