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

项目
05/09/2023

删除列表中的项目。这些 URI 的域是 eplists.xboxlive.com。

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

备注

要删除的项目在列表中由其索引指示，在查询字符串参数 indexes 中标识。索引列表必须以逗号分隔，一个调用中只能传入 100 个索引。但是，如果未传递索引（空查询字符串参数），那么整个列表的内容都将被删除（空列表将保留，版本号将继续递增）。项目被删除后，列表将被“压缩”，以不会按索引顺序留下洞。因此，此调用不是幂等的。

此调用需要将 If-Match:versionNumber 标头包含在请求中，其中的 versionNumber 是文件的当前版本号。如果未包含，或与当前的列表版本号不一致，将返回 HTTP 412（前置条件失败）状态代码，响应的正文将包含包括当前版本号的列表的最新元数据。这是为了防止来自会相互破坏的其他客户端的更新。

URI 参数

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

查询字符串参数

参数	类型	说明
索引	字符串	可选。指定删除项目的位置。支持的值：0、正整数和“end”。默认值：0。

示例：indexes=1,8 删除索引 1 和 8 处的项目。索引必须是唯一的。如果未提供索引，将清除整个列表。

授权

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

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

必需请求标头

标头	说明
授权	包含用于对请求进行身份验证和授权的 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 – 未修改”代码。

请求正文

对象不会在此请求的正文中发送。

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 标头），可以重试请求。

响应正文

示例响应

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

另请参阅

父级

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

通过