> ## 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)

<a id="ID4EV" />

## 備註

傳回資料中的 **listCount** 欄位表示服務所維護的整個清單中有多少個項目，因此可用來判斷清單的結尾位置，而此數字可能與要求所傳回的特定項目數不同。

如果清單尚不存在，則結果不會包含任何清單項目，**listCount** 會是零，**listVersion** 也會是零。

<a id="ID4EIB" />

## URI 參數

| 參數 | 類型 | 描述 |
| - | - | - |
| xuid | 字串 | XBOX 使用者識別碼 (XUID)。 |
| listtype | 字串 | 清單的類型 (其使用方式和運作方式)。對於這些相關方法，一律為 "PINS"。 |
| listname | 字串 | 清單的名稱 (要對指定 listtype 的哪個清單執行動作)。對於 Pins 中的項目，一律為 "XBLPins"。 |

<a id="ID4ETB" />

## 查詢字串參數

\| 參數| 類型| 描述|
\| --- | --- | --- | --- | --- | --- |
\| skipItems| 32 位元帶正負號的整數| 選用。傳回結果之前，在列舉中要略過的項目數。預設值：0。|
\| maxItems| 32 位元帶正負號的整數| 選用。要傳回的項目數上限。如果要求中未指定上限，預設為 25 個項目。服務不會對此值設定上限；如果此值大於清單中的項目數，則會傳回所有項目且不會發生錯誤。|
\| filterItemId| 字串| 選用。指定要在清單中尋找的項目。傳回清單中該項目的所有執行個體。可讓用戶端快速判斷項目是否在清單中以及位於何處。對於大型清單很方便，無需逐一查看整個清單即可判斷項目的所有執行個體。預設值：null。|
\| filterContentType| 字串| 選用。指定要傳回的內容類型清單，以逗號分隔 (不會傳回不在清單中的類型)。用於只從清單中取得特定內容類型。此篩選條件使用以逗號分隔的內容類型清單。(可在一次呼叫中查詢多個內容類型。) 支援的內容類型包括 Entertainment Discovery Services (EDS) 所定義的所有媒體類型。預設值：null (所有內容類型)。|
\| filterDeviceType| 字串| 選用。指定要傳回的裝置類型清單，以逗號分隔 (不會傳回不在清單中的類型)。篩選傳回集合，只傳回從特定裝置類型集合插入的項目。此篩選條件使用以逗號分隔的裝置類型清單 (可在一次呼叫中查詢多個裝置類型)。可能的值：XboxOne、MCapensis、WindowsPhone、WindowsPhone7、Web、PC、MoLive。預設值：null (所有內容類型)。|

<a id="ID4ESD" />

## 授權

此呼叫預期 **Authorization** 標頭中有 XSTS SAML 權杖。該 SAML 權杖中必須存在 Xuid 宣告，以識別呼叫端。此值用於判斷呼叫端是否具有相關清單資料的存取權限。清單本身也會以 Xuid 識別，並包含在清單的 URI 中。藉此，我們未來可能會支援清單的共用存取，但目前尚未提供此功能。目前，使用者存取的所有清單都是使用者自己的清單，沒有共用存取。因此，URI 中的 Xuid 必須與 SAML 宣告權杖中的 Xuid 相符。

> **注意：**\
> 目前同時支援 XBL Auth 2.0 和 3.0 權杖。

<a id="ID4E6D" />

## 必要的要求標頭

\| 標頭| 描述|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| 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 - 前置條件失敗代碼。(選用) 也可用於 GET，如果存在此標頭且傳入的版本與清單目前的版本相符，則不會傳回任何清單資料，並會傳回 HTTP 304 - Not Modified 代碼。 |

<a id="ID4EVF" />

## 要求本文

此要求的本文中不會傳送任何物件。

<a id="ID4EAG" />

## HTTP 狀態碼

服務會傳回本節中的其中一個狀態碼，以回應在此資源上使用此方法所提出的要求。如需 XBOX Live 服務所使用之標準 HTTP 狀態碼的完整清單，請參閱[標準 HTTP 狀態碼](/zh-TW/reference/live/rest/additional/httpstatuscodes)。

\| 代碼| 原因片語| 描述|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| 200| OK| 要求已成功完成。回應本文應包含所要求的資源 (適用於 GET)。POST 和 PUT 要求會收到最新的清單中繼資料 (清單版本、計數等)。|
\| 201| Created| 已建立新清單。這會在首次插入清單時傳回。回應包含清單的最新中繼資料，且 location 標頭包含清單的 URI。|
\| 304| Not Modified| 在 GET 時傳回。表示用戶端擁有最新版本的清單。服務會將 <b>If-Match</b> 標頭中的值與清單版本進行比較。如果兩者相等，則會傳回 304 且不含任何資料。|
\| 400| Bad Request| 要求格式不正確。可能是 URI 或查詢字串參數的值或類型無效。也可能是缺少必要參數或資料值，或要求指出的 API 版本遺失或無效所致。請參閱 <b>X-XBL-Contract-Version</b> 標頭。|
\| 401| Unauthorized| 要求需要使用者驗證。|
\| 403| Forbidden| 不允許使用者或服務提出此要求。|
\| 404| Not Found| 呼叫端沒有該資源的存取權。這表示尚未建立此類清單。|
\| 412| Precondition Failed| 表示清單的版本已變更，且修改要求已失敗。修改要求是指插入、更新或移除。服務會檢查 <b>If-Match</b> 標頭中的清單版本。如果與清單目前的版本不符，則作業會失敗，並傳回此代碼及目前的清單中繼資料 (其中包括目前的版本)。|
\| 500| Internal Server Error| 由於伺服器端錯誤，服務拒絕了此要求。|
\| 501| Not Implemented| 呼叫端要求了伺服器上尚未實作的 URI。(目前僅在針對未列入允許清單的清單名稱提出要求時使用。)|
\| 503| Service Unavailable| 伺服器拒絕了此要求，通常是因為負載過重。經過一段延遲之後 (請參閱 <b>Retry-after</b> 標頭)，即可重試要求。|

<a id="ID4E5CAC" />

## 回應本文

<a id="ID4EEDAC" />

### 範例回應

```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"
    }
  }]
}
         
```

<a id="ID4EODAC" />

## 另請參閱

<a id="ID4EQDAC" />

##### 上層

[/users/xuid(xuid)/lists/PINS/{listname}](/zh-TW/reference/live/rest/uri/lists/uri-usersxuidlistspinslistname)

<a id="ID4E1DAC" />

##### 詳細資訊

[市集 URI](/zh-TW/reference/live/rest/uri/marketplace/atoc-reference-marketplace)

[其他參考](/zh-TW/reference/live/rest/additional/atoc-xboxlivews-reference-additional)


## Related topics

- [XblUserStatisticsGetSingleUserStatisticAsync](/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticsgetsingleuserstatisticasync.md)
- [XblUserStatisticsGetSingleUserStatisticsAsync](/ko/reference/live/xsapi-c/user_statistics_c/functions/xbluserstatisticsgetsingleuserstatisticsasync.md)