Skip to main content

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

Insère des éléments dans la liste à l’index défini par le paramètre de chaîne de requête insertIndex. Le domaine de ces URI est eplists.xboxlive.com.

​
Remarques

Cet appel insère des éléments dans la liste à l’index défini par le paramètre de chaîne de requête insertIndex (0 par défaut, soit le début de la liste). Tous les éléments du corps de la requête sont insérés à cet emplacement de la liste. Si insertIndex est supérieur au nombre d’éléments de la liste existante, les nouveaux éléments sont insérés à la fin. Les éléments à insérer doivent comporter les champs obligatoires indiqués dans la spécification fonctionnelle ; sinon, un code HTTP 400 est retourné. De même, si l’insertion entraîne un dépassement de la taille maximale de la liste (définie par type de liste), un code HTTP 400 est retourné et rien n’est inséré. Si l’élément ne doit pas être inséré au début ou à la fin de la liste, l’en-tête If-Match:versionNumber doit être inclus dans la requête. L’en-tête est facultatif si l’insertion se fait au début ou à la fin. S’il est présent, l’en-tête est validé quel que soit l’emplacement d’insertion. Dans l’en-tête, VersionNumber est le numéro de version actuel de la liste. S’il n’est pas inclus alors qu’il est obligatoire, ou s’il ne correspond pas au numéro de version actuel de la liste, un code d’état HTTP 412 (precondition failed) est retourné, et le corps de la réponse contient les dernières métadonnées de la liste, qui incluent le numéro de version actuel. Cela permet d’éviter que des mises à jour provenant de différents clients ne s’écrasent mutuellement. Notez que cet appel n’est pas idempotent ; des appels répétés avec les mêmes données peuvent entraîner plusieurs insertions. Toutefois, comme aucune liste ne prend actuellement en charge les doublons, des appels répétés entraîneront probablement le retour de codes HTTP 400.

​
Paramètres d’URI

​
Paramètres de chaîne de requête

| Paramètre| Type| Description| | --- | --- | --- | --- | --- | --- | | insertIndex| string| Facultatif. Définit l’emplacement où insérer les éléments. Valeurs prises en charge : 0, entiers positifs et “end”. Toute valeur d’index supérieure au nombre d’éléments de la liste ajoute le nouvel élément en bas de la liste, sans insérer d’espace “vide” dans la liste. Valeur par défaut : 0.|

​
Autorisation

Cet appel attend un jeton SAML XSTS dans l’en-tête Authorization. Une revendication Xuid doit exister dans ce jeton SAML pour identifier l’appelant. Cette valeur permet de déterminer si l’appelant dispose de droits d’accès aux données de la liste concernée. La liste elle-même est également identifiée par le Xuid, qui est inclus dans l’URI de la liste. Cela pourrait permettre à l’avenir de prendre en charge l’accès partagé aux listes, mais cette fonctionnalité n’existe pas pour le moment. Actuellement, toutes les listes auxquelles un utilisateur accède lui appartiennent, et il n’y a pas d’accès partagé. Par conséquent, le Xuid de l’URI doit correspondre au Xuid du jeton de revendications SAML.
Remarque :
Les jetons XBL Auth 2.0 et 3.0 sont actuellement tous deux pris en charge.

​
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 XBOX Live Services, consultez Codes d’état HTTP standard. | Code| Expression de raison| Description| | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 200| OK| La requête a abouti. 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 d’éléments, 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 inclut 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 dispose 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 obligatoire ou d’une valeur de données manquants, ou d’une version de l’API manquante ou non valide indiquée par la requête. Consultez l’en-tête X-XBL-Contract-Version.| | 401| Unauthorized| La requête nécessite une 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 verte.)| | 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| Spécifie 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| Spécifie si le contenu des corps de requête/réponse sera au format json ou 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 de requêtes de modification. Les requêtes de modification utilisent les verbes PUT, POST ou DELETE. Si la version indiquée dans 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 également ê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é.|

​
Exemple de requête

ContentType, ItemId ou ProviderId, Provider et Locale sont obligatoires.

​
Corps de la réponse

​
Exemple de réponse

​
Voir aussi

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

Related topics

XblSocialSubmitReputationFeedbackAsyncXblAchievementsUpdateAchievementAsync