패턴

이 페이지는 Open Cloud API와 관련된 일반적인 패턴, 특히 요청 및 응답 처리에 대해 다룹니다.

경로

Open Cloud API에 요청을 하려면 먼저 URL을 형성해야 합니다. 이 URL은 기본 URL(예: https://apis.roblox.com), Open Cloud API 경로(예: /cloud/v2/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 호출, 특히 생성 또는 업데이트하는 호출은 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 오류가 발생합니다.

Open Cloud v2

여러 경로

일부 리소스는 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가 요청을 처리하는 데 몇 초 이상 걸리는 경우, 종종 리소스나 응답 자체보다는 작업을 반환합니다.

장기 실행 작업

일부 메서드는 나중에 비동기 응답을 반환하는 장기 실행 요청을 나타내는 Operation 객체를 반환합니다. 이 객체는 다음 필드를 포함합니다:

• path - 요청 완료를 확인하기 위해 호출할 엔드포인트 경로입니다. 이 경로를 리소스 메서드의 원래 기본 URL에 추가합니다.
• done - 작업이 완료되었는지를 나타내는 부울 값입니다.
• response - 응답 객체입니다. 이 필드는 done 필드의 값이 true가 될 때까지 비어 있습니다.
• metadata - 요청과 관련된 사용자 정의 메타데이터입니다.

예제 작업 객체
{
  "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 필드

예시

• 사용자가 소유한 모든 수집 가능한 항목을 반환합니다:

  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