> ## 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.

# POST /users/xuid(xuid)/lists/PINS/{listname}/index({index})?insertIndex={insertIndex}

> POST /users/xuid(xuid)/lists/PINS/{listname}/index({index})?insertIndex={insertIndex}

# POST /users/xuid(xuid)/lists/PINS/{listname}/index({index})?insertIndex={insertIndex}

Déplace un élément d'une liste vers une autre position dans la liste.
Le domaine de ces URI est `eplists.xboxlive.com`.

* [Remarques](#ID4EV)
* [Paramètres d'URI](#ID4EEB)
* [Paramètres de la chaîne de requête](#ID4EWC)
* [Corps de la requête](#ID4EVD)
* [Codes d'état HTTP](#ID4EEE)
* [En-têtes de requête obligatoires](#ID4E1BAC)
* [Corps de la réponse](#ID4EQDAC)

## Remarques

Cet appel permet au client de déplacer facilement un élément vers un autre index de la liste en une seule opération. Un seul élément peut être déplacé à la fois. Si l'index de l'élément à déplacer n'existe pas, un code HTTP 400 est retourné. L'index du point d'insertion suit les mêmes règles qu'une insertion standard. Sa valeur par défaut est 0, soit le début de la liste, et tout nombre supérieur au nombre d'éléments de la liste réinsère l'élément à la fin de la liste. De même, la fin de la liste peut être indiquée en transmettant « end » pour insertIndex.

Cet appel vous permet également d'identifier l'élément à déplacer par son itemId (ou par la combinaison provider/providerId). Dans ce cas, l'itemId doit être transmis dans le corps de la requête et doit correspondre à un élément existant de la liste. Sinon, une erreur HTTP 400 est retournée avec IndexOutOfRange dans la description; pour cette version particulière de l'appel, utilisez « -1 » comme index de l'élément à déplacer.

Cet appel exige que l'en-tête « If-Match:versionNumber » soit inclus dans la requête si l'élément est spécifié par index. Si vous utilisez itemId pour indiquer l'élément à déplacer, l'en-tête « If-Match » est facultatif. S'il est présent, l'en-tête « If-Match » est toujours validé. Dans l'en-tête « if-Match », versionNumber est le numéro de version actuel de la liste. S'il n'est pas inclus (alors qu'il est obligatoire) ou ne correspond pas au numéro de version actuel de la liste, le code d'état HTTP 412 - precondition failed est retourné et le corps de la réponse contient les métadonnées les plus récentes de la liste, y compris le numéro de version actuel. Cela permet d'éviter que les mises à jour de différents clients s'écrasent mutuellement.

## Paramètres d'URI

| Paramètre | Type | Description |
| - | - | - |
| XUID | chaîne | XUID de l'utilisateur. |
| listname | chaîne | Nom de la liste à manipuler. |
| index | chaîne | Indique l'index actuel de l'élément à déplacer. Si la valeur de l'index est zéro ou un entier positif, elle désigne l'index actuel de l'élément et le corps de la requête de l'appel doit être vide. Toutefois, si la valeur de l'index est « -1 », l'élément à déplacer doit être spécifié par ItemId ou Provider/ProviderID dans le corps de la requête de l'appel. |

## Paramètres de la chaîne de requête

\| Paramètre| Type| Description|
\| --- | --- | --- | --- | --- | --- |
\| insertIndex| chaîne| Indique l'emplacement de la liste où insérer l'élément. Les valeurs autorisées sont zéro, les entiers positifs et « end ». « end » place l'élément à la fin de la liste actuelle. Si la valeur spécifiée dépasse la fin de la liste, l'élément est inséré à la fin de la liste.|

## Corps de la requête

Un corps de requête est envoyé uniquement lorsque l'élément à déplacer est spécifié par itemId ou par Provider/ProviderId.

Exemple de requête

```cpp theme={null}
{
  "Item":
  {
    "ItemId":  "ed591a0c-dde3-563f-99af-530278a3c402",
    "ProviderId":  null,
    "Provider": null
  }
}
    
```

## Codes d'état HTTP

Le service retourne l'un des codes d'état de cette section en réponse à une requête effectuée avec cette méthode sur cette ressource. Pour obtenir la liste complète des codes d'état HTTP standard utilisés avec les services XBOX Live, consultez [Codes d'état HTTP standard](https://docs.xbox.com/fr-CA/reference/live/rest/additional/httpstatuscodes.md).

\| Code| Phrase de motif| Description|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| 200| OK| La requête s'est terminée avec succès. Le corps de la réponse doit contenir la ressource demandée (pour un GET). Les requêtes POST et PUT reçoivent les métadonnées à jour de la liste (version de la liste, nombre, etc.).|
\| 201| Created| Une nouvelle liste a été créée. Ce code est retourné lors de la première insertion dans une liste. La réponse comprend les métadonnées à jour de la liste et l'en-tête location contient l'URI de la liste.|
\| 304| Not Modified| Retourné pour les GET. Indique que le client possède la dernière version de la liste. Le service compare la valeur de l'en-tête **If-Match** à la version de la liste. Si elles sont égales, un code 304 est retourné sans données.|
\| 400| Bad Request| La requête était mal formée. Il peut s'agir d'une valeur ou d'un type non valide pour un paramètre d'URI ou de chaîne de requête. Cela peut aussi résulter d'un paramètre ou d'une valeur de données obligatoire manquant, ou d'une version de l'API manquante ou non valide indiquée dans la requête. Consultez l'en-tête **X-XBL-Contract-Version**.|
\| 401| Unauthorized| La requête nécessite l'authentification de l'utilisateur.|
\| 403| Forbidden| La requête n'est pas autorisée pour l'utilisateur ou le service.|
\| 404| Not Found| L'appelant n'a pas accès à la ressource. Cela indique qu'aucune liste de ce type n'a été créée.|
\| 412| Precondition Failed| Indique que la version de la liste a changé et qu'une requête de modification a échoué. Une requête de modification est une insertion, une mise à jour ou une suppression. Le service vérifie la version de la liste dans l'en-tête **If-Match**. Si elle ne correspond pas à la version actuelle de la liste, l'opération échoue et ce code est retourné avec les métadonnées actuelles de la liste (qui incluent la version actuelle).|
\| 500| Internal Server Error| Le service refuse la requête en raison d'une erreur côté serveur.|
\| 501| Not Implemented| L'appelant a demandé un URI qui n'a pas été implémenté sur le serveur. (Actuellement utilisé uniquement lorsqu'une requête porte sur un nom de liste qui ne figure pas dans la liste d'autorisation.)|
\| 503| Service Unavailable| Le serveur refuse la requête, généralement en raison d'une charge excessive. Après un délai (consultez l'en-tête **Retry-after**), la requête peut être réessayée.|

## En-têtes de requête obligatoires

\| En-tête| Description|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| Authorization| Contient le jeton STS utilisé pour authentifier et autoriser la requête. Doit être un jeton du service XSTS et inclure le XUID parmi les revendications.|
\| X-XBL-Contract-Version| Indique la version de l'API demandée (entiers positifs). Pins prend en charge la version 2. Si cet en-tête est absent ou si la valeur n'est pas prise en charge, le service retourne un code 400 - Bad request avec « Unsupported or missing contract version header » dans la description de l'état.|
\| Content-Type| Indique si le contenu des corps de requête et de réponse sera en JSON ou en XML. Les valeurs prises en charge sont « application/json » et « application/xml »|
\| If-Match| Cet en-tête doit contenir le numéro de version actuel d'une liste lors des requêtes de modification. Les requêtes de modification utilisent les verbes PUT, POST ou DELETE. Si la version de l'en-tête « If-Match » ne correspond pas à la version actuelle de la liste, la requête est rejetée avec le code de retour HTTP 412 - precondition failed. (facultatif) Peut aussi être utilisé pour les GET : s'il est présent et que la version transmise correspond à la version actuelle de la liste, aucune donnée de liste n'est retournée et le code HTTP 304 - Not Modified est retourné.|

## Corps de la réponse

Si l'appel réussit, le service retourne les métadonnées les plus récentes de la liste.

### Exemple de réponse

```cpp theme={null}
{ 
  "ListVersion":  1,
  "ListCount":  1,
  "MaxListSize": 200,
  "AllowDuplicates": "true",
  "AccessSetting":  "OwnerOnly"
}

      
```


## Related topics

- [/users/xuid(xuid)/lists/PINS/{listname}/index({index})?insertIndex={insertIndex}](https://docs.xbox.com/fr-CA/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamewindows-apg.md)
- [POST (/users/xuid(xuid)/lists/PINS/{listname})](https://docs.xbox.com/fr-CA/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamepost.md)
- [/users/xuid(xuid)/lists/PINS/{listname}](https://docs.xbox.com/fr-CA/reference/live/rest/uri/lists/uri-usersxuidlistspinslistname.md)
- [DELETE (/users/xuid(xuid)/lists/PINS/{listname})](https://docs.xbox.com/fr-CA/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamedelete.md)
- [DELETE /users/xuid(xuid)/lists/PINS/{listname}/RemoveItems](https://docs.xbox.com/fr-CA/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnameremoveitemsdelete.md)