Skip to main content

​
POST (/users/xuid(xuid)/lists/PINS/)

Insere itens na lista no índice com base no parâmetro da cadeia de consulta insertIndex. O domínio para esses URIs é eplists.xboxlive.com.

​
Comentários

Esta chamada inserirá itens na lista no índice com base no parâmetro da cadeia de consulta insertIndex (o padrão é 0, ou o início da lista). Todos os itens no corpo da solicitação serão inseridos nesse ponto da lista. Se insertIndex for maior que o número de itens na lista existente, os novos itens serão inseridos no fim. Os itens a serem inseridos devem ter os campos obrigatórios indicados na especificação funcional; caso contrário, um HTTP 400 será retornado. Da mesma forma, se o resultado da inserção exceder o tamanho máximo da lista (definido por tipo de lista), um HTTP 400 será retornado e nada será inserido. Se o item não for inserido no início ou no fim da lista, o cabeçalho If-Match:versionNumber deverá ser incluído na solicitação. O cabeçalho é opcional se a inserção for no início ou no fim. Se estiver presente, o cabeçalho será validado independentemente do local de inserção. No cabeçalho, VersionNumber é o número da versão atual da lista. Se ele não for incluído e for obrigatório, ou não corresponder ao número da versão atual da lista, um código de status HTTP 412 (precondition failed) será retornado, e o corpo da resposta conterá os metadados mais recentes da lista, que incluem o número da versão atual. Isso serve para evitar que atualizações de clientes diferentes se sobreponham umas às outras. Observe que esta chamada não é idempotente; chamadas repetidas com os mesmos dados podem resultar em várias inserções. No entanto, como nenhuma lista dá suporte a duplicatas atualmente, chamadas repetidas provavelmente resultarão no retorno de códigos HTTP 400.

​
Parâmetros de URI

​
Parâmetros da cadeia de consulta

| Parâmetro| Tipo| Descrição| | --- | --- | --- | --- | --- | --- | | insertIndex| cadeia de caracteres| Opcional. Define onde inserir itens. Valores com suporte: 0, inteiros positivos e “end”. Qualquer valor de índice maior que o número de itens da lista adicionará o novo item no final da lista e não inserirá espaço “em branco” na lista. Valor padrão: 0.|

​
Autorização

Esta chamada espera um token SAML do XSTS no cabeçalho Authorization. Uma declaração Xuid deve existir nesse token SAML para identificar o chamador. Esse valor é usado para determinar se o chamador tem direitos de acesso aos dados da lista em questão. A própria lista também será identificada pelo Xuid e será incluída no URI da lista. Com isso, poderemos no futuro dar suporte ao acesso compartilhado a listas, mas esse não é um recurso disponível no momento. Atualmente, todas as listas que um usuário acessa serão dele mesmo e não há acesso compartilhado. Portanto, o Xuid no URI deve corresponder ao Xuid no token de declarações SAML.
Observação:
No momento, há suporte para tokens do XBL Auth 2.0 e 3.0.

​
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, consulte Códigos de status HTTP padrão. | Código| Frase de motivo| Descrição| | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 200| OK| A solicitação foi concluída com êxito. O corpo da resposta deve conter o recurso solicitado (para um GET). As solicitações POST e PUT receberão metadados atualizados da lista (versão da lista, contagem etc.).| | 201| Created| Uma nova lista foi criada. Isso é retornado na inserção inicial em uma lista. A resposta inclui metadados atualizados sobre a lista, e o cabeçalho location contém o URI da lista.| | 304| Not Modified| Retornado em GETs. Indica que o cliente tem a versão mais recente da lista. O serviço compara o valor no cabeçalho If-Match com a versão da lista. Se forem iguais, um 304 será retornado sem dados.| | 400| Bad Request| A solicitação estava malformada. Pode ser um valor ou tipo inválido para um parâmetro de URI ou da cadeia de consulta. Também pode ser resultado da ausência de um parâmetro ou valor de dados obrigatório, ou de a solicitação indicar uma versão ausente ou inválida da API. Consulte o cabeçalho X-XBL-Contract-Version.| | 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 chamador não tem acesso ao recurso. Isso indica que essa lista não foi criada.| | 412| Precondition Failed| Indica que a versão da lista foi alterada e uma solicitação de modificação falhou. Uma solicitação de modificação é uma inserção, atualização ou remoção. O serviço verifica o cabeçalho If-Match para obter a versão da lista. Se ela não corresponder à versão atual da lista, a operação falhará e isso será retornado junto com os metadados atuais da lista (que incluem a versão atual).| | 500| Internal Server Error| O serviço está recusando a solicitação devido a um erro no servidor.| | 501| Not Implemented| O chamador solicitou um URI que não foi implementado no servidor. (Atualmente, usado apenas quando é feita uma solicitação para um nome de lista que não está na lista de permissões.)| | 503| Service Unavailable| O servidor está recusando a solicitação, geralmente devido a carga excessiva. Após um intervalo (consulte o cabeçalho Retry-after), a solicitação pode ser repetida.|

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

| Cabeçalho| Descrição| | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Authorization| Contém o token STS usado para autenticar e autorizar a solicitação. Deve ser um token do serviço XSTS e incluir o XUID como uma das declarações. | | X-XBL-Contract-Version| Especifica qual versão da API está sendo solicitada (inteiros positivos). Pins dá suporte à versão 2. Se esse cabeçalho estiver ausente ou o valor não tiver suporte, o serviço retornará 400 - Bad request com “Unsupported or missing contract version header” na descrição do status.| | Content-Type| Especifica se o conteúdo dos corpos de solicitação/resposta estará em json ou xml. Os valores com suporte são “application/json” e “application/xml”| | If-Match| Este cabeçalho deve conter o número da versão atual de uma lista ao fazer solicitações de modificação. As solicitações de modificação usam os verbos PUT, POST ou DELETE. Se a versão no cabeçalho “If-Match” não corresponder à versão atual da lista, a solicitação será rejeitada com um código de retorno HTTP 412 - precondition failed. (opcional) Também pode ser usado para GETs; se estiver presente e a versão passada corresponder à versão atual da lista, nenhum dado da lista será retornado, e sim um código HTTP 304 - Not Modified. |

​
Exemplo de solicitação

ContentType, ItemId ou ProviderId, Provider e Locale são obrigatórios.

​
Corpo da resposta

​
Exemplo de resposta

​
Consulte também

Pai
/users/xuid(xuid)/lists/PINS/
Last modified on October 6, 2026