從 URL 放置範圍

發行項
02/21/2025

Put Range From URL 作業會建立要認可的新範圍，做為從URL讀取內容的檔案的一部分。啟用SMB通訊協定的檔案共享 2019-02-02 版和更新版本支援這項作業，並在2025-05-05版和更新版本中支援啟用 NFS 通訊協定的檔案共用。

通訊協定可用性

已啟用檔案共享通訊協定	可用
SMB
NFS

請求

Put Range From URL 要求建構方式如下。建議您使用 HTTPS。

方法	要求 URI	HTTP 版本
放	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range`	HTTP/1.1

以您自己的方式取代要求 URI 中顯示的路徑元件，如下所示：

路徑元件	描述
`myaccount`	記憶體帳戶的名稱。
`myshare`	檔案共享的名稱。
`mydirectorypath`	自選。父目錄的路徑。
`myfile`	檔名。

如需路徑命名限制的相關信息，請參閱名稱和參考共用、目錄、檔案和元數據。

URI 參數

參數	描述
`timeout`	自選。 `timeout` 參數是以秒為單位來表示。如需詳細資訊，請參閱設定 Azure 檔案服務的逾時。

要求標頭

下表說明必要和選擇性的要求標頭：

常見的要求標頭

要求標頭	描述
`Authorization`	必填。指定授權配置、帳戶名稱和簽章。如需詳細資訊，請參閱授權對 Azure 記憶體的要求。
`Date` 或 `x-ms-date`	必填。指定要求的國際標準時間（UTC）。如需詳細資訊，請參閱授權對 Azure 記憶體的要求。
`x-ms-version`	所有已授權要求的必要專案。指定要用於此要求的作業版本。啟用SMB通訊協定的檔案共享 2019-02-02 版和更新版本支援這項作業，並在2025-05-05版和更新版本中支援啟用 NFS 通訊協定的檔案共用。如需詳細資訊，請參閱 Azure 記憶體服務的版本設定。
`x-ms-copy-source:name`	必填。指定來源檔案的 URL。此值的長度可能高達 2 KiB，可指定檔案。此值應該以 URL 編碼，因為它會出現在要求 URI 中。來源檔案必須是公用檔案，或必須透過共用存取簽章獲得授權。如果來源檔案是公用的，則不需要授權才能執行作業。以下是來源物件 URL 的一些範例： `https://myaccount.file.core.windows.net/myshare/mydir/myfile` `https://myaccount.file.core.windows.net/myshare/mydir/myfile?<sastoken>`
`x-ms-copy-source-authorization: <scheme> <signature>`	自選。指定複製來源的授權配置和簽章。如需詳細資訊，請參閱授權對 Azure 記憶體的要求。只有Microsoft Entra 支援配置持有人。 2020-10-02 版和更新版本支援此標頭。
`x-ms-write: { update }`	必填。您必須只指定 `update`。如果以 `clear`呼叫要求，則要求會失敗。 `update` 值會將要求本文所指定的位元組寫入指定的範圍。
`Range` 或 `x-ms-range`	必填。需要 `Range` 或 `x-ms-range`。指定要寫入的位元組範圍。必須指定範圍的開始和結尾。此標頭是由 HTTP/1.1 通訊協定規格所定義。針對更新作業，範圍的大小上限為 4 MiB。 Azure 檔案服務只接受 `Range` 和 `x-ms-range` 標頭的單一位元組範圍，且位元組範圍必須以下列格式指定：`bytes=startByte-endByte`。如果同時指定 `Range` 和 `x-ms-range`，服務會使用 `x-ms-range`的值。如需詳細資訊，請參閱指定 Azure 檔案服務作業的範圍標頭。
`x-ms-source-range`	必填。指定要從來源讀取的位元組範圍。必須指定範圍的開始和結尾。 Azure 檔案服務只接受 `Range` 和 `x-ms-range` 標頭的單一位元組範圍，且位元組範圍必須以下列格式指定：`bytes=startByte-endByte`。來源範圍的大小上限為 4 MiB。如果來源範圍大小超過 4 MiB，Azure 檔案服務會傳回狀態代碼 413（要求實體太大）。如果來源範圍大小不符合範圍（目標範圍）大小，服務會傳回狀態代碼 400 （不正確的要求）。
`Content-Length`	必填。指定要在要求主體中傳輸的位元組數目。這個標頭的值必須設定為 `0`。當長度未 `0`時，作業會失敗，狀態代碼為 400 （不正確的要求）。
`x-ms-client-request-id`	自選。提供客戶端產生的不透明值，其中包含設定記錄時記錄的 1-kibibyte （KiB）字元限制。強烈建議您使用此標頭，將用戶端活動與伺服器接收的要求相互關聯。如需詳細資訊，請參閱監視 Azure 檔案服務。
`x-ms-source-content-crc64`	自選。 URI 中指定範圍的CRC64哈希。此哈希是用來驗證從 URI 傳輸數據期間範圍的完整性。指定此標頭時，Azure 檔案服務會比較從複製來源與這個標頭值抵達的內容哈希。附注：此 CRC64 哈希不會與檔案一起儲存。如果兩個哈希不相符，作業會失敗，錯誤碼為 400 （不正確的要求）。
`x-ms-source-if-match-crc64`	自選。 CRC64 總和檢查碼值。指定此標頭，只有在從提供總和檢查碼讀取來源相符的指定範圍總和檢查碼時，才執行作業。如果不符合指定的條件，Azure 檔案服務會傳回狀態代碼 412（前置條件失敗）。
`x-ms-source-if-none-match-crc64`	自選。 CRC64 總和檢查碼值。只有在從來源讀取之指定範圍的總和檢查碼與提供的總和檢查碼不同時，才指定此標頭來執行作業。如果不符合指定的條件，Azure 檔案服務會傳回狀態代碼 412（前置條件失敗）。
`x-ms-lease-id: <ID>`	如果檔案具有使用中租用，則為必要專案。適用於 2019-02-02 版和更新版本。如果檔案位於已啟用 NFS 通訊協定的檔案共用上，則忽略此標頭，這不支援檔案租用。
`x-ms-client-request-id`	自選。提供客戶端產生的不透明值，其中包含 1-kibibyte （KiB）字元限制，這會在啟用 Azure 記憶體分析記錄時記錄在分析記錄中。強烈建議您在將用戶端活動與伺服器所接收的要求相互關聯時，請使用此標頭。如需詳細資訊，請參閱監視 Blob 記憶體。
`x-ms-file-last-write-time: { now ¦ preserve }`	自選。版本 2021-06-08 和更新版本。您可以指定下列其中一個選項： `now`：預設值。將上次寫入時間時間戳更新為要求的時間。 `preserve`：保留現有的上次寫入時間戳不變。
`x-ms-file-request-intent`	如果 `Authorization` 標頭指定 OAuth 令牌，則為必要項。可接受的值為 `backup`。如果 `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` 或 `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` 包含在指派給使用 `Authorization` 標頭授權的身分識別中，則此標頭指定應授與 `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` 或 `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action`。適用於 2022-11-02 版和更新版本。
`x-ms-allow-trailing-dot: { <Boolean> }`	自選。版本 2022-11-02 和更新版本。布爾值會指定是否應該修剪要求 URL 中的尾端點。如果目標位於已啟用 NFS 通訊協定的檔案共用上，預設支援尾端點，則會忽略此標頭。如需詳細資訊，請參閱命名和參考共用、目錄、檔案和元資料。
`x-ms-source-allow-trailing-dot: { <Boolean> }`	自選。版本 2022-11-02 和更新版本。布爾值會指定是否應該修剪來源 URL 中的尾端點。只有當複製來源位於 Azure 檔案共用上時，才應該指定此標頭。任何其他複製來源類型都不支援此標頭。如果複製來源位於已啟用NFS通訊協定的檔案共用上，預設支援尾端點，則會忽略此標頭。如需詳細資訊，請參閱命名和參考共用、目錄、檔案和元資料。

僅限SMB要求標頭

沒有。

僅限 NFS 要求標頭

沒有。

要求本文

沒有要求本文。

範例要求

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/mydir/myfile?comp=range HTTP/1.1  
  
Request Headers:  
x-ms-page-write: update  
x-ms-copy-source: http://myaccount2.file.core.windows.net/myshare2/mydirectory2/myfile2?sv=2018-11-09&sp=r&sr=s&se=2018-08-22T09%3A59%3A28.2185790Z&sig=Qn6QEET3Gn%2FhCEVcXuwG7ssatIYiYRM5pNIy4Q3N0cQ%3D 
x-ms-date: Fri, 22 Aug 2018 01:15:50 GMT  
x-ms-version: 2019-02-02 
x-ms-range: bytes=100-1023  
x-ms-source-range: bytes=200-1123  
x-ms-source-content-crc64: 3bedb8b3730fc205 
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 0

回應

回應包含 HTTP 狀態代碼和一組響應標頭。

狀態代碼

成功的作業會傳回狀態代碼 201 （已建立）。如您需狀態代碼的詳細資訊，請參閱狀態和錯誤碼。

回應標頭

此作業的回應包含下表中的標頭。回應也可能包含額外的標準 HTTP 標頭。所有標準標頭都符合 HTTP/1.1 通訊協定規格，。

常見的響應標頭

回應標頭	描述
`ETag`	包含值，可用來有條件地執行作業。值會以引弧括住。
`Last-Modified`	上次修改檔案的日期和時間。日期格式遵循 RFC 1123。如需詳細資訊，請參閱標頭中的日期/時間值的表示。檔案上的任何寫入作業，包括檔案元數據或屬性的更新，會變更檔案的上次修改時間。
`x-ms-request-id`	唯一識別已提出的要求，而且您可以使用它來針對要求進行疑難解答。如需詳細資訊，請參閱針對 API 作業進行疑難解答。
`x-ms-version`	指出用來執行要求的 FileREST API 版本。
`Date`	服務所產生的 UTC 日期/時間值，表示起始響應的時間。
`x-ms-content-crc64`	傳回，讓用戶端可以檢查訊息內容完整性。此標頭的值是由 Azure 檔案服務所計算。它不一定與要求標頭中指定的值相同。
`x-ms-client-request-id`	可用來針對要求和對應的回應進行疑難解答。如果此標頭存在於要求中，則這個標頭的值等於 `x-ms-client-request-id` 標頭的值，而且值包含不超過 1,024 個可見的 ASCII 字元。如果要求中沒有 `x-ms-client-request-id` 標頭，它就不會出現在回應中。
`x-ms-file-last-write-time`	版本 2021-06-08 和更新版本。檔案的最後寫入時間，格式為 ISO 8601 （例如，`2017-05-10T17:52:33.9551861Z`）。

僅限SMB回應標頭

沒有。

僅限 NFS 回應標頭

沒有。

回應本文

沒有。

範例回應

Response Status:  
HTTP/1.1 201 Created  

Response Headers:
Date: Sun, 22 Aug 2020 01:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Wed, 22 Aug 2020 01:13:31 GMT  
x-ms-version: 2019-02-02
x-ms-content-crc64: 3bedb8b3730fc205 
Content-Length: 0  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0

授權

只有帳戶擁有者可以呼叫這項作業。

言論

Put Range From URL 作業會將一系列數據寫入檔案，而且與 Put Range 作業的行為類似。它會使用指定來源上的 Get File 作業來讀取來源檔案的數據、元數據和其他屬性。在 2020-10-02 版和更新版本中，複製作業的來源支援Microsoft Entra 授權。

只有當指定的範圍寫入檔案時，Put Range From URL 作業才會傳回成功 201（已建立）。

另請參閱

檔案上的作業

共用方式為