你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

列出共享

项目
07/19/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 中所示的路径组件替换为你自己的组件，如下所示：

路径组件	说明
`myaccount`	存储帐户的名称。

有关路径命名限制的详细信息，请参阅命名和引用共享、目录、文件和元数据。

URI 参数

可以在请求 URI 上指定以下附加参数。

参数	说明
`prefix`	可选。筛选结果以仅返回名称以指定前缀开头的共享。
`marker`	可选。一个字符串值，该值指定要使用下一个列表操作返回的列表部分。如果返回的列表未完成，则操作在响应正文中返回标记值。然后，可以在后续调用中使用标记值来请求下一组列表项。标记值对客户端不透明。
`maxresults`	可选。指定要返回的最大共享数。如果请求未指定 `maxresults`，或指定的值大于 5，000，则服务器将返回最多 5，000 个项目。如果此参数设置为小于或等于 0 的值，服务器将返回状态代码 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-kibite (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>
      </Properties>  
      <Metadata>  
        <metadata-name>value</metadata-name>  
      </Metadata>  
    </Share>  
  </Shares>  
  <NextMarker>marker-value</NextMarker>  
</EnumerationResults>

元素 EnabledProtocols 仅在版本 2020-02-10 及更高版本中显示在响应正文中。
RootSquash当启用的协议包含 NFS 时，元素仅在版本 2020-02-10 及更高版本中显示在响应正文中。
元素 Quota 仅在版本 2015-02-21 及更高版本中显示在响应正文中。
Version、Deleted、 DeletedTime和 RemainingRetentionDays 元素仅在版本 2019-12-12 及更高版本中显示在响应正文中。
PrefixMarker仅当在 URI 上指定、和 MaxResults 元素时，它们才存在。 NextMarker仅当列表结果不完整时，元素才具有值。
Metadata仅当在 URI 上指定参数时，include=metadata元素才存在。在 Metadata 元素中，将在与每个名称-值对的名称对应的元素中列出该对的值。
仅当在请求 URI 上使用参数指定include=snapshots 参数时， include 快照才会包含在响应中。
元素 AccessTier 保存共享的层。如果共享的层尚未更改，则此属性将是常规用途版本 2 (GPv2) 存储帐户的默认层 TransactionOptimized 。在Azure 文件存储存储帐户上，属性将为 Premium，这是唯一支持的层。
AccessTierChangeTime仅当在共享上显式设置访问层时，元素才存在。
AccessTierTransitionState仅当共享从一个层转换到另一层时，元素才存在。它指示从其转换的层。
元素ProvisionedIngressMBps仅适用于 Premium Azure 文件存储帐户以及版本 2019-07-07 或更高版本。它以 MiB/秒显示预配的入口。
元素ProvisionedEgressMBps仅适用于 Premium Azure 文件存储帐户以及版本 2019-07-07 或更高版本。它以 MiB/秒为单位显示预配的出口。
元素ProvisionedBandwidthMiBps仅适用于PremiumAzure 文件存储帐户以及版本 2021-02-12 或更高版本。它以 MiB/秒为单位显示预配的带宽 (入口 + 出口组合) 。

示例响应

请参阅本主题后面的示例请求和响应部分。

授权

只有帐户所有者才能调用此操作。

注解

如果为 maxresults 参数指定值，并且要返回的共享数超过此值，或超过的默认值 maxresults，则响应正文将包含元素 NextMarker 。此元素指示在后续请求中返回的下一个共享。要返回下一组项，请在后续请求的 URI 上将 NextMarker 值指定为标记参数。

请注意，NextMarker 值应视为不透明。

共享将按字母顺序在响应正文中列出。

List Shares 操作将在 30 秒后超时。

示例请求和响应

以下示例 URI 请求帐户的共享列表。它将初始操作返回的最大结果设置为 3。

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