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

项目
05/09/2023

返回列表的内容。这些 URI 的域是 eplists.xboxlive.com。

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

备注

返回的数据中的 listCount 字段指示服务维护的总列表中有多少项目 - 同样，它可以用于确定列表末尾的位置，此数字可能与请求返回的特定项目的数量不同。

如果列表尚不存在，结果将不包含列表项，listCount 将为零，listVersion 将为零。

URI 参数

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

查询字符串参数

参数	类型	说明
skipItems	32 位有符号整数	可选。在返回结果前在枚举中跳过的项目数。默认值：0。
maxItems	32 位有符号整数	可选。要返回的最大项目数。如果未在请求中指定最大数，默认为 25 个项目。服务不对此值设置最大值；如果值大于列表中的项目数，所有项目都将返回，不会发生错误。
filterItemId	字符串	可选。指定要在列表中查找的项目。返回列表中项目的所有实例。允许客户端快速确定项目是否在列表中以及在哪个位置。便于较大列表确定项目的所有实例，而无需循环访问整个列表。默认值：null。
filterContentType	字符串	可选。指定要返回的逗号分隔的内容类型列表（不会返回列表中没有的类型）。用于只从列表中获取某些内容类型。逗号分隔的内容类型列表用于此筛选器。（多个内容类型可以在一个调用中查询。）支持的内容类型包括 Entertainment Discovery Services (EDS) 定义的所有媒体类型。默认值：null（所有内容类型）。
filterDeviceType	字符串	可选。指定要返回的逗号分隔的设备类型列表（不会返回列表中没有的类型）。筛选返回集以仅返回已从一组特定设备类型插入的项目。逗号分隔的设备类型列表用于此筛选器（多个设备类型可以在一个调用中查询）。可能值：XboxOne、MCapensis、WindowsPhone、WindowsPhone7、Web、PC、MoLive。默认值：null（所有内容类型）。

授权

此调用需要在 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 标头），可以重试请求。

响应正文

示例响应

{ 
"ListMetadata":
  {"ListVersion": 12,
   "ListCount": 6,
   "MaxListSize": 200,
   "AccessSetting": "OwnerOnly",
   "AllowDuplicates": true
  },
"ListItems":
  [{ 
   "Index": 0,
   "DateAdded": "\/Date(1198908717056)/",
   "DateModified": "\/Date(1198908717056)/",
   "HydrationResult": "Indeterminate",
   "HydratedItem": null

   "Item":
   {
     "ContentType": "Movie",
     "ItemId": "3a5095a5-eac3-4215-944d-27bc051faa47",
     "ProviderId": null,
     "Provider": null,
     "ImageUrl": "http://www.bing.com/thumb/get?bid=Gw%2fsjCGSS4kAAQ584x800&bn=SANGAM&fbid=7wIR63+Clmj+0A&fbn=CC",
     "Title": "The Dark Knight",
     "SubTitle": null,
     "Locale": "en-us",
     "AltImageUrl": null,
     "DeviceType": "XboxOne"
    }
  }]
}

另请参阅

父级

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

补充信息

市场 URI

其他参考

通过