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

# PUT (/sessions/{sessionId}/scids/{scid}/data/{pathAndFileName},{type})

> PUT (/sessions/{sessionId}/scids/{scid}/data/{pathAndFileName},{type})

# PUT (/sessions/{sessionId}/scids/{scid}/data/{pathAndFileName},{type})

上傳檔案。資料可以透過完整上傳 (在單一訊息中傳送資料和中繼資料) 的方式上傳，也可以透過多區塊上傳 (在一系列較小的區塊中傳送資料和中繼資料) 的方式上傳。只有小於 4 MB 的檔案才能以單一訊息傳送。json 類型的資料不支援多區塊上傳。
這些 URI 的網域為 `titlestorage.xboxlive.com`。

* [URI 參數](#ID4EX)
* [授權](#ID4EEB)
* [選擇性查詢字串參數](#ID4ERB)
* [必要的要求標頭](#ID4ENE)
* [選擇性要求標頭](#ID4EWF)
* [要求本文](#ID4EZG)
* [HTTP 狀態碼](#ID4EEH)
* [回應本文](#ID4EXEAC)

## URI 參數

| 參數 | 類型 | 描述 |
| - | - | - |
| sessionId | 字串 | 要查閱之工作階段的識別碼。 |
| scid | guid | 要查閱之服務設定的識別碼。 |
| pathAndFileName | 字串 | 要存取之項目的路徑和檔案名稱。路徑部分 (直到並包含最後一個正斜線) 的有效字元包括大寫字母 (A-Z)、小寫字母 (a-z)、數字 (0-9)、底線 (*) 和正斜線 (/)。路徑部分可以是空的。檔案名稱部分 (最後一個正斜線之後的所有內容) 的有效字元包括大寫字母 (A-Z)、小寫字母 (a-z)、數字 (0-9)、底線 (*)、句點 (.) 和連字號 (-)。檔案名稱不可為空的、不可以句點結尾，也不可包含兩個連續的句點。 |
| type | 字串 | 資料的格式。可能的值為 binary 或 json。 |

## 授權

要求必須包含有效的 XBOX LIVE 授權標頭。如果不允許呼叫者存取此資源，服務將傳回 403 Forbidden 回應。如果標頭無效或遺漏，服務將傳回 401 Unauthorized 回應。

## 選擇性查詢字串參數

對於單一訊息上傳，查詢字串參數如下：

\| 參數| 類型| 描述|
\| --- | --- | --- | --- | --- | --- |
\| clientFileTime| DateTime| 最後上傳檔案之用戶端上的檔案日期/時間。|
\| displayName| 字串| 應向使用者顯示的檔案名稱。|

對於多區塊上傳，查詢字串參數如下：

\| 參數| 類型| 描述|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| clientFileTime| DateTime| 最後上傳檔案之用戶端上的檔案日期/時間。|
\| displayName| 字串| 應向使用者顯示的檔案名稱。|
\| continuationToken| 字串| 來自上一個上傳要求之回應的接續權杖。如果這是第一個區塊，則不應指定此項目。 |
\| finalBlock| bool| 針對檔案的最後一個區塊設定為 true。針對所有其他區塊設定為 false。|

## 必要的要求標頭

\| 標頭| 值| 描述|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| x-xbl-contract-version| 1| API 合約版本。|
\| Authorization| XBL3.0 x=\[hash];\[token]| STS 驗證權杖。STSTokenString 會由驗證要求所傳回的權杖取代。如需擷取 STS 權杖及建立授權標頭的詳細資訊，請參閱「驗證和授權 XBOX LIVE 服務要求」。|

## 選擇性要求標頭

\| 標頭| 描述|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| If-Match| 指定必須符合現有項目才能完成作業的 ETag。|
\| If-None-Match| 指定必須不符合任何現有項目才能完成作業的 ETag。|

## 要求本文

要求本文包含要上傳之檔案的內容。對於單一訊息上傳，本文是檔案的完整內容。對於多區塊上傳，本文是查詢字串參數中所指定的檔案部分。

## HTTP 狀態碼

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

\| 代碼| 原因片語| 描述|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| 200| OK | 要求成功。|
\| 201| Created | 已建立實體。|
\| 400| Bad Request | 服務無法理解格式錯誤的要求。通常是無效的參數。|
\| 401| Unauthorized | 要求需要使用者驗證。|
\| 403| Forbidden | 不允許使用者或服務提出此要求。|
\| 404| Not Found | 找不到指定的資源。|
\| 406| Not Acceptable | 不支援資源版本。|
\| 408| Request Timeout | 要求花費太長的時間才能完成。|
\| 500| Internal Server Error | 伺服器發生未預期的狀況，導致無法完成要求。|
\| 503| Service Unavailable | 要求已受到節流，請在 client-retry 值的秒數之後 (例如 5 秒後) 再次嘗試要求。|

## 回應本文

如果呼叫是多區塊要求且成功，服務將傳回要與下一個區塊一起傳遞的接續權杖。

### 範例回應

```cpp theme={null}
{
    "continuationToken":"abcd1234-1111-2222-3333-abcd12345678-1"
}
         
```

## 另請參閱

##### 上層

[/sessions/{sessionId}/scids/{scid}/data/{pathAndFileName},{type}](https://docs.xbox.com/zh-TW/reference/live/rest/uri/storage/uri-sessionssessionidscidssciddatapathandfilenametype.md)


## Related topics

- [/sessions/{sessionId}/scids/{scid}/data/{pathAndFileName},{type}](https://docs.xbox.com/zh-TW/reference/live/rest/uri/storage/uri-sessionssessionidscidssciddatapathandfilenametype.md)
- [DELETE (/sessions/{sessionId}/scids/{scid}/data/{pathAndFileName},{type})](https://docs.xbox.com/zh-TW/reference/live/rest/uri/storage/uri-sessionssessionidscidssciddatapathandfilenametype-delete.md)
- [GET (/sessions/{sessionId}/scids/{scid}/data/{pathAndFileName},{type})](https://docs.xbox.com/zh-TW/reference/live/rest/uri/storage/uri-sessionssessionidscidssciddatapathandfilenametype-get.md)
- [PUT (/trustedplatform/users/xuid({xuid})/scids/{scid}/data/{pathAndFileName},{type})](https://docs.xbox.com/zh-TW/reference/live/rest/uri/storage/uri-trustedplatformusersxuidscidssciddatapathandfilenametype-put.md)
- [PUT (/untrustedplatform/users/xuid({xuid})/scids/{scid}/data/{pathAndFileName},{type})](https://docs.xbox.com/zh-TW/reference/live/rest/uri/storage/uri-untrustedplatformusersxuidscidssciddatapathandfilenametype-put.md)