放置範圍

發行項
03/29/2023

Put Range 作業會將一連串位元組寫入檔案。

通訊協定可用性

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

要求

Put Range 要求的建構如下。建議您使用 HTTPS。

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

將要求 URI 中的路徑元件取代為您自己的路徑元件，如下所示：

路徑元件	描述
`myaccount`	儲存體帳戶的名稱。
`myshare`	檔案共用的名稱。
`mydirectorypath`	選擇性。上層目錄的路徑。
`myfile`	檔案的名稱。

如需路徑命名限制的相關資訊，請參閱名稱和參考共用、目錄、檔案和中繼資料。

URI 參數

您可以在要求的 URI 中指定下列其他參數。

參數	描述
`timeout`	選擇性。 `timeout` 參數以秒為單位。如需詳細資訊，請參閱設定檔案服務作業的逾時。

要求標頭

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

要求標頭	描述
`Authorization`	必要。指定授權配置、帳戶名稱和簽章。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`Date` 或 `x-ms-date`	必要。指定要求的「國際標準時間」(UTC)。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`x-ms-version`	所有已授權要求都需要。指定用於這個要求的作業版本。如需詳細資訊，請參閱 Azure 儲存體服務的版本。
`Range` 或 `x-ms-range`	需要 `Range` 或 `x-ms-range`。指定要寫入的位元組範圍。您必須指定開始和結束範圍。此標頭是由 HTTP/1.1 通訊協定規格所定義。針對更新作業，範圍的大小上限為 4 MiB。若為清除作業，範圍的值最大可以是檔案的完整大小。檔案服務只接受和 `x-ms-range` 標頭的單一位元組範圍 `Range` ，而且必須以下列格式指定位元組範圍： `bytes=startByte-endByte` 。如果同時指定 `Range` 與 `x-ms-range`，服務會使用 `x-ms-range` 的值。如需詳細資訊，請參閱指定檔案服務作業的範圍標頭。
`Content-Length`	必要。指定要求主體中所傳輸的位元組數目。 `x-ms-write`當標頭設定為 `clear` 時，這個標頭的值必須設定為 `0` 。
`Content-MD5`	選擇性。內容的 MD5 雜湊。在傳輸期間，此雜湊用來驗證資料的完整性。 `Content-MD5`指定標頭時，Azure 檔案儲存體會比較已抵達的內容雜湊與已傳送的標頭值。如果兩個雜湊不相符，作業會失敗，錯誤碼為 400 (不正確的要求) 。 `Content-MD5`當標頭設定為 `clear` 時 `x-ms-write` ，不允許標頭。如果要求隨附于該要求，檔案服務會傳回狀態碼 400 (不正確的要求) 。
`x-ms-write: { update ¦ clear }`	必要。您必須指定下列其中一個選項： `update`：將要求主體所指定的位元組寫入指定的範圍。 `Range` 和 `Content-Length` 標頭必須相符，才能執行更新。 `clear`：清除指定的範圍，並釋放該範圍所使用的儲存空間。若要清除範圍，請將 `Content-Length` 標頭設定為 `0` ，並將標頭設定 `Range` 為值，指出要清除的範圍，最高為檔案大小上限。
`x-ms-lease-id: <ID>`	如果檔案有作用中的租用，則為必要專案。適用于 2019-02-02 版和更新版本。
`x-ms-client-request-id`	選擇性。提供用戶端產生的不透明值，其中包含設定記錄時記錄的 1 kibibyte (KiB) 字元限制。強烈建議您使用此標頭，將用戶端活動與伺服器接收的要求相互關聯。如需詳細資訊，請參閱監視Azure 檔案儲存體。
`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` 指定，如果在指派給使用 `Authorization` 標頭授權的身分識別的 RBAC 原則中包含，則應該授與或 `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` 。適用于 2022-11-02 版和更新版本。
`x-ms-allow-trailing-dot: { <Boolean> }`	選擇性。版本 2022-11-02 和更新版本。布林值會指定是否應該修剪要求 URL 中的尾端點。如需詳細資訊，請參閱命名和參考共用、目錄、檔案和中繼資料。

要求本文

代表要上傳之範圍的資料。

範例要求：更新位元組範圍

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1  
  
Request Headers:  
x-ms-write: update  
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT  
x-ms-version: 2014-02-14  
x-ms-range: bytes=0-65535  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 65536

範例要求：清除位元組範圍

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1  
  
Request Headers:  
Range: bytes=1024-2048  
x-ms-write: clear  
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT  
x-ms-version: 2014-02-14  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=

回應

回應包括 HTTP 狀態碼和一組回應標頭。

狀態碼

成功的作業會傳回狀態碼「201 (已建立)」。

如需狀態碼的詳細資訊，請參閱狀態和錯誤碼。

回應標頭

這項作業的回應包括下列標頭。回應也可能包括其他標準 HTTP 標頭。所有標準標頭都符合 HTTP/1.1 通訊協定規格。

回應標頭	描述
`ETag`	ETag 包含值，代表檔案的版本。此值會以引號括住。
`Last-Modified`	傳回上次修改目錄的日期和時間。日期格式會依照 RFC 1123。如需詳細資訊，請參閱代表標頭中的日期/時間值。修改共用或其屬性或中繼資料的任何作業，都會更新上次修改時間。檔案上的作業不會影響共用的上次修改時間。
`Content-MD5`	傳回此標頭，以供用戶端檢查訊息內容完整性。此標頭的值是由檔案服務計算。它不一定與要求標頭中指定的值相同。
`x-ms-request-id`	可唯一識別所做的要求，並可用來對要求進行疑難排解。如需詳細資訊，請參閱針對 API 作業進行疑難排解。
`x-ms-version`	指出用來執行要求的檔案服務版本。
`Date`	服務所產生的 UTC 日期/時間值，表示起始回應的時間。
`x-ms-request-server-encrypted: { true ¦ false }`	版本 2017-04-17 和更新版本。如果使用指定的演算法成功加密要求的內容，這個標頭的值就會設定 `true` 為。否則，會將值設定為 `false`。
`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`.

回應本文

無。

範例回應

Response Status:  
HTTP/1.1 201 Created  

Response Headers:  
Transfer-Encoding: chunked  
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==  
Date:Mon, 27 Jan 2014 22:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Mon, 27 Jan 2014 12:13:31 GMT  
x-ms-version: 2014-02-14  
Content-Length: 0  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0

授權

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

備註

Put Range 作業會將一連串位元組寫入檔案。此作業只能在現有的檔案上呼叫。無法呼叫它來建立新的檔案。使用目前不存在的檔案名呼叫 Put Range 會傳回狀態碼 404 (找不到) 。

若要建立新的檔案，請呼叫建立檔案。檔案的大小最多可達 4 TiB。

Put Range每個 MiB 允許 10 分鐘完成作業。如果作業平均每 MiB 花費超過 10 分鐘的時間，就會逾時。

如果檔案具有作用中的租用，用戶端必須在要求上指定有效的租用識別碼，才能寫入範圍。

範圍更新作業

搭配 Update 選項呼叫 Put Range 可在指定的檔案中執行就地寫入。指定範圍中的所有內容都會以更新的內容覆寫。針對更新作業所 Put Range 提交的每個範圍，大小上限為 4 MiB。如果您嘗試上傳大於 4 MiB 的範圍，服務會傳回狀態碼 413 (要求實體太大) 。

範圍清除作業

搭配 Clear 選項呼叫 Put Range 可釋放儲存體中的空間，但指定的範圍必須是 512 位元組對齊。已清除的範圍不再追蹤為檔案的一部分，也不會在清單範圍回應中傳回。如果指定的範圍未對齊 512 位元組，作業會將零寫入未對齊 512 位元組的範圍的開頭或結尾，並釋放該範圍內 512 位元組對齊的其餘部分。

清單範圍回應中會傳回尚未清除的任何範圍。如需範例，請參閱下列「範例未對齊的清除範圍」一節。

檔案租用
您可以呼叫租用檔案，針對其他寫入取得檔案的獨佔寫入鎖定，持續無限期。

SMB 用戶端位元組範圍鎖定

SMB 通訊協定可讓位元組範圍鎖定管理檔案區域的讀取和寫入存取權。這表示 Put Range ，如果 SMB 用戶端具有與使用作業 x-ms-range 所指定的範圍重迭的 Put Range 鎖定，就會失敗。如需詳細資訊，請參閱管理檔案鎖定。

SMB 用戶端目錄變更通知

SMB 通訊協定支援 FindFirstChangeNotification API 函式，可讓應用程式偵測檔案系統中發生變更的時間。它可以偵測檔案或目錄新增、變更或刪除，以及檔案的大小、屬性或安全性描述元變更時。當檔案或目錄變更透過 Azure 檔案儲存體 REST API 發生時，使用此 API 的 SMB 用戶端將不會收到通知。不過，其他 SMB 用戶端所造成的變更會傳播通知。

未對齊的清除範圍範例

假設使用建立檔案建立檔案，並使用撰寫單一範圍 Put Range ，如下所示：

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1  

Request Headers:  
x-ms-write: updte  
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT  
x-ms-version: 2014-02-14  
x-ms-range: bytes=0-65536  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 65536

在檔案上執行清單範圍作業會傳回下列回應本文：

<?xml version="1.0" ecoding="utf-8"?>  
<Ranges>  
<Range>  
<Start>0</Start>  
<End>65536</End>  
</Range>  
</Ranges>

現在假設已執行未對齊的清除範圍位元組範圍作業：

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1  

Request Headers:  
Range: bytes=768-2304  
x-ms-write: clear  
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT  
x-ms-version: 2014-02-14  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=

檔案上的後續清單範圍作業會傳回下列回應本文：

<?xml version="1.0" encoding="utf-8"?>  
<Ranges>  
<Range>  
<Start>0</Start>  
<End>1024</End>  
</Range>  
<Range>  
<Start>2048</Start>  
<End>65535</End>  
</Range>  
</Ranges>

請注意，未對齊的空間 768-1024 和 2048-2304 已寫入零。

Put Range 共用快照集不支援，這是共用的唯讀複本。嘗試在共用快照集上執行此作業失敗， (InvalidQueryParameterValue) 。

另請參閱

檔案的作業