> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

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

* [备注](#ID4EV)
* [URI 参数](#ID4EIB)
* [查询字符串参数](#ID4ETB)
* [授权](#ID4ESD)
* [必需的请求标头](#ID4E6D)
* [请求正文](#ID4EVF)
* [HTTP 状态代码](#ID4EAG)
* [响应正文](#ID4E5CAC)

## 备注

返回数据中的 **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 状态代码](https://devdocs.xbox.com/zh-CN/reference/live/rest/additional/httpstatuscodes)。

| 代码 | 原因短语 | 说明 |
| - | - | - |
| 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** 标头),可以重试请求。 |

## 响应正文

### 响应示例

```cpp theme={null}
{ 
"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}](https://devdocs.xbox.com/zh-CN/reference/live/rest/uri/lists/uri-usersxuidlistspinslistname)

##### 更多信息

[Marketplace URIs](https://devdocs.xbox.com/zh-CN/reference/live/rest/uri/marketplace/atoc-reference-marketplace)

[其他参考](https://devdocs.xbox.com/zh-CN/reference/live/rest/additional/atoc-xboxlivews-reference-additional)


## Related topics

- [XblUserStatisticsGetSingleUserStatisticAsync](https://devdocs.xbox.com/ja-jp/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticsgetsingleuserstatisticasync.md)
- [XblUserStatisticsGetSingleUserStatisticsAsync](https://devdocs.xbox.com/ja-jp/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticsgetsingleuserstatisticsasync.md)