GET(/users/xuid({xuid})/scids/{scid}/stats/{statname)/people/{all|favorite})
현재 사용자의 알려진 모든 연락처에 대한 통계 값(점수)을 순위로 나타내거나 해당 사용자가 즐겨찾기로 지정한 연락처만 순위로 나타내는 방식으로 소셜 순위표를 반환합니다.
이 URI의 도메인은 leaderboards.xboxlive.com입니다.
- 비고
- URI 매개 변수
- 쿼리 문자열 매개 변수
- Authorization
- 필수 요청 헤더
- 선택적 요청 헤더
- 요청 본문
- HTTP 상태 코드
- 필수 응답 헤더
- 선택적 응답 헤더
- 응답 본문
설명
순위표 API는 모두 읽기 전용이므로 HTTPS를 통해 GET 동사만 지원합니다. 플레이어 데이터 시스템을 통해 작성된 개별 사용자 통계의 인덱싱된 파생 플레이어 통계의 순위가 지정되고 정렬된 "페이지"를 반영합니다. 전체 순위표 인덱스는 대규모일 수 있으며 호출자는 전체를 볼 필요가 없으므로 이 URI는 호출자가 해당 순위표에 대해 보고 싶은 유형을 특정할 수 있는 여러 쿼리 문자열 인수를 지원합니다.
GET 작업은 리소스를 수정하지 않으므로 한 번 또는 여러 번 실행하는 경우 동일한 결과가 생성됩니다.
URI 매개 변수
| 매개 변수 | 형식 | 설명 |
|---|---|---|
| xuid | 문자열 | 사용자 식별자입니다. |
| scid | 문자열 | 액세스되는 리소스를 포함하는 서비스 구성 식별자입니다. |
| statname | 문자열 | 액세스하는 사용자 통계 리소스의 고유 식별자입니다. |
| 모두 또는 즐겨찾기 | 열거형 | 현재 사용자의 알려진 모든 연락처에 대한 통계 값(점수)을 순위로 나타낼지 또는 해당 사용자가 즐겨찾기로 지정한 연락처만 순위로 나타낼지 여부입니다. |
쿼리 문자열 매개 변수
| 매개 변수 | 형식 | 설명 |
|---|---|---|
| maxItems | 32비트 부호 없는 정수 | 결과 페이지에서 반환할 순위표 레코드의 최대 수입니다. 지정하지 않으면 기본 숫자가 반환됩니다(10). maxItems의 최대 값은 여전히 정의되어 있지 않지만 대규모 데이터 집합은 방지하고자 하므로 이 값은 튜너 UI가 호출당 처리할 수 있는 최대 집합을 대상으로 해야 합니다. |
| skipToRank | 32비트 부호 없는 정수 | 지정된 순위표 순위로 시작하는 결과 페이지를 반환합니다. 나머지 결과는 순위별로 정렬됩니다. 이 쿼리 문자열은 결과의 "다음 페이지"를 가져오기 위해 후속 쿼리로 다시 공급될 수 있는 연속 토큰을 반환할 수 있습니다. |
| skipToUser | 문자열 | 해당 사용자의 순위 또는 점수와 상관없이 지정된 gamer xuid와 관련하여 순위표 결과 페이지를 반환합니다. 해당 페이지는 미리 정의된 보기 페이지의 마지막 위치에서 지정된 사용자와 함께 백분위 수 순위에 따라 정렬되거나 통계 순위표 보기의 중간에 정렬됩니다. 이 유형의 쿼리에는 continuationToken이 제공되지 않습니다. |
| continuationToken | 문자열 | 이전 호출에서 continuationToken이 반환된 경우 호출자는 쿼리 문자열에서 해당 토큰을 "있는 그대로" 다시 전달하여 결과의 다음 페이지를 가져올 수 있습니다. |
| sort | 문자열 | 플레이어 목록을 낮은 값에서 높은 값 순서("오름차순") 또는 높은 값에서 낮은 값 순서("내림차순")로 순위를 매길 것인지 여부를 지정합니다. 이는 선택적 매개 변수이며, 기본값은 내림차순입니다. |
권한 부여
Xuid 권한이 필요합니다.
콘텐츠 격리 및 액세스 제어 시나리오에 대해 권한 부여 논리가 구현됩니다.
호출자가 요청과 함께 유효한 XSTS 토큰을 제출하는 경우 모든 플랫폼의 클라이언트에서 순위표와 사용자 통계를 모두 읽을 수 있습니다. 쓰기는 플레이어 데이터 시스템에서 지원하는 클라이언트로 제한됩니다.
타이틀 개발자는 파트너 센터에서 통계를 공개 또는 제한으로 표시할 수 있습니다. 순위표는 공개된 통계입니다. 사용자가 샌드박스에 대한 권한이 있는 한 공개된 통계는 Smartglass뿐만 아니라 iOS, Android, Windows, Windows Phone 및 웹 애플리케이션을 통해 액세스할 수 있습니다. 샌드박스에 대한 사용자 권한 부여는 파트너 센터를 통해 관리됩니다.
필수 요청 헤더
| 헤더 | 설명 |
|---|---|
| Authorization | 문자열입니다. HTTP 인증을 위한 인증 자격 증명입니다. 예제 값: "XBL3.0 x=<userhash>;<token>". |
| 콘텐츠-종류 | 문자열입니다. 요청 본문의 MIME 유형. 예제 값: "application/json". |
| X-RequestedServiceVersion | 이 요청을 연결해야 하는 Xbox LIVE 서비스의 이름/번호를 작성합니다. 헤더의 유효성과 권한 부여 토큰의 클레임 등을 확인한 이후에만 요청이 해당 서비스로 라우팅됩니다. 기본값: 1. |
| 수락 | 문자열입니다. 허용 가능한 Content-Type 값. 예제 값: "application/json". |
선택적 요청 헤더
| 헤더 | 설명 |
|---|---|
| If-None-Match | 문자열입니다. 엔터티 태그 - 클라이언트가 캐싱을 지원하는 경우 사용됩니다. 예제 값: "686897696a7c876b7e". |
요청 본문
적절한 표시를 위해 반송되는 데이터를 호출자가 최대한 이해할 수 있도록 각 사용자의 각 통계 값은 표시되어야 하는 형식의 문자열로 반환되며 요청의 accept-language 헤더에 지정된 로캘과 일치하도록 형식이 지정됩니다. 해당 순위표의 statname에 대해서도 지역화된 "표시 이름"이 반환됩니다.
필수 멤버
| 멤버 | 유형 | 설명 |
|---|---|---|
| pagingInfo | section | 선택 사항. 페이지의 마지막 항목 순위가 totalItems보다 낮을 때 반환됩니다. 이 섹션은 skipToUser가 요청에 지정된 경우에도 반환되지 않습니다. |
| continuationToken | 문자열 | 필수. 원하는 경우 "continuationToken" 쿼리 매개 변수에 다시 입력하여 해당 URI의 결과 페이지를 가져올 값을 지정합니다. pagingInfo가 반환되지 않는 경우 획득할 데이터의 "다음 페이지"가 없습니다. |
| totalItems | 64비트 부호 없는 정수 | 필수. 순위표의 총 항목 수입니다. |
| leaderboardInfo | section | 필수. 항상 반환됩니다. 요청된 순위표에 대한 메타데이터가 포함되어 있습니다. |
| displayName | 문자열 | 필수. 사전 정의된 순위표의 지역화된 표시 이름입니다. 예제 값: "Total flags captured". |
| totalCount | 문자열 | 필수. 순위표의 총 항목 수입니다. |
| columns | array | 필수. |
| displayName | 문자열 | 필수. 순위표의 열에 해당합니다. |
| statName | 문자열 | 필수. 순위표의 열에 해당합니다. |
| type | 문자열 | 필수. 순위표의 열에 해당합니다. |
| userList | section | 필수. 항상 반환됩니다. 요청된 순위표의 실제 사용자 점수를 포함합니다. |
| gamertag | 문자열 | 필수. 순위표 항목의 사용자에 해당합니다. |
| xuid | 32비트 부호 있는 정수 | 필수. 순위표 항목의 사용자에 해당합니다. |
| percentile | 문자열 | 필수. 순위표 항목의 사용자에 해당합니다. |
| rank | 문자열 | 필수. 순위표 항목의 사용자에 해당합니다. |
| values | array | 필수. 쉼표로 구분된 각 값은 순위표의 열에 해당합니다. |
HTTP 상태 코드
서비스는 이 리소스에서 이 메서드를 통해 수행한 요청에 대한 응답으로 이 섹션의 상태 코드 중 하나를 반환합니다. Xbox Live 서비스에서 사용되는 표준 HTTP 상태 코드의 전체 목록은 표준 HTTP 상태 코드를 참조하세요.
| 코드 | 이유 구문 | 설명 |
|---|---|---|
| 200 | OK | 세션이 성공적으로 검색되었습니다. |
| 304 | Not Modified | |
| 400 | Bad Request | 서비스가 형식이 잘못된 요청을 이해할 수 없습니다. 일반적으로 잘못된 매개 변수입니다. |
| 401 | Unauthorized | 요청에 대해 사용자 인증이 필요합니다. |
| 403 | Forbidden | 사용자 또는 서비스에 대해 요청이 허용되지 않습니다. |
| 404 | Not Found | 지정된 리소스를 찾을 수 없습니다. |
| 406 | Not Acceptable | 리소스 버전은 지원되지 않습니다. MVC 계층에서 거부되어야 합니다. |
| 408 | Request Timeout | 서비스가 형식이 잘못된 요청을 이해할 수 없습니다. 일반적으로 잘못된 매개 변수입니다. |
필수 응답 헤더
| 헤더 | 형식 | 설명 |
|---|---|---|
| 콘텐츠-종류 | 문자열 | 응답 본문의 mime 유형입니다. 예제 값: "application/json". |
| Content-Length | 문자열 | 응답에서 전송되는 바이트 수입니다. 예제 값: "232". |
선택적 응답 헤더
| 헤더 | 형식 | 설명 |
|---|---|---|
| ETag | 문자열 | 캐시 최적화에 사용됩니다. 예제 값: "686897696a7c876b7e". |
응답 본문
소셜 순위표에 대한 요청, 페이징 없음:
https://leaderboards.xboxlive.com/users/xuid(2533274916402282)/scids/c1ba92a9-0000-0000-0000-000000000000/stats/EnemyDefeats/people/all?sort=descending
샘플 응답
{
"pagingInfo": null,
"leaderboardInfo": {
"displayName": "Kills",
"totalCount": 3,
"columns": [
{
"displayName": "Kills",
"statName": "enemydefeats",
"type": "integer"
}
]
},
"userList": [
{
"gamertag":"xxxSniper39",
"xuid":"1234567890123555",
"percentile":1.0,
"rank":1,
"values": [
"47"
]
},
{
"gamertag":"WarriorSaint",
"xuid":"2533274916402282",
"percentile":0.66,
"rank":2,
"values": [
"42"
]
},
{
"gamertag":"WhockaWhocka",
"xuid":"1234567890123666",
"percentile":0.33,
"rank":3,
"values": [
"12"
]
}
]
}
참고 항목
상위 항목
/users/xuid({xuid})/scids/{scid}/stats/{statname)/people/{all|favorite}