패턴 | 설명서 - Roblox 크리에이터 허브

이 페이지에서는 오픈 클라우드 API에서 일반적인 패턴, 특히 요청 제출 및 응답 처리와 관련하여 설명합니다.

경로

오픈 클라우드 API에 요청을 보내려면 먼저 URL을 형성해야 합니다.이 URL은 기본 URL(https://apis.roblox.com/cloud/v2)과 Open Cloud API 경로(예: /universes/{universe_id}/places/{place_id}/user-restrictions) 및 모든 쿼리 매개변수(예: ?maxPageSize=25)의 조합입니다.전체 요청 URL은 다음과 같이 보일 수 있습니다:


https://apis.roblox.com/cloud/v2/users/4687549151/inventory-items?maxPageSize=100

위의 예제를 포함하여 많은 경로에는 경로 매개 변수 가 있으며, API 참조의 굵은 괄호에 의해 지정됩니다.경로 매개 변수는 요청을 하기 전에 삽입하는 변수이며 거의 항상 ID입니다: 사용자 ID, 그룹 ID, 장소 ID 등.ID는 종종 숫자이지만 반드시 그렇지 않습니다; 예를 들어, 데이터 저장소와 메모리 저장소 ID는 더 넓은 문자 설정지원합니다.

일부 리소스에는 API 참조의 리소스 경로 헤더에 표시되는 여러 경로 패턴이 있습니다.예를 들어, 사용자 제한 목록의 URL은 팔로잉중 하나일 수 있습니다.

https://apis.roblox.com/cloud/cloud/v2/universes/{universe_id}/user-restrictions
https://apis.roblox.com/cloud/cloud/v2/universes/{universe_id}/places/{place_id}/user-restrictions

아마 두 사이의 차이를 추론할 수 있습니다: 일부 사용자 제한은 전체 우주(경험)에 적용되지만, 다른 사용자 제한은 우주 내의 특정 장소에 적용됩니다.경로와 추가 경로 매개 변수에 대한 작은 추가 외에, 호출은 동일합니다.

많은 API가 응답의 일부로 경로를 반환하며, 이를 사용하여 추가 요청을 할 수 있습니다.API가 요청을 완료하는 데 몇 초 이상이 필요한 경우 자원이나 응답 자체가 아닌 작업을 종종 반환합니다.

콘텐츠 길이와 입력

리소스를 생성하거나 업데이트하는 많은 API 호출, 특히 리소스를 생성하거나 업데이트하는 호출은 JSON 요청 신체필요합니다.요청에 본문이 있는 경우 Content-Length 및 Content-Type 헤더를 포함하는 것이 좋습니다.대부분의 HTTP 클라이언트는 이러한 헤더를 자동으로 추가합니다.

페이지네이션

요청에서 maxPageSize를 지정하면 일부 메서드가 페이지 된 결과를 반환합니다. 즉, 부분 응답입니다.


GET /cloud/v2/users/{user_id}/inventory-items?maxPageSize=25

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": "aaaBBB"
}


GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25

{
  "dataStores": [
    ...
  ],
  "nextPageToken": "datastore1"
}

응답에 nextPageToken 값이 포함되어 있으면 다음 요청의 pageToken 매개변수에서 해당 값을 사용하여 다음 페이지를 검색합니다.nextPageToken 이 비어 있거나 전체적으로 생략되면 결과의 끝에 도달했습니다:


GET /cloud/v2/users/{user_id}/inventory-items?maxPageSize=25&pageToken=aaaBBB

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": ""
}


GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25&pageToken=datastore1

{
  "dataStores": [
    ...
  ]
}

pageToken 외에도 페이지 번호가 올바르게 작동하려면 동일한 쿼리를 사용해야 합니다. 필터 매개변수를 변경하면 400 오류가 발생합니다.

장시간 실행 작업

일부 메서드는 나중에 비동기 응답을 반환하는 긴 실행 요청을 나타내는 Operation 개체를 반환합니다.개체에는 다음 필드가 포함되어 있습니다:

경로 - 요청의 완료를 조사하기 위한 끝점 경로. 리소스 메서드의 원래 기본 URL에 경로를 추가합니다.
완료 - 작업이 완료되었는지 여부를 나타내는 부울 값
응답 - 응답 개체. 이 필드는 필드에 값이 없을 때까지 비어 있습니다. - 응답 개체. 이 필드는 값이 없을 때까지 비어 있습니다.
메타데이터 - 요청된 특정 메타데이터.

예제 작업 개체
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "myValue",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "string",
    "metadata2": 5678
  }
}

리소스가 준비될 때 투표하기 위해 Operation 개체의 경로를 사용하십시오.좋은 전략은 지수 백오프를 사용하는 것입니다.예를 들어, 즉시 조사한 다음 1초, 2초, 4초 등 후에 조사할 수 있습니다.


def PollForResults(operationPath):
    currentRetries = 0
    maxRetries = 10
    retryPollingDelay = 1
    retryPollingMultiplier = 2
    while (currentRetries < maxRetries):
        # 첫 번째 확인지연 없음
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # 후속 검사에 대한 논리 재시도
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # 지수 백오프
            retryPollingDelay *= retryPollingMultiplier
        # 결과를 확인하고 존재하는 경우 반환
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # 그렇지 않으면 재시도 횟수를 증가시키십시오
        else:
           currentRetries += 1

고정 재시도 간격을 사용하는 대신 지수 백오프를 사용하는 더 완전한 코드 샘플은 결과 조사를 참조하십시오.

필터링

일부 메서드는 요청에 filter 매개 변수를 포함하여 응답을 필터링하도록 합니다.다음 섹션에서는 지정된 끝점에 대한 필터 구문 및 가이드라인을 설명합니다.

그룹 멤버십 목록 표시

와일드카드 문자 -는 모든 그룹에서 멤버를 나열하기 위해 그룹 ID 대신 사용할 수 있습니다: groups/-/memberships.

필터링은 공통 표현 언어(CEL)에 부합합니다. 두 개의 연산자만 지원됩니다:

==
in [...]

리소스 경로에 그룹 ID를 지정하면 다음 형식으로 사용자 또는 역할에 따라 멤버십을 필터링할 수 있습니다.

사용자 필터 : filter="user == 'users/9876543210'"
역할 필터 : filter="role == 'groups/123/roles/7920705'"

그룹 ID에 와일드카드 문자를 지정하는 경우 다음 형식으로 사용자 구성원을 필터링해야 합니다(최대 50):

사용자 필터 : filter="user in ['users/1', 'users/156', 'users/9876543210', ...]"

인벤토리 항목 목록 표시

수집품 상태, 인벤토리 아이템 입력및 인벤토리 아이템 ID로 필터링할 수 있습니다.필터를 제공하지 않으면 사용자의 전체 재고가 반환됩니다.

필터 형식은 세미콜론으로 구분된 목록입니다:

filter={field}={value};{field}={value},{value},...;{field}=...

{field} 는 다음 표의 미리 정의된 유형 필드 또는 ID 필드 중 하나일 수 있습니다.
{value} 문자열, 부울 또는 열거형일 수 있습니다.필드 입력따라 이는 단일 값(부울 필드) 또는 여러 값(목록 필드)일 수 있습니다.

동일한 필터에서 유형 및 ID 필드를 결합할 수 없습니다.

필드 입력

ID 필드

| 필터 | 유형 | 설명 | | :----------------- | :----- | :--------------------------------------------------------------------------------------------------------------------- | | assetIds | 문자열 | 숫자 자산 ID를 포함할 구분 목록. | | badgeIds | 문자열 | 포함할 숫자 배지 ID 목록을 쉼표로 구분합니다. | | gamePassIds | 문자열 | 포함할 숫자 게임 패스 ID 목록을 쉼표로 구분합니다. | | privateServerIds | 문자열 | 포함할 숫자 개인 서버 ID 목록을 쉼표로 구분합니다.이 필드로 필터링할 인벤토리 읽기 범위가 있어야 합니다. |

예시

사용자가 소유하는 모든 수집 아이템을 반환합니다:

filter=onlyCollectibles=true;inventoryItemAssetTypes=*
지정된 유형의 모든 항목을 반환합니다:

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
나열된 유형의 모든 항목 또는 게임 패스를 반환합니다.결과에서 배지를 제외합니다(필터에 포함되지 않은 것과 동일한 행동):

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false
지정된 ID와 일치하는 자산을 반환합니다:

filter=assetIds=1,2,3,4
지정된 ID와 일치하는 자산, 배지, 게임 패스 및 개인 서버를 반환합니다:

filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4