패턴

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

이 페이지는 Open Cloud API에 대한 일반적인 패턴을 설명합니다, 특히 요청을 처리하는 방법과 응답을 처리하는 방법에 대해.

경로

Open Cloud API에 요청을 만들려면 먼저 URL을 형성해야 합니다. 이 URL은 기본 URL( https://apis.roblox.com/cloud/v2 )의 조합이며, Open Cloud API 경로(예: /universes/universe-id/places/place-id/user-restraints </

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

위의 예에 대한 경로 포함 많은 경로에는 경로 매개 변수 가 있습니다, API 참조에 있는 컬리 브라켓으로 지정된 짝수 브라켓에 있습니다. 경로 매개 변수는 요청을 만드기 전에 입력하는 변수이며, 대부분 ID입니다. 데이터 저장소

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

  • 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/{userId}/inventory-items?maxPageSize=25



{

  "inventoryItems": [

    ...

  ],

  "nextPageToken": "aaaBBB"

}

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

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



{

  "inventoryItems": [

    ...

  ],

  "nextPageToken": ""

}

pageToken 외에도 페이지 내 링크를 사용하여 콘텐츠를 구성해야 합니다. 필터 매개 변수를 변경하면 400 오류가 발생합니다.

길게 실행되는 작업

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

  • 경로 - 요청의 완료를 위해 호출할 엔드포인트 경로. 리소스 메서드의 원래 베이스 URL에 경로를 추가합니다.
  • done - 작업이 완료되었는지 여부를 나타내는 부울 값입니다.
  • 응답 - 응답 개체입니다. 이 필드는 done 필드에 값이 true 이면 비워집니다.
  • 메타데이터 - 요청이 제출되는 특정 메타데이터 사용자 지정.
작업 개체 예시
{

  "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 .

필터는 Common Expressions Language(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로 필터링할 수 있습니다. 필터를 제공하지 않으면 사용자의 전체 인벤토리가 반환됩니다.

필터 형식은 semicolon-separated list입니다.

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