GET (/users/xuid(xuid)/lists/PINS/)

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

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

备注

返回数据中的 listCount 字段表示服务所维护的整个列表中包含的项数——因此,可用于确定列表的末尾位置,并且此数字可能不同于请求返回的具体项的数量。如果列表尚不存在,则结果将不包含任何列表项,listCount 将为零,并且 listVersion 也将为零。

URI 参数

参数	类型	说明
xuid	string	XBOX 用户 ID (XUID)。
listtype	string	列表的类型(表示其用途以及行为方式)。对于这些相关方法,始终为 “PINS”。
listname	string	列表的名称(表示对给定 listtype 的哪个列表进行操作)。对于 Pins 中的项,始终为 “XBLPins”。

查询字符串参数

参数	类型	说明
skipItems	32 位有符号整数	可选。在返回结果之前,枚举中要跳过的项数。默认值:0。
maxItems	32 位有符号整数	可选。要返回的项的最大数量。如果请求中未指定最大值,则默认值为 25 项。服务对此值不设上限;如果该值大于列表中的项数,则将返回所有项,不会报错。
filterItemId	string	可选。指定要在列表中查找的项。返回该项在列表中的所有实例。允许客户端快速判断某个项是否存在于列表中以及位于何处。对于大型列表非常方便,可确定某项的所有实例,而无需遍历整个列表。默认值:null。
filterContentType	string	可选。指定以逗号分隔的要返回的内容类型列表(不在列表中的类型将不被返回)。用于仅从列表中获取特定内容类型。此筛选器使用以逗号分隔的内容类型列表。(可在一次调用中查询多个内容类型。)支持的内容类型包括 Entertainment Discovery Services (EDS) 定义的所有媒体类型。默认值:null(所有内容类型)。
filterDeviceType	string	可选。指定以逗号分隔的要返回的设备类型列表(不在列表中的类型将不被返回)。将返回集筛选为仅返回从特定设备类型集合插入的项。此筛选器使用以逗号分隔的设备类型列表(可在一次调用中查询多个设备类型)。可能的值: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 令牌。

必需的请求标头

标头	说明
Authorization	包含用于对请求进行身份验证和授权的 STS 令牌。必须是来自 XSTS 服务的令牌,并且包含 XUID 作为其中一项声明。
X-XBL-Contract-Version	指定正在请求的 API 版本(正整数)。Pins 支持版本 2。如果缺少此标头或值不受支持,则服务将返回 400 - Bad request,状态描述为 “Unsupported or missing contract version header”。
Content-Type	指定请求/响应正文的内容是 json 还是 xml。支持的值为 “application/json” 和 “application/xml”。
If-Match	发出修改请求时,此标头必须包含列表的当前版本号。修改请求使用 PUT、POST 或 DELETE 谓词。如果 “If-Match” 标头中的版本与列表的当前版本不匹配,则请求将被拒绝并返回 HTTP 412 - precondition failed 代码。(可选)也可用于 GET,如果存在并且传入的版本与当前列表版本匹配,则不返回任何列表数据并返回 HTTP 304 - Not Modified 代码。

请求正文

此请求的正文中不发送任何对象。

HTTP 状态代码

服务针对使用此方法对此资源发出的请求,返回本节中的某个状态代码。有关与 XBOX Live 服务一同使用的标准 HTTP 状态代码的完整列表,请参见标准 HTTP 状态代码。

代码	原因短语	说明
200	OK	请求已成功完成。响应正文应包含所请求的资源(对于 GET)。POST 和 PUT 请求将收到最新的列表元数据(列表版本、计数等)。
201	Created	已创建新列表。这是在向列表进行初始插入时返回的。响应包含列表的最新元数据,并且位置标头包含该列表的 URI。
304	Not Modified	对 GET 返回。表示客户端已拥有该列表的最新版本。服务将 If-Match 标头中的值与列表版本进行比较。如果相等,则返回 304 且不带任何数据。
400	Bad Request	请求格式错误。可能是 URI 或查询字符串参数的值或类型无效。也可能是由于缺少必需的参数或数据值,或者请求指示了缺少或无效的 API 版本。请参见 X-XBL-Contract-Version 标头。
401	Unauthorized	请求需要用户身份验证。
403	Forbidden	不允许该用户或服务发出请求。
404	Not Found	调用者无权访问该资源。这表示尚未创建这样的列表。
412	Precondition Failed	表示列表的版本已更改,并且修改请求失败。修改请求是插入、更新或移除操作。服务会检查 If-Match 标头中的列表版本。如果与列表的当前版本不匹配,则该操作失败,并返回此代码以及当前列表的元数据(包括当前版本)。
500	Internal Server Error	由于服务器端错误,服务正在拒绝请求。
501	Not Implemented	调用者请求了尚未在服务器上实现的 URI。(当前仅在对未列入允许列表的列表名称发出请求时使用。)
503	Service Unavailable	服务器拒绝请求,通常是由于负载过大。经过延迟后(请参见 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/

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

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

GET (/users/xuid(xuid)/lists/PINS/)

备注

URI 参数

查询字符串参数

授权

必需的请求标头

请求正文

HTTP 状态代码

响应正文

响应示例

另请参阅

父主题

更多信息

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

​备注

​URI 参数

​查询字符串参数

​授权

​必需的请求标头

​请求正文

​HTTP 状态代码

​响应正文

​响应示例

​另请参阅

父主题

更多信息

GET (/users/xuid(xuid)/lists/PINS/)

备注

URI 参数

查询字符串参数

授权

必需的请求标头

请求正文

HTTP 状态代码

响应正文

响应示例

另请参阅