GET (/scids//leaderboards/)

사전 정의된 전역 리더보드를 가져옵니다. 이 URI의 도메인은 leaderboards.xboxlive.com입니다.

설명
URI 매개변수
쿼리 문자열 매개변수
권한 부여
개인정보 설정이 리소스에 미치는 영향
필수 요청 헤더
선택적 요청 헤더
HTTP 상태 코드
응답 헤더
응답 본문

설명

리더보드 API는 모두 읽기 전용이므로 GET 동사만 지원합니다. 이 API는 Player Data 시스템을 통해 기록된 개별 사용자 통계에서 파생된, 인덱싱된 플레이어 통계의 순위가 매겨지고 정렬된 “페이지”를 반영합니다. 전체 리더보드 인덱스는 매우 클 수 있으며 호출자는 절대 전체를 보기를 요청하지 않으므로, 이 URI는 호출자가 해당 리더보드에 대해 어떤 종류의 뷰를 보고자 하는지 구체적으로 지정할 수 있는 여러 쿼리 문자열 인수를 지원합니다. GET 작업은 리소스를 수정하지 않으므로 한 번 실행하든 여러 번 실행하든 동일한 결과가 생성됩니다.

URI 매개변수

매개변수	형식	설명
scid	GUID	액세스하려는 리소스를 포함하는 서비스 구성의 식별자입니다.
leaderboardname	string	액세스하려는 사전 정의된 리더보드 리소스의 고유 식별자입니다.

쿼리 문자열 매개변수

| 매개변수| 형식| 설명| | --- | --- | --- | --- | --- | --- | | maxItems| 32비트 부호 없는 정수| 결과 페이지에서 반환할 리더보드 레코드의 최대 개수입니다. 지정되지 않은 경우 기본값(10)이 반환됩니다. maxItems의 최댓값은 아직 정의되어 있지 않지만, 큰 데이터 집합을 피하고자 하므로 이 값은 튜너 UI가 호출당 처리할 수 있는 가장 큰 집합을 대상으로 하는 것이 좋습니다.| | skipToRank| 32비트 부호 없는 정수| 지정된 리더보드 순위부터 시작하는 결과 페이지를 반환합니다. 나머지 결과는 순위 순으로 정렬됩니다. 이 쿼리 문자열은 후속 쿼리에 다시 전달하여 “다음 페이지” 결과를 얻을 수 있는 연속 토큰을 반환할 수 있습니다.| | skipToUser| string| 사용자의 순위나 점수와 관계없이 지정된 게이머 xuid를 중심으로 하는 리더보드 결과 페이지를 반환합니다. 페이지는 백분위 순위로 정렬되며, 사전 정의된 뷰의 경우 지정된 사용자가 페이지의 마지막 위치에, 통계 리더보드 뷰의 경우 중간에 위치합니다. 이 유형의 쿼리에는 continuationToken이 제공되지 않습니다.| | continuationToken| string| 이전 호출에서 continuationToken이 반환된 경우, 호출자는 해당 토큰을 쿼리 문자열에 “그대로” 다시 전달하여 다음 페이지의 결과를 가져올 수 있습니다.|

권한 부여

콘텐츠 격리 및 액세스 제어 시나리오를 위한 권한 부여 로직이 구현되어 있습니다.

리더보드와 사용자 통계는 호출자가 요청과 함께 유효한 XSTS 토큰을 제출하는 한 모든 플랫폼의 클라이언트에서 읽을 수 있습니다. 쓰기는 명백히 Player Data 시스템에서 지원하는 클라이언트로 제한됩니다.
타이틀 개발자는 Partner Center를 통해 통계를 공개 또는 제한으로 표시할 수 있습니다. 리더보드는 공개 통계입니다. 공개 통계는 사용자가 샌드박스에 대해 권한이 부여되어 있는 한 Smartglass는 물론 iOS, Android, Windows, Windows Phone 및 웹 애플리케이션에서 액세스할 수 있습니다. 사용자의 샌드박스에 대한 권한 부여는 Partner Center를 통해 관리됩니다.

검사의 의사 코드는 다음과 같습니다.

If (!checkAccess(serviceConfigId, resource, CLAIM[userid, deviceid, titleid]))
{
        Reject request as Unauthorized
}

// else accept request.
         

개인정보 설정이 리소스에 미치는 영향

리더보드 데이터를 읽을 때는 개인정보 검사를 수행하지 않습니다.

필수 요청 헤더

| 헤더| 설명| | --- | --- | --- | --- | --- | --- | --- | --- | | Authorization| String. HTTP 인증을 위한 인증 자격 증명입니다. 예제 값: XBL3.0 x=<userhash>;<token>| | X-RequestedServiceVersion| String. 요청이 라우팅되어야 하는 XBOX LIVE 서비스의 빌드 이름/번호입니다. 요청은 헤더, 인증 토큰의 클레임 등의 유효성이 확인된 후에만 해당 서비스로 라우팅됩니다. 기본값: 1.| | Accept| String. 허용 가능한 Content-Type입니다. 예제 값: application/json|

선택적 요청 헤더

헤더	설명
If-None-Match	String. 엔터티 태그로, 클라이언트가 캐싱을 지원할 경우 사용됩니다. 예제 값: “686897696a7c876b7e”

HTTP 상태 코드

이 리소스에서 이 메서드로 이루어진 요청에 대한 응답으로 서비스는 이 섹션의 상태 코드 중 하나를 반환합니다. XBOX Live Services에서 사용되는 표준 HTTP 상태 코드의 전체 목록은 표준 HTTP 상태 코드를 참조하세요. | 코드| 이유 구문| 설명| | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 200| OK| 세션을 성공적으로 검색했습니다.| | 304| Not Modified| 마지막 요청 이후 리소스가 수정되지 않았습니다.| | 400| Bad Request| 서비스가 잘못된 형식의 요청을 이해할 수 없습니다. 일반적으로 잘못된 매개변수입니다.| | 401| Unauthorized| 요청에 사용자 인증이 필요합니다.| | 403| Forbidden| 사용자 또는 서비스에 대한 요청이 허용되지 않습니다.| | 404| Not Found| 지정된 리소스를 찾을 수 없습니다.| | 406| Not Acceptable| 리소스 버전이 지원되지 않습니다.| | 408| Request Timeout| 리소스 버전이 지원되지 않습니다. MVC 계층에서 거부해야 합니다.|

응답 헤더

| 헤더| 형식| 설명| | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Content-Type| string| 필수. 응답 본문의 MIME 형식입니다. 예: application/json.| | Content-Length| string| 필수. 응답에서 전송되는 바이트 수입니다. 예: 232.| | ETag| string| 선택 사항. 캐시 최적화에 사용됩니다. 예: 686897696a7c876b7e.|

응답 본문

응답 멤버

pagingInfo | pagingInfo| 섹션| 선택 사항. 요청에 maxItems가 지정된 경우에만 존재합니다.| | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | continuationToken| 64비트 부호 없는 정수| 필수. 원하는 경우 해당 URI에 대한 다음 결과 페이지를 가져오기 위해 skipItems 쿼리 매개변수에 다시 전달할 값을 지정합니다. pagingInfo가 반환되지 않은 경우 얻을 수 있는 데이터의 다음 페이지가 없습니다.| | totalCount| 64비트 부호 없는 정수| 필수. 리더보드의 총 항목 수입니다. 예제 값: 1234567890| leaderboardInfo | leaderboardInfo| 섹션| 필수. 항상 반환됩니다. 요청한 리더보드에 대한 메타데이터를 포함합니다.| | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | displayName| string| 사용되지 않습니다.| | totalCount| string (64비트 부호 없는 정수)| 필수. 리더보드의 총 항목 수입니다. 예제 값: 1234567890| | columns| array| 필수. 리더보드의 열입니다.| | displayName| string| 필수. 리더보드의 열에 해당합니다.| | statName| string| 필수. 리더보드의 열에 해당합니다.| | type| string| 필수. 리더보드의 열에 해당합니다.| userList | userList| 섹션| 필수. 항상 반환됩니다. 요청한 리더보드에 대한 실제 사용자 점수를 포함합니다.| | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | gamertag| string| 필수. 리더보드 항목의 사용자에 해당합니다.| | xuid| 64비트 부호 없는 정수| 필수. 리더보드 항목의 사용자에 해당합니다.| | percentile| string| 필수. 리더보드 항목의 사용자에 해당합니다.| | rank| string| 필수. 리더보드 항목의 사용자에 해당합니다.| | values| array| 필수. 쉼표로 구분된 각 값은 리더보드의 열에 해당합니다.|

샘플 응답

다음 요청 URI는 전역 리더보드에서 순위로 건너뛰는 것을 나타냅니다.

https://leaderboards.xboxlive.com/scids/0FA0D955-56CF-49DE-8668-05D82E6D45C4/leaderboards/TotalFlagsCaptured/columns/deaths?maxItems=3&skipToRank=15000
         

위 URI는 다음 JSON 응답을 반환합니다.

{
    "pagingInfo": {
        "continuationToken": "152",
        "totalItems": 23437
    },
    "leaderboardInfo": {
        "displayName": "Total flags captured",
        "totalCount": 23437,
        "columns": [
            {
                "displayName": "Flags Captured",
                "statName": "flagscaptured",
                "type": "Integer"
            },
            {
                "displayName": "Deaths",
                "statName": "deaths",
                "type": "Integer"
            }
        ]
    },
    "userList": [
        {
            "gamertag": "WarriorSaint",
            "xuid": 1234567890123444,
            "percentile": 0.64,
            "rank": 15000,
            "values": [
                1000,
                47
            ]
        },
        {
            "gamertag": "xxxSniper39",
            "xuid": 1234567890123555,
            "percentile": 0.64,
            "rank": 15001,
            "values": [
                998,
                17
            ]
        },
        {
            "gamertag": "WhockaWhocka",
            "xuid": 1234567890123666,
            "percentile": 0.64,
            "rank": 15002,
            "values": [
                996,
                2
            ]
        }
    ]
}
         

다음 요청 URI는 전역 리더보드에서 사용자로 건너뛰는 것을 나타냅니다.

https://leaderboards.xboxlive.com/scids/0FA0D955-56CF-49DE-8668-05D82E6D45C4/leaderboards/totalflagscaptured?maxItems=3&skipToUser=2343737892734237
         

위 URI는 다음 JSON 응답을 반환합니다.

{
    "leaderboardInfo": 
    {
       "displayName": "Total flags captured",
       "totalCount": 23437,
       "columns": [
              {
                  "displayName": "Flags Captured",
                  "statName": "flagscaptured",
                  "type": "Integer"
              }
       ]
    },
    "userList": [
        {
            "gamertag": "AverageJoe",
            "percentile": 55.00,
            "rank": 11718,
            "value": 1219,
            "xuid": 1234567890123444
        },
        {
            "gamertag": "AreUWatchinMe",
            "percentile": 60.00,
            "rank": 14162,
            "value": 1062,
            "xuid": 2343737892734333
        },
         {
            "gamertag": "WarriorSaint",
            "percentile": 64.39,
            "rank": 15000,
            "value ": 1000,
            "xuid": 1234567890123455
        }
    ]
}
         

참고 항목

상위 항목

/scids//leaderboards/

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

GET (/scids/{scid}/leaderboards/{leaderboardname})

GET (/scids//leaderboards/)

설명

URI 매개변수

쿼리 문자열 매개변수

권한 부여

개인정보 설정이 리소스에 미치는 영향

필수 요청 헤더

선택적 요청 헤더

HTTP 상태 코드

응답 헤더

응답 본문

응답 멤버

샘플 응답

참고 항목

상위 항목

​GET (/scids//leaderboards/)

​설명

​URI 매개변수

​쿼리 문자열 매개변수

​권한 부여

​개인정보 설정이 리소스에 미치는 영향

​필수 요청 헤더

​선택적 요청 헤더

​HTTP 상태 코드

​응답 헤더

​응답 본문

​응답 멤버

​샘플 응답

​참고 항목

상위 항목

GET (/scids//leaderboards/)

설명

URI 매개변수

쿼리 문자열 매개변수

권한 부여

개인정보 설정이 리소스에 미치는 영향

필수 요청 헤더

선택적 요청 헤더

HTTP 상태 코드

응답 헤더

응답 본문

응답 멤버

샘플 응답

참고 항목