Skip to main content

PUT (/users/xuid(xuid)/lists/PINS/)

依據要求本文中為每個項目指定的索引,更新清單中的項目。 這些 URI 的網域是 eplists.xboxlive.com。

備註

此呼叫會依據要求本文中為每個項目指定的索引,更新清單中的項目。此呼叫不會將項目插入清單,如果指定的索引處不存在項目,則呼叫會傳回 400 Bad Request 狀態。單一呼叫中可以更新多個項目,但所有項目都必須存在於目前的清單中。也就是說,要麼全部更新,要麼全部不更新。 此呼叫允許以 itemId 而非 index 來指定要更新的項目。若要這麼做,只需在傳送給服務的 IndexedItems 結構中,將索引設為 “-1” 即可。顯然在此情況下,itemId 無法在更新時變更,因此僅適用於變更其他中繼資料欄位。也可以使用 provider/providerId 組合取代 itemId 來識別項目。服務會在內部搜尋清單中的這些項目,並找出要更新的正確索引。如果找不到該項目或這些項目,則會傳回 400 Bad Request 狀態,且不會更新任何項目。 如果使用索引來識別項目,此呼叫要求在要求中包含 If-Match:versionNumber 標頭。如果使用項目識別碼來識別項目 (且清單不允許重複項目),則 If-Match 標頭為選用。如果存在 if-Match 標頭,一律會進行驗證。在標頭中,versionNumber 是清單目前的版本號碼。如果未包含此標頭 (且為必要),或與清單目前的版本號碼不符,則會傳回 HTTP 412 Precondition Failed 狀態碼,且回應本文會包含清單的最新中繼資料,其中包括目前的版本號碼。這是為了防止來自不同用戶端的更新互相覆蓋。

URI 參數

授權

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

HTTP 狀態碼

服務會傳回本節中的其中一個狀態碼,以回應在此資源上使用此方法所提出的要求。如需 XBOX Live 服務所使用之標準 HTTP 狀態碼的完整清單,請參閱標準 HTTP 狀態碼。 | 代碼| 原因片語| 描述| | --- | --- | --- | --- | --- | --- | --- | | 200| OK| 要求已成功完成。回應本文應包含所要求的資源 (適用於 GET)。POST 和 PUT 要求會收到最新的清單中繼資料 (清單版本、計數等)。| | 201| Created| 已建立新清單。這會在首次插入清單時傳回。回應包含清單的最新中繼資料,且 location 標頭包含清單的 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 標頭),即可重試要求。|

必要的要求標頭

| 標頭| 描述| | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 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 代碼。 |

要求本文

範例要求

回應本文

範例回應

另請參閱

上層
/users/xuid(xuid)/lists/PINS/
Last modified on October 6, 2026