PUT (/users/xuid(xuid)/lists/PINS/{listname})

项目
05/09/2023

根据在请求正文中为每个项目指定的索引更新列表中的项目。这些 URI 的域是 eplists.xboxlive.com。

备注
URI 参数
授权
HTTP 状态代码
必需请求标头
请求正文
响应正文

备注

此调用将根据在请求正文中为每个项目指定的索引更新列表中的项目。此调用不会将项目插入列表，如果项目在指定的索引处不存在，调用将返回“400 无效的请求”状态。多个项目可以在一个调用中更新，但所有项目均必须存在于当前列表中。也就是说，全部更新或全部未更新。

此调用将允许项目被更新为由 itemId 而不是 index 指定。若要执行此操作，只需为发送到服务的 IndexedItems 结构中的索引使用“-1”。在此情况下很明显，itemId 无法作为更新的一部分更改，因此它仅适用于对其他元数据字段的更改。 provider/providerId 组合（而不是 itemId）可用于标识项目。在内部，服务搜索列表来查找这些项目，并找出正确的更新索引。如果找不到项目（一个或多个），将返回“400 无效的请求”状态，没有项目会被更新。

如果使用索引标识项目，此调用需要在请求中包含 If-Match:versionNumber 标头。如果使用项目 ID 标识项目（并且列表不允许重复项），If-Match 标头则是可选的。如果存在，if-Match 标头会始终被验证。在标头中，versionNumber 是列表的当前版本号。如果未包含（但需要），或与当前的列表版本号不一致，将返回“HTTP 412 前置条件失败”状态代码，响应的正文将包含包括当前版本号的列表的最新元数据。这是为了防止来自会相互破坏的其他客户端的更新。

URI 参数

参数	类型	说明
xuid	字符串	Xbox 用户 ID (XUID)。
listtype	字符串	列表的类型（使用方法及其工作方式）。对于这些相关方法始终是“PIN”。
listname	字符串	列表的名称（要对哪个指定 listtype 的列表执行操作）。对于“固定”中的项目始终为“XBLPins”。

授权

此调用需要在 Authorization 标头中有 XSTS SAML 令牌。该 SAML 令牌内必须有 Xuid 声明以标识调用方。此值用于确定调用方是否有权访问有问题的列表数据。列表本身将由 Xuid 标识，并将包含在列表的 URI 中。使用此方法，我们将来可以支持对列表的共享访问，但现在这项功能还未实现。目前，用户访问的所有列表都是他们自己的，没有共享访问。因此，URI 中的 Xuid 必须与 SAML 声明令牌中的 Xuid 一致。

注意：
目前支持 XBL Auth 2.0 和 3.0 令牌。

HTTP 状态代码

服务返回此部分中的状态代码之一，以响应使用此方法对此资源发出的请求。对于用于 Xbox Live 服务的标准 HTTP 状态代码的完整列表，请参阅标准 HTTP 状态代码。

代码	原因短语	说明
200	确定	已成功完成请求。响应正文应包含请求的资源（对于 GET）。 POST 和 PUT 请求将收到最新的列表元数据（列表版本、计数等）。
201	Created	新列表已创建。在最初插入到列表时返回。响应包含列表中的最新元数据，位置标头包含列表的 URI。
304	未修改	在 GET 上返回。指示客户端具有最新版本的列表。服务将 If-Match 标头中的值与列表版本进行比较。如果相等，304 将返回，且不包含任何数据。
400	无效请求	请求格式错误。可能是无效值或者 URI 或查询字符串参数的类型。也可能是缺少的必需参数或数据值的结果，或指示缺少或无效 API 版本的请求。请参阅 X-XBL-Contract-Version 标头。
401	未授权	请求需要用户身份验证。
403	已禁止	用户或服务不允许此请求。
404	未找到	调用方没有访问资源的权限。这指示未创建此类列表。
412	前置条件失败	指示列表的版本已发生更改，并且修改请求已失败。修改请求是插入、更新或删除。服务检查列表版本的 If-Match 标头。如果与列表的当前版本不一致，操作将失败，并将返回此信息以及当前的列表元数据（其中包括当前版本）。
500	内部服务器错误	服务由于服务器端错误拒绝请求。
501	未实现	调用方请求了未在服务器上实现的 URI。（当前仅在为不允许列出的列表名称发出请求时使用。）
503	服务不可用	服务器拒绝请求，通常由于超载。延迟后（参阅 Retry-after 标头），可以重试请求。

必需请求标头

标头	说明
授权	包含用于对请求进行身份验证和授权的 STS 令牌。必须是来自 XSTS 服务的令牌，作为声明之一包含 XUID。
X-XBL-Contract-Version	指定正在请求哪个 API 版本（正整数）。 “固定”支持版本 2。如果缺少此标头或值不受支持，服务将在状态描述中返回“400 - 无效的请求”以及“协定版本标头不受支持或缺失”。
Content-Type	指定请求/响应正文的内容是否是 json 或 xml 格式。支持的值为“application/json”和“application/xml”
If-Match	在发起修改请求时，此标头必须包含列表的当前版本号。修改请求使用 PUT、POST 或 DELETE 谓词。如果“If-Match”标头中的版本与列表的当前版本不一致，请求将被拒绝并显示“HTTP 412 - 前置条件失败”返回代码。（可选）另外还可用于 GET，如果显示的版本和传入的版本与当前的列表版本一致，将不会返回列表数据和“HTTP 304 – 未修改”代码。

请求正文

示例请求

{"IndexedItems":
 [{  "Index": 0, 
     "Item": 
     {
       "ContentType": "Movie",
       "ItemId": "3a5095a5-eac3-4215-944d-27bc051faa47",
       "ProviderId": null,
       "Provider": null,
       "ImageUrl": "http://www.bing.com/thumb/...",
       "Title": "The Dark Knight",
       "SubTitle":null, 
       "Locale": "en-us",
       "DeviceType": "XboxOne"
     }
}]}

响应正文

示例响应

{
  "ListVersion":  1,
  "ListCount":  1,
  "MaxListSize": 200,
  "AllowDuplicates": "true",
  "AccessSetting":  "OwnerOnly"
}

另请参阅

父级

/users/xuid(xuid)/lists/PINS/{listname}

通过