> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET (/users/xuid({xuid})/scids/{scid}/stats/{statname)/people/{all|favorite})

> GET (/users/xuid(\{xuid})/scids/\{scid}/stats/\{statname)/people/\{all|favorite})

# GET (/users/xuid(\{xuid})/scids/\{scid}/stats/\{statname)/people/\{all|favorite})

현재 사용자의 알려진 모든 연락처 또는 해당 사용자가 즐겨찾는 사람으로 지정한 연락처만을 대상으로 통계 값(점수)의 순위를 매겨 소셜 리더보드를 반환합니다.
이 URI의 도메인은 `leaderboards.xboxlive.com`입니다.

* [설명](#ID4EV)
* [URI 매개변수](#ID4EAB)
* [쿼리 문자열 매개변수](#ID4ELB)
* [권한 부여](#ID4EQD)
* [필수 요청 헤더](#ID4EGE)
* [선택적 요청 헤더](#ID4EXF)
* [요청 본문](#ID4ETG)
* [HTTP 상태 코드](#ID4ECEAC)
* [필수 응답 헤더](#ID4E1HAC)
* [선택적 응답 헤더](#ID4EDJAC)
* [응답 본문](#ID4EDKAC)

## 설명

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

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

## URI 매개변수

| 매개변수 | 형식 | 설명 |
| - | - | - |
| xuid | string | 사용자의 식별자입니다. |
| scid | string | 액세스하려는 리소스를 포함하는 서비스 구성의 식별자입니다. |
| statname | string | 액세스하려는 사용자 통계 리소스의 고유 식별자입니다. |
| all or favorite | enumeration | 현재 사용자의 알려진 모든 연락처의 통계 값(점수) 순위를 매길지, 아니면 해당 사용자가 즐겨찾는 사람으로 지정한 연락처만의 순위를 매길지 여부입니다. |

## 쿼리 문자열 매개변수

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

## 권한 부여

Xuid 권한 부여가 필요합니다.

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

리더보드와 사용자 통계는 호출자가 요청과 함께 유효한 XSTS 토큰을 제출하는 한 모든 플랫폼의 클라이언트에서 읽을 수 있습니다. 쓰기는 (당연히) Player Data 시스템에서 지원하는 클라이언트로 제한됩니다.

타이틀 개발자는 Partner Center를 통해 통계를 공개 또는 제한으로 표시할 수 있습니다. 리더보드는 공개 통계입니다. 공개 통계는 사용자가 샌드박스에 대해 권한이 부여되어 있는 한 Smartglass는 물론 iOS, Android, Windows, Windows Phone 및 웹 애플리케이션에서 액세스할 수 있습니다. 사용자의 샌드박스에 대한 권한 부여는 Partner Center를 통해 관리됩니다.

## 필수 요청 헤더

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

## 선택적 요청 헤더

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

## 요청 본문

호출자가 반환받는 데이터를 올바르게 표시할 수 있도록, 각 사용자의 각 통계 값은 표시되어야 하는 형식의 문자열로 반환되며 요청의 accept-language 헤더에 지정된 로캘에 맞게 서식이 지정됩니다. 해당 리더보드의 statname에 대한 지역화된 "표시 이름"도 반환됩니다.

### 필수 멤버

| 멤버 | 형식 | 설명 |
| - | - | - |
| **pagingInfo** | 섹션 | 선택 사항. 페이지의 마지막 항목 순위가 totalItems보다 낮을 때 반환됩니다. 요청에 skipToUser가 지정된 경우에도 이 섹션은 반환되지 않습니다. |
| continuationToken | string | 필수. 원하는 경우 해당 URI에 대한 다음 결과 페이지를 가져오기 위해 "continuationToken" 쿼리 매개변수에 다시 전달할 값을 지정합니다. pagingInfo가 반환되지 않은 경우 얻을 수 있는 데이터의 "다음 페이지"가 없습니다. |
| totalItems | 64비트 부호 없는 정수 | 필수. 리더보드의 총 항목 수입니다. |
| **leaderboardInfo** | 섹션 | 필수. 항상 반환됩니다. 요청한 리더보드에 대한 메타데이터를 포함합니다. |
| displayName | string | 필수. 사전 정의된 리더보드의 지역화된 표시 이름입니다. 예제 값: "Total flags captured". |
| totalCount | string | 필수. 리더보드의 총 항목 수입니다. |
| columns | array | 필수. |
| displayName | string | 필수. 리더보드의 열에 해당합니다. |
| statName | string | 필수. 리더보드의 열에 해당합니다. |
| type | string | 필수. 리더보드의 열에 해당합니다. |
| **userList** | 섹션 | 필수. 항상 반환됩니다. 요청한 리더보드에 대한 실제 사용자 점수를 포함합니다. |
| gamertag | string | 필수. 리더보드 항목의 사용자에 해당합니다. |
| xuid | 32비트 부호 있는 정수 | 필수. 리더보드 항목의 사용자에 해당합니다. |
| percentile | string | 필수. 리더보드 항목의 사용자에 해당합니다. |
| rank | string | 필수. 리더보드 항목의 사용자에 해당합니다. |
| values | array | 필수. 쉼표로 구분된 각 값은 리더보드의 열에 해당합니다. |

## HTTP 상태 코드

이 리소스에서 이 메서드로 이루어진 요청에 대한 응답으로 서비스는 이 섹션의 상태 코드 중 하나를 반환합니다. XBOX Live Services에서 사용되는 표준 HTTP 상태 코드의 전체 목록은 [표준 HTTP 상태 코드](https://docs.xbox.com/ko/reference/live/rest/additional/httpstatuscodes.md)를 참조하세요.

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

## 필수 응답 헤더

| 헤더 | 형식 | 설명 |
| - | - | - |
| Content-Type | string | 응답 본문의 MIME 형식입니다. 예제 값: "application/json". |
| Content-Length | string | 응답에서 전송되는 바이트 수입니다. 예제 값: "232". |

## 선택적 응답 헤더

| 헤더 | 형식 | 설명 |
| - | - | - |
| ETag | string | 캐시 최적화에 사용됩니다. 예제 값: "686897696a7c876b7e". |

## 응답 본문

페이징이 없는 소셜 리더보드 요청:

`https://leaderboards.xboxlive.com/users/xuid(2533274916402282)/scids/c1ba92a9-0000-0000-0000-000000000000/stats/EnemyDefeats/people/all?sort=descending`

### 샘플 응답

```json theme={null}
{
    "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}](https://docs.xbox.com/ko/reference/live/rest/uri/leaderboard/uri-usersxuidscidstatnamepeople.md)


## Related topics

- [/users/xuid({xuid})/scids/{scid}/stats/{statname)/people/{all|favorite}](https://docs.xbox.com/ko/reference/live/rest/uri/leaderboard/uri-usersxuidscidstatnamepeople.md)
- [GET (/users/xuid({xuid})/scids/{scid}/stats)](https://docs.xbox.com/ko/reference/live/rest/uri/userstats/uri-usersxuidscidsscidstatsget.md)
- [GET (/users/xuid({xuid})/scids/{scid}/stats?include=valuemetadata)](https://docs.xbox.com/ko/reference/live/rest/uri/userstats/uri-usersxuidscidsscidstatsgetvaluemetadata.md)
- [/users/xuid({xuid})/scids/{scid}/stats](https://docs.xbox.com/ko/reference/live/rest/uri/userstats/uri-usersxuidscidsscidstats.md)
- [GET (/users/xuid({xuid})/achievements/{scid}/{achievementid})](https://docs.xbox.com/ko/reference/live/rest/uri/achievements/uri-usersxuidachievementsscidachievementidget.md)
