列出共用

發行項
08/07/2024

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

通訊協定可用性

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

請求

您可以建構 List Shares 要求，如下所示。建議使用 HTTPS。

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

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

路徑元件	描述
`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 （確定）。如您需狀態代碼的相關資訊，請參閱狀態和錯誤碼。

回應標頭

此作業的回應包含下列標頭。回應也包含額外的標準 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>
        <PaidBurstingEnabled>true</PaidBurstingEnabled>
        <PaidBurstingMaxIops>20000</PaidBurstingMaxIops>
        <PaidBurstingMaxBandwidthMibps>4000</PaidBurstingMaxBandwidthMibps>
      </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、Deleted、DeletedTime和 RemainingRetentionDays 元素只會出現在 2019-12-12 版和更新版本中的回應本文中。
只有在您在 URI 上指定 Prefix、Marker和 MaxResults 元素時，才會存在。只有當清單結果未完成時，NextMarker 元素才會有值。
只有在您在 URI 上指定 include=metadata 參數時，才會顯示 Metadata 專案。在 Metadata 元素內，每個名稱/值組的值都會列在對應至配對名稱的專案內。
只有當您在要求 URI 上以 include 參數指定include=snapshots 參數時，才會在回應中包含快照集。
AccessTier 元素會保存共用的階層。如果共用的層尚未變更，此屬性將是一般用途第 2 版（GPv2）儲存體帳戶上的預設層 TransactionOptimized。在 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/秒中布建的頻寬（輸入 + 輸出合併）。
當啟用的通訊協定包含 NFS 時，EnableSnapshotVirtualDirectoryAccess 元素只會出現在回應本文中。2024-08-04 版和更新版本。這個元素只會針對共用傳回，而不是針對快照集傳回。
PaidBurstingEnabled 元素僅適用於 2024-11-04 版或更新版本中 Premium Azure 檔案記憶體帳戶。這個元素只會針對共用傳回，而不是針對快照集傳回。
PaidBurstingMaxIops 元素僅適用於 2024-11-04 版或更新版本中 Premium Azure 檔案記憶體帳戶。只有在 Share 的 PaidBurstingEnabled 為 true 時，才會傳回它。這個元素只會針對共用傳回，而不是針對快照集傳回。
PaidBurstingMaxBandwidthMibps 元素僅適用於 2024-11-04 版或更新版本中 Premium Azure 檔案記憶體帳戶。只有在 Share 的 PaidBurstingEnabled 為 true 時，才會傳回它。這個元素只會針對共用傳回，而不是針對快照集傳回。

範例回應

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

授權

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

言論

如果您為 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>
      </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

共用方式為