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

아티클
05/10/2023

미리 정의된 글로벌 순위표를 가져옵니다.

이 URI의 도메인은 leaderboards.xboxlive.com입니다.

비고
URI 매개 변수
쿼리 문자열 매개 변수
Authorization
리소스에 대한 개인 정보 설정의 영향
필수 요청 헤더
선택적 요청 헤더
HTTP 상태 코드
응답 헤더
응답 본문

설명

순위표 API는 모두 읽기 전용이므로 GET 동사만 지원합니다. 플레이어 데이터 시스템을 통해 작성된 개별 사용자 통계의 인덱싱된 파생 플레이어 통계의 순위가 지정되고 정렬된 "페이지"를 반영합니다. 전체 순위표 인덱스는 대규모일 수 있으며 호출자는 전체를 볼 필요가 없으므로 이 URI는 호출자가 해당 순위표에 대해 보고 싶은 유형을 특정할 수 있는 여러 쿼리 문자열 인수를 지원합니다.

GET 작업은 리소스를 수정하지 않으므로 한 번 또는 여러 번 실행하는 경우 동일한 결과가 생성됩니다.

URI 매개 변수

매개 변수	형식	설명
scid	GUID	액세스되는 리소스를 포함하는 서비스 구성 식별자입니다.
leaderboardname	문자열	액세스되는 미리 정의된 순위표 리소스의 고유 식별자입니다.

쿼리 문자열 매개 변수

매개 변수	형식	설명
maxItems	32비트 부호 없는 정수	결과 페이지에서 반환할 순위표 레코드의 최대 수입니다. 지정하지 않으면 기본 숫자가 반환됩니다(10). maxItems의 최대 값은 여전히 정의되어 있지 않지만 대규모 데이터 집합은 방지하고자 하므로 이 값은 튜너 UI가 호출당 처리할 수 있는 최대 집합을 대상으로 해야 합니다.
skipToRank	32비트 부호 없는 정수	지정된 순위표 순위로 시작하는 결과 페이지를 반환합니다. 나머지 결과는 순위별로 정렬됩니다. 이 쿼리 문자열은 결과의 "다음 페이지"를 가져오기 위해 후속 쿼리로 다시 공급될 수 있는 연속 토큰을 반환할 수 있습니다.
skipToUser	문자열	해당 사용자의 순위 또는 점수와 상관없이 지정된 gamer xuid와 관련하여 순위표 결과 페이지를 반환합니다. 해당 페이지는 미리 정의된 보기 페이지의 마지막 위치에서 지정된 사용자와 함께 백분위 수 순위에 따라 정렬되거나 통계 순위표 보기의 중간에 정렬됩니다. 이 유형의 쿼리에는 continuationToken이 제공되지 않습니다.
continuationToken	문자열	이전 호출에서 continuationToken이 반환된 경우 호출자는 쿼리 문자열에서 해당 토큰을 "있는 그대로" 다시 전달하여 결과의 다음 페이지를 가져올 수 있습니다.

Authorization

콘텐츠 격리 및 액세스 제어 시나리오에 대해 구현된 권한 부여 논리가 있습니다.

호출자가 요청과 함께 유효한 XSTS 토큰을 제출하는 경우 모든 플랫폼의 클라이언트에서 순위표와 사용자 통계를 모두 읽을 수 있습니다. 쓰기는 플레이어 데이터 시스템에서 지원하는 클라이언트로 제한됩니다.
타이틀 개발자는 파트너 센터에서 통계를 공개 또는 제한으로 표시할 수 있습니다. 순위표는 공개된 통계입니다. 사용자가 샌드박스에 대한 권한이 있는 한 공개된 통계는 Smartglass뿐만 아니라 iOS, Android, Windows, Windows Phone 및 웹 애플리케이션을 통해 액세스할 수 있습니다. 샌드박스에 대한 사용자 권한 부여는 파트너 센터를 통해 관리됩니다.

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

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

// else accept request.

리소스에 대한 개인 정보 설정의 영향

순위표 데이터를 읽을 때 개인 정보 보호 검사가 수행되지 않습니다.

필수 요청 헤더

헤더	설명
Authorization	문자열입니다. HTTP 인증을 위한 인증 자격 증명입니다. 예제 값: XBL3.0 x=<userhash>;<token>
X-RequestedServiceVersion	문자열입니다. 이 요청을 연결해야 하는 Xbox LIVE 서비스의 이름/번호를 작성합니다. 헤더의 유효성과 권한 부여 토큰의 클레임 등을 확인한 이후에만 요청이 해당 서비스로 라우팅됩니다. 기본 값은 1입니다.
수락	문자열입니다. 허용 가능한 콘텐츠-유형입니다. 예제 값: application/json

선택적 요청 헤더

헤더	설명
If-None-Match	문자열입니다. 클라이언트가 캐싱을 지원하는 경우 사용되는 엔터티 태그입니다. 예제 값: "686897696a7c876b7e"

HTTP 상태 코드

서비스는 이 리소스에서 이 메서드를 통해 수행한 요청에 대한 응답으로 이 섹션의 상태 코드 중 하나를 반환합니다. Xbox Live 서비스에서 사용되는 표준 HTTP 상태 코드의 전체 목록은 표준 HTTP 상태 코드를 참조하세요.

코드	이유 구문	설명
200	OK	세션이 성공적으로 검색되었습니다.
304	Not Modified	마지막으로 요청한 이후로 리소스가 수정되지 않았습니다.
400	Bad Request	서비스가 형식이 잘못된 요청을 이해할 수 없습니다. 일반적으로 잘못된 매개 변수입니다.
401	Unauthorized	요청에 대해 사용자 인증이 필요합니다.
403	Forbidden	사용자 또는 서비스에 대해 요청이 허용되지 않습니다.
404	Not Found	지정된 리소스를 찾을 수 없습니다.
406	Not Acceptable	리소스 버전이 지원되지 않습니다.
408	Request Timeout	리소스 버전은 지원되지 않습니다. MVC 계층에서 거부되어야 합니다.

응답 헤더

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

응답 본문

응답 멤버

pagingInfo	pagingInfo	section	선택 사항. maxItems가 요청에 지정된 경우에만 표시됩니다.
continuationToken	64비트 부호 없는 정수	필수. 원하는 경우 skipItems 쿼리 매개 변수에 다시 입력하여 해당 URI의 결과 페이지를 가져올 값을 지정합니다. pagingInfo가 반환되지 않는 경우 획득할 데이터의 다음 페이지가 없습니다.
totalCount	64비트 부호 없는 정수	필수. 순위표의 총 항목 수입니다. 예제 값: 1234567890

leaderboardInfo	leaderboardInfo	section
displayName	문자열	사용되지 않습니다.
totalCount	문자열(부호 없는 64비트 정수)	필수. 순위표의 총 항목 수입니다. 예제 값: 1234567890
columns	array	필수. 순위표의 열입니다.
displayName	문자열	필수. 순위표의 열에 해당합니다.
statName	문자열	필수. 순위표의 열에 해당합니다.
type	문자열	필수. 순위표의 열에 해당합니다.

userList	userList	section
gamertag	문자열	필수. 순위표 항목의 사용자에 해당합니다.
xuid	64비트 부호 없는 정수	필수. 순위표 항목의 사용자에 해당합니다.
percentile	문자열	필수. 순위표 항목의 사용자에 해당합니다.
rank	문자열	필수. 순위표 항목의 사용자에 해당합니다.
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