清單範圍

發行項
02/20/2025

List Ranges 作業會傳回檔案的有效範圍清單。啟用 NFS 通訊協定的檔案共用版本 2025-05-05 和更新版本支援這項作業。

通訊協定可用性

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

請求

List Ranges 要求建構方式如下。建議您使用 HTTPS。

方法	要求 URI	HTTP 版本
獲取	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist`	HTTP/1.1
獲取	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist`	HTTP/1.1
獲取	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime>`	HTTP/1.1
獲取	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&prevsharesnapshot=<DateTime>`	HTTP/1.1

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

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

如需路徑命名限制的詳細資訊，請參閱命名和參考共用、目錄、檔案和元資料。

URI 參數

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

參數	描述
`sharesnapshot`	自選。版本 2017-04-17 和更新版本。 `sharesnapshot` 參數是一個不透明的 `DateTime` 值，當存在時，會指定要查詢檔案的共用快照集。
`timeout`	自選。 `timeout` 參數是以秒為單位來表示。如需詳細資訊，請參閱設定 Azure 檔案服務的逾時。
`prevsharesnapshot`	2020-02-10 版和更新版本中為選擇性。 `prevsharesnapshot` 參數是不透明的 `DateTime` 值，當存在時，會指定先前的快照集。當此參數和 `sharesnapshot` 都存在時，回應只會包含兩個快照集之間變更的頁面範圍。當只有 `prevsharesnapshot` 存在時，回應只會包含在此快照集與即時共用之間變更的頁面範圍。已變更的頁面包括已更新和已清除的頁面。

要求標頭

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

常見的要求標頭

要求標頭	描述
`Authorization`	必填。指定授權配置、帳戶名稱和簽章。如需詳細資訊，請參閱授權對 Azure 記憶體的要求。
`Date` 或 `x-ms-date`	必填。指定要求的國際標準時間（UTC）。如需詳細資訊，請參閱授權對 Azure 記憶體的要求。
`x-ms-version`	所有已授權要求的必要專案。指定要用於此要求的作業版本。啟用 NFS 通訊協定的檔案共用版本 2025-05-05 和更新版本支援這項作業。如需詳細資訊，請參閱 Azure 記憶體服務的版本設定。
`Range`	自選。指定要列出範圍之位元組的範圍，包含範圍。如果省略，則會傳回檔案的所有範圍。
`x-ms-range`	自選。指定要列出範圍之位元組的範圍，包含範圍。如果同時指定 `Range` 和 `x-ms-range` 標頭，服務會使用 `x-ms-range`的值。如需詳細資訊，請參閱指定 Azure 檔案服務作業的範圍標頭。
`x-ms-lease-id:<ID>`	自選。版本 2019-02-02 和更新版本。如果指定標頭，則只有在檔案的租用目前為使用中時，才會執行作業，而要求中指定的租用標識符符合檔案的租用標識符。否則，作業會失敗，狀態代碼為 412（前置條件失敗）。如果檔案位於已啟用 NFS 通訊協定的檔案共用上，則忽略此標頭，這不支援檔案租用。
`x-ms-client-request-id`	自選。提供客戶端產生的不透明值，其中包含設定記錄時記錄的 1-kibibyte （KiB）字元限制。強烈建議您使用此標頭，將用戶端活動與伺服器接收的要求相互關聯。如需詳細資訊，請參閱監視 Azure 檔案服務。
`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-file-support-rename: { <Boolean> }`	自選。 2024-05-04 版和更新版本支援。只有當 `prevsharesnapshot` 查詢參數存在時，才允許此標頭。布爾值會決定當上一個快照集中的檔案位置與要求 URI 中的位置不同時，是否應該列出檔案的變更範圍，因為重新命名或移動作業。如果值為 true，則會傳回檔案的有效變更範圍。如果值為 false，作業將會導致失敗，併產生 409 （衝突）回應。默認值為 false。

僅限SMB要求標頭

沒有。

僅限 NFS 要求標頭

沒有。

要求本文

沒有。

回應

回應包含 HTTP 狀態代碼、一組響應標頭，以及 XML 格式的回應本文。

狀態代碼

成功的作業會傳回狀態代碼 200 （確定）。如您需狀態代碼的相關資訊，請參閱狀態和錯誤碼。

回應標頭

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

常見的響應標頭

回應標頭	描述
`Last-Modified`	上次修改檔案的日期/時間。修改檔案的任何作業，包括檔案元數據或屬性的更新，會變更檔案的上次修改時間。
`ETag`	`ETag` 包含值，以引號表示檔案的版本。
`x-ms-content-length`	以位元組為單位的檔案大小。當 `prevsharesnapshot` 存在時，值會描述位於 `sharesnapshot` 的檔案大小（如果 `sharesnapshot` 查詢參數存在）。否則，它會描述即時檔案的大小。
`x-ms-request-id`	此標頭可唯一識別已提出的要求，並可用於對要求進行疑難解答。如需詳細資訊，請參閱針對 API 作業進行疑難解答。
`x-ms-version`	指出用來執行要求的 Azure 檔案服務版本。
`Date` 或 `x-ms-date`	UTC 日期/時間值，指出起始響應的時間。服務會產生此值。
`x-ms-client-request-id`	您可以使用此標頭來針對要求和對應的回應進行疑難解答。如果要求中有 `x-ms-client-request-id` 標頭的值，則此標頭的值等於。此值最多為1024個可見的ASCII字元。如果要求中沒有 `x-ms-client-request-id` 標頭，此標頭就不會出現在回應中。

僅限SMB回應標頭

沒有。

僅限 NFS 回應標頭

沒有。

回應本文

回應本文包含非重疊有效範圍的清單，依遞增位址範圍排序。回應本文的格式如下。

<?xml version="1.0" encoding="utf-8"?>  
<Ranges>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
</Ranges>

如果已清除檔案的整個範圍集，響應主體將不會包含任何範圍。

如果指定 prevsharesnapshot，回應只會包含目標快照集（或實時檔案）與上一個快照集之間的差異頁面。傳回的範圍包括已更新或清除的兩個範圍。此回應的格式如下所示：

<?xml version="1.0" encoding="utf-8"?> 
<Ranges> 
  <Range> 
    <Start>Start Byte</Start> 
    <End>End Byte</Start> 
  </Range> 
  <ClearRange> 
    <Start>Start Byte</Start>
    <End>End Byte</Start> 
  </ClearRange> 
  <Range> 
    <Start>Start Byte</Start> 
    <End>End Byte</Start> 
  </Range> 
</Ranges>

如果已清除檔案的整組頁面，且未指定 prevsharesnapshot 參數，響應主體將不會包含任何範圍。

授權

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

言論

每個範圍的開始和結束位元組位移都是內含的。請參閱 Range Update Operations 和 Range Clear Operations 範例，以取得 Put Range。這些範例顯示如果您從檔案寫入或清除 512 未對齊的位元組範圍，則會傳回哪些範圍。

在具有大量寫入的高片段檔案中，List Ranges 要求可能會因為內部伺服器逾時而失敗。擷取具有大量寫入作業之檔案範圍的應用程式應該一次擷取範圍的子集。

從 2020-02-10 版開始，您可以使用 prevsharesnapshot 參數呼叫 List Ranges。這會傳回即時檔案與快照集之間的差異範圍，或快照集上檔案的兩個快照集。藉由使用這些範圍差異，您可以擷取檔案的累加快照集。如果您想要實作自己的備份解決方案，增量快照集是備份檔案符合成本效益的方式。

呼叫檔案以擷取增量快照集時，檔案上的某些作業會導致 List Ranges 失敗。服務會傳回：

如果您在其中一個快照集中不存在的檔案上呼叫，則為 404 （找不到），如果未指定 sharesnapshot，則為即時。
409 （衝突）如果您在快照集 之後覆寫複製的目標檔案上呼叫，prevsharesnapshot所指定。
409 （衝突）如果您在擷取 prevsharesnapshot 所指定的快照集之後，以相同的名稱和位置來刪除並重新建立的檔案。

另請參閱

檔案上的作業

共用方式為