데이터 저장소에 대한 API 요청 처리

표준 데이터 저장소 및 주문형 데이터 저장소에 대한 Open Cloud API 요청을 보내기 전에, 이들을 올바르게 처리하는 방법을 이해해야 합니다.API 사용에 대한 자세한 정보는 사용 가이드를 참조하십시오.

승인

모든 오픈 클라우드 API와 마찬가지로 데이터 저장소 끝점은 요청에 x-api-key 헤더를 포함하도록 모든 요청을 요구하며, 이 헤더에는 요청에 필요한 API 키가 포함되어 있습니다.이를 위해 키를 경험과 데이터 상점적용하고 끝점 작업이 허용되어야 합니다.키가 무효하면 403 Unauthorized 가 반환됩니다.API 키에 대한 자세한 정보는 API 키 관리를 참조하십시오.

스로틀링

모든 엔드포인트에는 유니버스 레벨 제한의 두 가지 유형이 있습니다: 요청 당 분 제한 과 처리량 제한 .모든 경험에서 요청당 분 제한 을 통해 분당 특정 수의 요청을 보낼 수 있으며, 대역폭 제한 을 통해 API 키 수에 관계없이 분당 특정 수의 데이터를 보낼 수 있습니다.

Luau API와 달리 현재 이러한 제한은 사용자 수에 따라 확장되지 않습니다. 이러한 제한을 초과하면 끝점이 429 Too Many Requests로 반환됩니다.

표준 데이터 저장소 속도 제한

요청 입력	메서드	스로틀 제한
쓰기	입력 설정 증가 입력 입력 삭제	10 MB/min/universe 쓰기 대역폭 300 reqs/min/universe
읽기	데이터 저장소 목록 목록 항목 검색 항목 가져오기 목록 항목 버전 항목 버전 가져오기	20 MB/min/universe 쓰기 대역폭 300 reqs/min/universe

정렬된 데이터 저장소 속도 제한

요청 입력	메서드	스로틀 제한
쓰기	생성 증가 업데이트 삭제	300 요청/분/우주
읽기	목록 가져오기	300 요청/분/우주

입력 검증

요청을 보내기 전에 다음 표에 따라 형식 요구 사항과 제약 조건에 따라 끝점 매개 변수를 유효성 검사하십시오.개별 엔드포인트에는 이들 이상의 추가 요구 사항이 있을 수 있습니다.매개 변수가 다음 제한 사항을 충족하지 않으면 끝점은 400 Bad Request를 반환합니다.

정렬된 데이터 저장소 끝점은 모든 쿼리 및 바디 매개변수에 대해 퍼센트 인코딩을 사용합니다.매개 변수 값에 특수 문자가 없고 URL을 파괴하지 않는 한, 직접 인코딩을 처리할 필요가 없습니다.

입력	유형	노트
universeId	번호	경험의 고유 식별자. 참조하십시오 유니버스 ID.
datastoreName	문자열	길이는 50바이트 이하여야 합니다. null이나 비어있을 수 없습니다.
scope	문자열	데이터 상점범위. 참조 범위. 길이는 50바이트 이하여야 합니다.
entryKey	문자열	길이는 50바이트 이하여야 합니다. null이나 비어있을 수 없습니다.
content-md5	문자열	콘텐츠의 기본-64 인코딩 MD5 체크섬입니다. 참조하십시오 콘텐츠-MD5 .
roblox-entry-attributes	문자열	JSON 개체에 의해 직렬화됩니다. 길이는 300바이트 미만이어야 합니다.
roblox-entry-userids	문자열	0-4 숫자의 JSON 배열로 직렬화됩니다. 사용자 ID가 4개 이상 없습니다.
cursor	문자열	요청한 결과 설정사용 가능한 더 많은 데이터의 지표. 참조 커서.

유니버스 ID

유니버스 ID 는 데이터 저장소에 액세스하려는 경험의 고유 식별자입니다.경험의 유니버스 ID 값은 경험의 시작 장소 ID 와 동일하지 않으며, 전체 경험이 아니라 경험의 시작 장소를 식별하는 시작 장소 ID를 가지고 있습니다.

다음 단계로 경험의 유니버스 ID 를 얻을 수 있습니다.

탐색하여 크리에이터 대시보드로 이동합니다.
액세스하려는 데이터 저장소가 있는 경험을 찾습니다.
경험의 썸네일 섬네일이동하고 ⋯ 버튼을 클릭하고 우주 ID 복사 를 선택합니다.

범위

입력에 대한 하위 폴더를 지정하는 범위로 고유한 문자열을 설정하여 데이터 저장소를 구성할 수 있습니다.You can organize your data stores by setting a unique string as a scope that specifies a subfolder for the entry.범위를 설정하면 데이터 상점수행된 모든 작업의 모든 키에 자동으로 접두사가 붙습니다.범위는 선택 사항이며 기본적으로 표준 데이터 저장소에서는 global로, 주문형 데이터 저장소에서는 필수로 사용됩니다.

정렬 및 목록 작성을 위해 표준 데이터 저장소를 정렬하고 나열하기 위해서는 대신 매개 변수를 사용하는 것이 강력히 권장됩니다.

범위는 문자열과 "/"와 같은 구분 기호로 데이터를 분류합니다.

키	범위
집/사용자_1	집
펫/사용자_1	반려동물
인벤토리/사용자_1	인벤토리

모든 데이터 저장소 입력 작업 메서드에는 기본 범위가 아닌 항목에 액세스해야 할 때 Scope 매개변수가 있습니다.예를 들어, 기본 1234 범위에 키 global 가 있고, 동일한 키가 special 범위에 있을 수 있습니다.범위 매개 변수를 사용하지 않고 전자에 액세스할 수 있지만, 후자에 액세스하려면 범위 매개 변수를 에서 또는 에서 API 호출로 지정해야 합니다.

또한, 데이터 저장소에 하나 이상의 기본이 아닌 범위가 있고 모든 키를 열거하려는 경우 메서드에서 매개 변수를 로 설정하여 호출이 키 문자열과 범위를 포함하는 튜플을 반환할 수 있습니다.이전 예제에서 List Entries 는 응답에서 둘 모두( 1234 , global )와 ( 1234 , special )를 반환합니다.

동일한 요청에서 Scope 및 AllScopes 매개 변수를 전달할 수 없으면 호출이 오류를 반환합니다.데이터 저장소 모듈의 Open Cloud API에서 도움말 기능을 활용하여 다음 코드는 사용자 지정 범위로 데이터 저장소의 모든 키를 읽는 방법을 보여줍니다.

다른 범위의 키 목록
# 설정
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"

# 전역 범위의 키 목록
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)
print(keys.content)
# 특수 범위에 대한 키 목록
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# 모든 범위가 true로 설정된 키 목록
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

해당 범위의 키가 응답에 반환됩니다:

다른 범위에 대한 예시 응답
// 전역 범위에 대한 응답
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }

// 특수 범위에 대한 응답
{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

// AllScopes에 대한 응답
{"keys":[{"scope":"global","key":"User_3"},{"scope":"global","key":"User_4"},{"scope":"global","key":"User_5"},{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

내용-MD5

콘텐츠-MD5는 콘텐츠의 기본-64 인코딩 MD5 체크섬입니다.데이터 무결성을 확인하고 잠재적 문제를 감지하는 Set Entry 백엔드 끝점의 선택적 요청 헤더입니다.

요청에 content-md5 헤더를 포함하지 않으면, 데이터 손상이 발생할 가능성은 낮지만, 비교적 낮은 확률로 발생할 수 있습니다.

선택한 언어를 사용하여 content-md5 헤더의 값을 계산할 수 있습니다.다음 예제에서는 파이썬을 사용합니다.hashlib.md5() 및 base64.b64encode() 함수는 Python 표준 라이브러리(2.7, 3+)에서 사용할 수 있습니다.

콘텐츠-MD5 생성
# 프롬프트로 작업하기
$ python -c "import base64, hashlib; print('content-md5: ' + str(base64.b64encode(hashlib.md5(bytes(input('content: '), encoding='utf8')).digest()), encoding='utf8'))"
content: 750
content-md5: sTf90fedVsft8zZf6nUg8g==
# 오직 stdin과 stdout 사용
$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"
sTf90fedVsft8zZf6nUg8g==

유효한 content-md5 값을 생성하는 문제에 부딪히면 체크섬을 계산하기 전에 UTF-8 바이너리로 요청 본문을 인코딩해야 할 수 있습니다.

커서

데이터 목록을 반환하는 끝점은 또한 nextPageCursor 문자열을 반환할 수 있습니다.이는 요청한 결과 설정더 많은 데이터가 사용 가능하다는 것을 나타냅니다.받으려면 후속 요청에서 cursor 쿼리 매개변수에 이 문자열을 제공하십시오.커서 매개 변수가 제공되지만 유효하지 않은끝점이 400 Bad Request 반환합니다.

커서 문자열의 형식은 정의되지 않았습니다 . 언제든지 변경될 수 있으므로 해석하거나 분석해서는 안됩니다.

필터

주문형 데이터 저장소에 대해 List 메서드에 선택적 filter 쿼리 매개변수를 보내면 지정된 범위의 값이 있는 항목을 반환할 수 있습니다.

filter 매개 변수는 하나의 논리 연산자, && , 그리고 최대값을 설정하기 위한 두 가지 비교 연산자, <= 및 최소값을 설정하기 위한 두 가지 비교 연산자, >= 를 지원합니다.최대 및 최소 값 범위를 모두 설정하려면 두 시퀀스 사이에 &&를 추가하십시오.

예를 들어, 값이 10보다 작거나 같은 항목을 반환하려면 entry <= 10 값으로 filter 를 입력해야 합니다.10과 50 사이의 값을 가진 항목을 반환하려면 entry <= 50 && entry >= 10 를 입력하십시오.

유효한 filter 값을 입력하려면 시퀀스의 각 부분 사이에 공백으로 구분된 모든 filter 문자열을 형식화해야 합니다.각 시퀀스의 왼쪽 부분은 'entry'로 시작해야 하고 오른쪽 부분은 숫자 값을 가져야 합니다.Filter 문자열도 대/소문자 구분됩니다.

다음 예제는 요청을 실패시킬 수 있는 잘못된 filter 값입니다.

entry <= 10 - 시퀀스의 각 부분 사이에 공백이 없습니다.
10 <= entry - entry 및 비교 값이 잘못된 쪽에 있습니다.
entry <= 10 && entry <= 50 - && 는 최소값과 최대값에 대한 두 가지 비교 연산자를 모두 사용하여 범위를 지정하는 데만 사용할 수 있습니다.

누락된 플래그 허용

기존 주문된 데이터 저장소 항목을 업데이트하기 위해 Update 메서드에 요청을 보낼 때, 항목이 존재하지 않더라도 입력을 만들 수 있도록 선택적 allow_missing 플래그를 추가할 수 있습니다.

allow_missing 플래그를 True로 설정하면:

입력이 존재하지 않으면 응답에서 새 입력을 반환합니다.
입력이 있지만 콘텐츠가 엔트리의 기존 값과 일치하면 기존 엔트리는 변경되지 않습니다.
입력이 존재하고 콘텐츠가 엔트리의 기존 값과 일치하지 않으면 응답에서 업데이트된 새 콘텐츠 값으로 엔트리를 반환합니다.

이 페이지