列出共用

發行項
08/05/2023

作業 List Shares 會傳回指定帳戶下共用和共用快照集的清單。此 API 完全受到支援，但它是舊版管理 API。請改用檔案共用 - 列出儲存體資源提供者所提供的清單， (Microsoft.Storage) 。若要深入瞭解如何使用儲存體資源提供者以程式設計方式與 FileShare 資源互動，請參閱 FileShares 上的作業。

通訊協定可用性

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

要求

您可以依照下列方式建構 List Shares 要求。建議使用 HTTPS。

方法	要求 URI	HTTP 版本
`GET`	`https://myaccount.file.core.windows.net/?comp=list`	HTTP/1.1

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

路徑元件	Description
`myaccount`	儲存體帳戶的名稱。

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

URI 參數

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

參數	描述
`prefix`	選擇性。篩選結果，只傳回名稱開頭為指定前置詞的共用。
`marker`	選擇性。識別下一個清單作業所要傳回之清單部分的字串值。如果傳回的清單未完成，此作業會在回應本文內傳回標記值。然後，您可以在後續呼叫中使用標記值來要求下一組清單專案。此標記值對於用戶端為不透明。
`maxresults`	選擇性。指定要傳回的最大共用數目。如果要求未指定 `maxresults` ，或指定大於 5，000 的值，則伺服器最多會傳回 5，000 個專案。如果參數的值設為小於或等於零，伺服器會傳回狀態碼 400 (不正確的要求)。
`include=metadata,snapshots,deleted`	選擇性。指定一個或多個包含在回應中的資料集： - `snapshots`：版本 2017-04-17 和更新版本。指定回應中應包含共用快照集。共用快照集會從回應中最舊到最新列出。 - `metadata`：指定應該在回應中傳回共用中繼資料。 - `deleted`：指定回應中應包含已刪除的檔案共用。若要在 URI 中指定上述多個選項，您必須以 URL 編碼的逗號 ("%82") 分隔每一個選項。所有中繼資料名稱都必須遵守 C# 識別碼的命名慣例。
`timeout`	選擇性。 `timeout` 參數以秒為單位。如需詳細資訊，請參閱設定Azure 檔案儲存體作業的逾時。

要求標頭

下表描述必要的和選用的要求標頭。

要求標頭	描述
`Authorization`	必要。指定授權配置、帳戶名稱和簽章。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`Date` 或 `x-ms-date`	必要。指定要求的「國際標準時間」(UTC)。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`x-ms-version`	所有授權要求都需要。指定用於這個要求的作業版本。如需詳細資訊，請參閱 Azure 儲存體服務的版本。
`x-ms-client-request-id`	選擇性。提供用戶端產生的不透明值，其中包含 1-kibibyte (KiB) 設定記錄時記錄在記錄中的字元限制。強烈建議您使用此標頭，將用戶端活動與伺服器收到的要求相互關聯。如需詳細資訊，請參閱監視Azure 檔案儲存體。

要求本文

無。

回應

回應包括 HTTP 狀態碼、一組回應標頭和 XML 格式的回應主體。

狀態碼

成功的作業會傳回狀態碼 200 (OK)。如需狀態碼的相關資訊，請參閱狀態和錯誤碼。

回應標頭

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

回應標頭	描述
`Content-Type`	標準 HTTP/1.1 標頭。指定傳回結果的格式。目前，此值為 `application/xml` 。
`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`如果要求中沒有標頭，則此標頭不會出現在回應中。

回應本文

回應本文的格式如下。

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults AccountName="https://myaccount.file.core.windows.net">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Shares>  
    <Share>  
      <Name>share-name</Name>  
      <Snapshot>Date-Time Value</Snapshot>
      <Version>01D2AC0C18EDFE36</Version> 
      <Deleted>true</Deleted>  
      <Properties>  
        <Last-Modified>date/time-value</Last-Modified>  
        <Etag>etag</Etag>  
        <Quota>max-share-size</Quota>
        <DeletedTime>Mon, 24 Aug 2020 04:56:10 GMT</DeletedTime>  
        <RemainingRetentionDays>360</RemainingRetentionDays>
        <AccessTier>TransactionOptimized</AccessTier>
        <AccessTierChangeTime>Mon, 24 Aug 2020 03:56:10 GMT</AccessTierChangeTime>
        <AccessTierTransitionState>pending-from-cool</AccessTierTransitionState>
        <EnabledProtocols>SMB</EnabledProtocols>
      </Properties>  
      <Metadata>  
        <metadata-name>value</metadata-name>  
      </Metadata>  
    </Share>  
  </Shares>  
  <NextMarker>marker-value</NextMarker>  
</EnumerationResults>

元素 EnabledProtocols 只會在 2020-02-10 版和更新版本中出現在回應本文中。
當啟用的通訊協定包含 NFS 時，元素 RootSquash 才會出現在回應本文中。2020-02-10 版和更新版本。
元素 Quota 只會出現在回應本文 2015-02-21 版和更新版本中。
Version、 DeletedDeletedTime 和 RemainingRetentionDays 元素只會在 2019-12-12 版和更新版本中出現在回應本文中。
Prefix只有在您在 URI 上指定、 Marker 和 MaxResults 元素時，才會存在。只有在清單結果未完成時，元素 NextMarker 才會有值。
Metadata只有在您在 URI 上指定參數時， include=metadata 元素才會存在。在 Metadata 項目中，每個名稱/值組的值會列於與組合名稱對應的項目內。
只有在您在要求 URI 上使用參數來指定 include=snapshots 參數 include 時，快照集才會包含在回應中。
元素 AccessTier 會保存共用的階層。如果共用的層尚未變更，此屬性會是一般用途第 2 版的預設層 TransactionOptimized ， (GPv2) 儲存體帳戶。在Azure 檔案儲存體儲存體帳戶上，屬性會是 Premium ，這是唯一支援的層。
只有在您明確在共用上設定存取層時，才會存在元素 AccessTierChangeTime 。
AccessTierTransitionState只有在共用從一個層轉換到另一層時，才會存在元素。它表示正在轉換的階層。
元素 ProvisionedIngressMBps 僅適用于 Premium Azure 檔案儲存體帳戶，以及 2019-07-07 版或更新版本。它會在 MiB/秒中顯示布建的輸入。
元素 ProvisionedEgressMBps 僅適用于 Premium Azure 檔案儲存體帳戶，以及 2019-07-07 版或更新版本。它會在 MiB/秒中顯示已布建的輸出。
元素 ProvisionedBandwidthMiBps 僅適用于 Premium Azure 檔案儲存體帳戶，以及版本 2021-02-12 或更新版本。它會在 MiB/秒中顯示已布建的頻寬 (輸入 + 輸出結合) 。

範例回應

請參閱本主題稍後的範例要求和回應一節。

授權

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

備註

如果您為參數指定值 maxresults ，而要傳回的共用數目超過此值，或超過的 maxresults 預設值，回應本文會 NextMarker 包含元素。這個專案表示後續要求傳回的下一個共用。若要傳回下一組項目，請指定 NextMarker 的值做為 URI 中的標記參數，以進行後續要求。

請注意，NextMarker 的值應視為不透明。

共用會依字母順序列於回應主體中。

List Shares 作業將於 30 秒後逾時。

範例要求與回應

下列範例 URI 會要求帳戶的共用清單。它會將初始作業傳回的最大結果設定為三。

GET https://myaccount.file.core.windows.net/?comp=list&maxresults=3&include=snapshots HTTP/1.1

所傳送的要求包含下列標頭：

x-ms-version: 2020-02-10  
x-ms-date: <date>  
Authorization: SharedKey myaccount:CY1OP3O3jGFpYFbTCBimLn0Xov0vt0khH/D5Gy0fXvg=

傳回的狀態碼和回應標頭如下：

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: <date>  
x-ms-version: 2020-02-10  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0

此要求的回應 XML 如下。請注意，元素 NextMarker 會遵循共用集，並包含要傳回之下一個共用的名稱。

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint=" https://myaccount.file.core.windows.net">  
  <MaxResults>3</MaxResults>  
  <Shares>  
    <Share>  
      <Name>audio</Name>  
      <Properties>  
        <Last-Modified><date></Last-Modified>  
        <Etag>0x8CACB9BD7C6B1B2</Etag>  
        <Quota>55</Quota>
        <AccessTier>Premium</AccessTier>
        <EnabledProtocols>SMB</EnabledProtocols>
      </Properties>  
    </Share>  
    <Share>  
      <Name>images</Name>  
      <Properties>  
        <Last-Modified><date></Last-Modified>  
        <Etag>0x8CACB9BD7C1EEEC</Etag>
        <AccessTier>Premium</AccessTier>
        <EnabledProtocols>SMB</EnabledProtocols>
      </Properties>  
    </Share>  
    <Share>
      <Name>textfiles</Name>
      <Snapshot>2017-05-12T20:52:22.0000000Z</Snapshot>
      <Properties>
        <Last-Modified><date></Last-Modified>
        <Etag>0x8D3F2E1A9D14700</Etag>
        <Quota>30</Quota>
        <AccessTier>Premium</AccessTier>
        <EnabledProtocols>NFS</EnabledProtocols>
        <RootSquash>RootSquash</RootSquash>
      </Properties>
    </Share>
    <Share>  
      <Name>textfiles</Name>  
      <Properties>  
        <Last-Modified><date></Last-Modified>  
        <Etag>0x8CACB9BD7BACAC3</Etag>  
        <Quota>30</Quota>
        <AccessTier>Premium</AccessTier>
        <EnabledProtocols>NFS</EnabledProtocols>
        <RootSquash>AllSquash</RootSquash>  
      </Properties>  
    </Share>
  </Shares>  
  <NextMarker>video</NextMarker>  
</EnumerationResults>

後續清單作業在要求 URI 中指定標記 (如下所示)。會傳回下一組結果，從標記指定的共用開始。

https://myaccount.file.core.windows.net/?comp=list&maxresults=3&marker=video

另請參閱

Azure 檔案儲存體 REST API