> ## 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 (/scids/{scid}/leaderboards/{leaderboardname}?include=valuemetadata)

> GET (/scids/{scid}/leaderboards/{leaderboardname}?include=valuemetadata)

# GET (/scids/{scid}/leaderboards/{leaderboardname}?include=valuemetadata)

Obtém um placar de líderes global predefinido junto com todos os metadados associados aos valores do placar de líderes.

O domínio desses URIs é `leaderboards.xboxlive.com`.

* [Comentários](#ID4EY)
* [Parâmetros de URI](#ID4EHB)
* [Parâmetros da cadeia de caracteres de consulta](#ID4ESB)
* [Autorização](#ID4EVD)
* [Efeito das configurações de privacidade no recurso](#ID4EQE)
* [Cabeçalhos de solicitação obrigatórios](#ID4EZE)
* [Cabeçalhos de solicitação opcionais](#ID4EOG)
* [Códigos de status HTTP](#ID4EOH)
* [Cabeçalhos de resposta](#ID4EFDAC)
* [Corpo da resposta](#ID4ECFAC)

## Comentários

O parâmetro de consulta ?include=valuemetadata permite que a resposta inclua todos os metadados associados aos valores do placar de líderes. Os metadados de valor contêm dados especificados pelo cliente associados ao valor, como o modelo e a cor de um carro usado para alcançar o melhor tempo em uma pista de corrida.

Os metadados de valor são definidos na estatística de usuário na qual o placar de líderes se baseia, não no próprio placar de líderes.

As APIs de placar de líderes são todas somente leitura e, portanto, só oferecem suporte ao verbo GET. Elas refletem "páginas" classificadas e ordenadas de estatísticas de jogadores indexadas, derivadas de estatísticas individuais de usuários que foram gravadas por meio do sistema Player Data. Índices completos de placares de líderes podem ser bem grandes, e os chamadores nunca pedirão para ver um em sua totalidade; portanto, este URI oferece suporte a vários argumentos de cadeia de caracteres de consulta que permitem que um chamador especifique que tipo de exibição deseja ver desse placar de líderes.

As operações GET não modificam nenhum recurso; portanto, isso produzirá os mesmos resultados se executado uma vez ou várias vezes.

## Parâmetros de URI

| Parâmetro | Tipo | Descrição |
| - | - | - |
| scid | GUID | Identificador da configuração de serviço que contém o recurso que está sendo acessado. |
| leaderboardname | string | Identificador exclusivo do recurso de placar de líderes predefinido que está sendo acessado. |

## Parâmetros da cadeia de caracteres de consulta

\| Parâmetro| Tipo| Descrição|
\| --- | --- | --- | --- | --- | --- |
\| include=valuemetadata| string| Indica que a resposta inclui todos os metadados de valor associados aos valores do placar de líderes.|
\| maxItems| inteiro sem sinal de 32 bits| Número máximo de registros do placar de líderes a serem retornados em uma página de resultados. Se não for especificado, um número padrão será retornado (10). O valor máximo de maxItems ainda não está definido, mas queremos evitar grandes conjuntos de dados; portanto, esse valor provavelmente deve visar o maior conjunto que uma interface do usuário de ajuste possa manipular por chamada.|
\| skipToRank| inteiro sem sinal de 32 bits| Retorna uma página de resultados começando pela classificação especificada no placar de líderes. O restante dos resultados estará ordenado por classificação. Essa cadeia de caracteres de consulta pode retornar um token de continuação que pode ser realimentado em uma consulta subsequente para obter "a próxima página" de resultados.|
\| skipToUser| string| Retorna uma página de resultados do placar de líderes em torno do xuid de jogador especificado, independentemente da classificação ou da pontuação desse usuário. A página será ordenada por classificação de percentil, com o usuário especificado na última posição da página para exibições predefinidas ou no meio para exibições de placar de líderes de estatísticas. Nenhum continuationToken é fornecido para esse tipo de consulta.|
\| continuationToken| string| Se uma chamada anterior retornou um continuationToken, o chamador poderá passar esse token "no estado em que se encontra" em uma cadeia de caracteres de consulta para obter a próxima página de resultados.|

## Autorização

Há uma lógica de autorização implementada para cenários de isolamento de conteúdo e controle de acesso.

* Tanto os placares de líderes quanto as estatísticas de usuário podem ser lidos de clientes em qualquer plataforma, desde que o chamador envie um token XSTS válido com a solicitação. As gravações, obviamente, são limitadas aos clientes compatíveis com o sistema Player Data.
* Os desenvolvedores de títulos podem marcar estatísticas como abertas ou restritas com o Partner Center. Os placares de líderes são estatísticas abertas. As estatísticas abertas podem ser acessadas pelo Smartglass, bem como por aplicativos iOS, Android, Windows, Windows Phone e Web, desde que o usuário esteja autorizado na área restrita. A autorização do usuário em uma área restrita é gerenciada por meio do Partner Center.

O pseudocódigo da verificação é semelhante a este:

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

// else accept request.
         
```

## Efeito das configurações de privacidade no recurso

Nenhuma verificação de privacidade é realizada ao ler dados do placar de líderes.

## Cabeçalhos de solicitação obrigatórios

\| Cabeçalho| Descrição|
\| --- | --- | --- | --- | --- | --- | --- | --- |
\| Authorization| String. Credenciais de autenticação para autenticação HTTP. Valor de exemplo: **XBL3.0 x=\<userhash>;\<token>**|
\| X-Xbl-Contract-Version| String. Indica qual versão da API usar. Esse valor deve ser definido como "3" para incluir metadados de valor na resposta.|
\| X-RequestedServiceVersion| String. Nome/número de build do serviço XBOX LIVE para o qual esta solicitação deve ser direcionada. A solicitação só será roteada para esse serviço após a verificação da validade do cabeçalho, das declarações no token de autenticação etc. Valor padrão: 1.|
\| Accept| String. Content-Types aceitáveis. Valor de exemplo: **application/json**|

## Cabeçalhos de solicitação opcionais

| Cabeçalho | Descrição |
| - | - |
| If-None-Match | String. Marca de entidade, usada se o cliente oferecer suporte a cache. Valor de exemplo: **"686897696a7c876b7e"** |

## Códigos de status HTTP

O serviço retorna um dos códigos de status desta seção em resposta a uma solicitação feita com este método neste recurso. Para obter uma lista completa dos códigos de status HTTP padrão usados com os XBOX Live Services, confira [Códigos de status HTTP padrão](https://docs.xbox.com/pt-BR/reference/live/rest/additional/httpstatuscodes.md).

\| Código| Frase de motivo| Descrição|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| 200| OK| A sessão foi recuperada com êxito.|
\| 304| Not Modified| O recurso não foi modificado desde a última solicitação.|
\| 400| Bad Request| O serviço não conseguiu entender a solicitação malformada. Normalmente, um parâmetro inválido.|
\| 401| Unauthorized| A solicitação requer autenticação do usuário.|
\| 403| Forbidden| A solicitação não é permitida para o usuário ou serviço.|
\| 404| Not Found| O recurso especificado não foi encontrado.|
\| 406| Not Acceptable| A versão do recurso não tem suporte.|
\| 408| Request Timeout| A versão do recurso não tem suporte; deve ser rejeitada pela camada MVC.|

## Cabeçalhos de resposta

\| Cabeçalho| Tipo| Descrição|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| Content-Type| string| Obrigatório. O tipo MIME do corpo da resposta. Exemplo: **application/json**.|
\| Content-Length| string| Obrigatório. O número de bytes que estão sendo enviados na resposta. Exemplo: **232**.|
\| ETag| string| Opcional. Usado para otimização de cache. Exemplo: **686897696a7c876b7e**.|

## Corpo da resposta

### Membros da resposta

pagingInfo | pagingInfo| seção| Opcional. Presente somente quando maxItems é especificado na solicitação.|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| continuationToken| inteiro sem sinal de 64 bits| Obrigatório. Especifica qual valor realimentar no parâmetro de consulta **skipItems** para obter a próxima página de resultados desse URI, se desejado. Se nenhum **pagingInfo** for retornado, não haverá próxima página de dados a ser obtida.|
\| totalItems| inteiro sem sinal de 64 bits| Obrigatório. Número total de entradas no placar de líderes. Valor de exemplo: 1234567890|

leaderboardInfo | leaderboardInfo| seção| Obrigatório. Sempre retornado. Contém os metadados sobre o placar de líderes solicitado.|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| displayName| string| Não usado.|
\| totalCount| string (inteiro sem sinal de 64 bits)| Obrigatório. Número total de entradas no placar de líderes. Valor de exemplo: 1234567890|
\| columnDefinition| objeto JSON| Obrigatório. Descreve a coluna no placar de líderes.|
\| columnDefinition.displayName| string| Obrigatório. Um nome descritivo da coluna no placar de líderes.|
\| columnDefinition.statName| string| Obrigatório. O nome da estatística de usuário na qual o placar de líderes se baseia.|
\| columnDefinition.type| string| Obrigatório. O tipo de dados da estatística de usuário na coluna.|

userList | userList| seção| Obrigatório. Sempre retornado. Contém as pontuações reais dos usuários para o placar de líderes solicitado.|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| gamertag| string| Obrigatório. O gamertag do usuário na entrada do placar de líderes.|
\| xuid| inteiro sem sinal de 64 bits| Obrigatório. A ID de usuário do XBOX do usuário na entrada do placar de líderes.|
\| percentile| string| Obrigatório. A classificação de percentil do usuário no placar de líderes.|
\| rank| string| Obrigatório. A classificação numérica do usuário no placar de líderes.|
\| value| string| Obrigatório. O valor do usuário para a estatística na qual o placar de líderes se baseia.|
\| valueMetadata| string| Obrigatório. Uma cadeia de caracteres de pares de cadeias de caracteres separados por vírgula, no formato ""name" : "value", ..."

Se não houver metadados, esse valor será uma cadeia de caracteres vazia.|

### Exemplo de resposta

O URI de solicitação a seguir mostra como pular para uma classificação em um placar de líderes global.

```cpp theme={null}
https://leaderboards.xboxlive.com/scids/0FA0D955-56CF-49DE-8668-05D82E6D45C4/leaderboards/TotalFlagsCaptured?include=valuemetadata&maxItems=3&skipToRank=15000
         
```

Para retornar metadados de valor, o cabeçalho a seguir também deve ser especificado.

```cpp theme={null}
X-Xbl-Contract-Version : 3
          
```

O URI acima retorna a seguinte resposta JSON.

```cpp theme={null}
{
    "pagingInfo": {
        "continuationToken": "15003",
        "totalItems": 23437
    },
    "leaderboardInfo": {
        "displayName": "Total flags captured",
        "totalCount": 23437,
        "columnDefinition" : 
            {
                "displayName": "Flags Captured",
                "statName": "flagscaptured",
                "type": "Integer"
            }
    },
    "userList": [
        {
            "gamertag": "WarriorSaint",
            "xuid": "1234567890123444",
            "percentile": 0.64,
            "rank": 15000,
            "value": "1002",
            "valuemetadata" : "{\"color\" : \"silver\",\"weight\" : 2000, \"israining\" : false}"
        },
        {
            "gamertag": "xxxSniper39",
            "xuid": "1234567890123555",
            "percentile": 0.64,
            "rank": 15001,
            "value": "993",
            "valuemetadata" : "{\"color\" : \"silver\",\"weight\" : 2020, \"israining\" : true}"
 
        },
        {
            "gamertag": "WhockaWhocka",
            "xuid": "1234567890123666",
            "percentile": 0.64,
            "rank": 15002,
            "value": "700",
            "valuemetadata" : "{\"color\" : \"red\",\"weight\" : 300, \"israining\" : false}"
        }
    ]
}
         
```

## Confira também

##### Pai

[/scids/{scid}/leaderboards/{leaderboardname}](https://docs.xbox.com/pt-BR/reference/live/rest/uri/leaderboard/uri-scidsscidleaderboardsleaderboardname.md)


## Related topics

- [/scids/{scid}/leaderboards/{leaderboardname}](https://docs.xbox.com/pt-BR/reference/live/rest/uri/leaderboard/uri-scidsscidleaderboardsleaderboardname.md)
- [GET (/scids/{scid}/leaderboards/{leaderboardname})](https://docs.xbox.com/pt-BR/reference/live/rest/uri/leaderboard/uri-scidsscidleaderboardsleaderboardnameget.md)
- [Visão geral dos leaderboards baseados em eventos](https://docs.xbox.com/pt-BR/services/xbox-services/player-data/stats-leaderboards/event-based/live-leaderboards-eb-overview.md)
- [/global/scids/{scid}](https://docs.xbox.com/pt-BR/reference/live/rest/uri/storage/uri-globalscidsscid.md)
- [GET (/global/scids/{scid})](https://docs.xbox.com/pt-BR/reference/live/rest/uri/storage/uri-globalscidsscid-get.md)