Listar Partilhas

  • Artigo

A operação List Shares retorna uma lista dos compartilhamentos e instantâneos de compartilhamento na conta especificada. Essa API é totalmente suportada, mas é uma API de gerenciamento herdada. Em vez disso, use File Shares - List, fornecido pelo provedor de recursos de armazenamento (Microsoft.Storage). Para saber mais sobre como interagir programaticamente com recursos FileShare usando o provedor de recursos de armazenamento, consulte Operações em FileShares.

Disponibilidade do protocolo

Protocolo de compartilhamento de arquivos habilitado Disponível
PME Sim
NFS Sim

Solicitar

Você pode construir a solicitação List Shares da seguinte maneira. HTTPS é recomendado.

Método Solicitar URI Versão HTTP
GET https://myaccount.file.core.windows.net/?comp=list HTTP/1.1

Substitua os componentes de caminho mostrados no URI de solicitação pelo seu, da seguinte maneira:

Componente Caminho Descrição
myaccount O nome da sua conta de armazenamento.

Para obter detalhes sobre restrições de nomenclatura de caminho, consulte Nomeando e referenciando compartilhamentos, diretórios, arquivos e metadados.

Parâmetros de URI

Você pode especificar os seguintes parâmetros adicionais no URI da solicitação.

Parâmetro Descrição
prefix Opcional. Filtra os resultados para retornar somente compartilhamentos que tenham nomes que comecem com o prefixo especificado.
marker Opcional. Um valor de cadeia de caracteres que identifica a parte da lista a ser retornada com a próxima operação de lista. A operação retorna um valor de marcador dentro do corpo da resposta, se a lista retornada não estiver completa. Em seguida, você pode usar o valor do marcador em uma chamada subsequente para solicitar o próximo conjunto de itens de lista.

O valor do marcador é opaco para o cliente.
maxresults Opcional. Especifica o número máximo de ações a serem retornadas. Se a solicitação não especificar maxresultsou especificar um valor maior que 5.000, o servidor retornará até 5.000 itens. Se o parâmetro for definido como um valor menor ou igual a zero, o servidor retornará o código de status 400 (Solicitação incorreta).
include=metadata,snapshots,deleted Opcional. Especifica um ou mais conjuntos de dados a serem incluídos na resposta:

- snapshots: Versão 2017-04-17 e posterior. Especifica que os instantâneos de compartilhamento devem ser incluídos na resposta. Os instantâneos de compartilhamento são listados do mais antigo para o mais recente na resposta.
- metadata: Especifica que os metadados de compartilhamento devem ser retornados na resposta.
- deleted: Especifica que os compartilhamentos de arquivos excluídos devem ser incluídos na resposta.

Para especificar mais de uma dessas opções no URI, você deve separar cada opção com uma vírgula codificada por URL ("%82").

Todos os nomes de metadados devem aderir às convenções de nomenclatura para identificadores C#.
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Definindo tempos limite para operações do Azure Files.

Cabeçalhos de solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.

Cabeçalho da solicitação Descrição
Authorization Necessário. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
Date ou x-ms-date Necessário. Especifica o Tempo Universal Coordenado (UTC) para a solicitação. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
x-ms-version Obrigatório para todos os pedidos autorizados. Especifica a versão da operação a ser usada para essa solicitação. Para obter mais informações, consulte controle de versão para os serviços de Armazenamento do Azure.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres de 1 kibibyte (KiB) que é registrado nos logs quando o log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações que o servidor recebe. Para obter mais informações, consulte Monitorar arquivos do Azure.

Corpo do pedido

Nenhuma.

Resposta

A resposta inclui um código de status HTTP, um conjunto de cabeçalhos de resposta e um corpo de resposta em formato XML.

Código de status

Uma operação bem-sucedida retorna o código de status 200 (OK). Para obter informações sobre códigos de status, consulte Códigos de status e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os seguintes cabeçalhos. A resposta também inclui cabeçalhos HTTP padrão adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Cabeçalho da resposta Descrição
Content-Type Cabeçalho HTTP/1.1 padrão. Especifica o formato no qual os resultados são retornados. Atualmente, esse valor é application/xml.
x-ms-request-id Esse cabeçalho identifica exclusivamente a solicitação que foi feita e pode ser usado para solucionar problemas da solicitação. Para obter mais informações, consulte Solução de problemas de operações de API.
x-ms-version Indica a versão dos Arquivos do Azure usada para executar a solicitação.
Date ou x-ms-date Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera esse valor.
x-ms-client-request-id Você pode usar esse cabeçalho para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho é igual ao valor do cabeçalho x-ms-client-request-id, se ele estiver presente na solicitação. O valor é, no máximo, 1024 caracteres ASCII visíveis. Se o cabeçalho x-ms-client-request-id não estiver presente na solicitação, esse cabeçalho não estará presente na resposta.

Corpo de resposta

O formato do corpo da resposta é o seguinte.

<?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>
  • O elemento EnabledProtocols aparece no corpo da resposta apenas na versão 2020-02-10 e posterior.
  • O elemento RootSquash aparece no corpo da resposta somente na versão 2020-02-10 e posterior, quando os protocolos habilitados contêm NFS. Esse elemento será retornado apenas para compartilhamentos, não para instantâneos.
  • O elemento Quota aparece no corpo da resposta apenas na versão 2015-02-21 e posterior.
  • Os elementos Version, Deleted, DeletedTimee RemainingRetentionDays aparecem no corpo da resposta apenas na versão 2019-12-12 e posterior.
  • Os elementos Prefix, Markere MaxResults só estarão presentes se você os especificar no URI. O elemento NextMarker tem um valor somente se os resultados da lista não estiverem completos.
  • O elemento Metadata estará presente somente se você especificar o parâmetro include=metadata no URI. Dentro do elemento Metadata, o valor de cada par nome-valor é listado dentro de um elemento correspondente ao nome do par.
  • Os instantâneos serão incluídos na resposta somente se você especificar o parâmetroinclude=snapshots com o parâmetro include no URI da solicitação.
  • O elemento AccessTier mantém a camada da ação. Se a camada do compartilhamento não tiver sido alterada, essa propriedade será a camada padrão TransactionOptimized em contas de armazenamento de uso geral versão 2 (GPv2). Nas contas de armazenamento de Arquivos do Azure, a propriedade será Premium, que é a única camada com suporte.
  • O elemento AccessTierChangeTime estará presente somente se você definir explicitamente a camada de acesso no compartilhamento.
  • O elemento AccessTierTransitionState só estará presente se a partilha estiver a transitar de um nível para outro. Ele indica a camada da qual está fazendo a transição.
  • O elemento ProvisionedIngressMBps está presente apenas para Premium contas de Arquivos do Azure e versão 2019-07-07 ou posterior. Ele mostra a entrada provisionada em MiB/s.
  • O elemento ProvisionedEgressMBps está presente apenas para Premium contas de Arquivos do Azure e versão 2019-07-07 ou posterior. Mostra a saída provisionada em MiB/s.
  • O elemento ProvisionedBandwidthMiBps está presente apenas para Premium contas do Azure Files e versão 2021-02-12 ou posterior. Ele mostra a largura de banda provisionada (entrada + saída combinada) em MiB/s.
  • O elemento EnableSnapshotVirtualDirectoryAccess aparece no corpo da resposta somente na versão 2024-08-04 e posterior, quando os protocolos habilitados contêm NFS. Esse elemento será retornado apenas para compartilhamentos, não para instantâneos.
  • O elemento PaidBurstingEnabled está presente apenas para Premium contas do Azure Files, na versão 2024-11-04 ou posterior. Esse elemento será retornado apenas para compartilhamentos, não para instantâneos.
  • O elemento PaidBurstingMaxIops está presente apenas para Premium contas do Azure Files, na versão 2024-11-04 ou posterior. Ele só será retornado se PaidBurstingEnabled for true para o compartilhamento. Esse elemento será retornado apenas para compartilhamentos, não para instantâneos.
  • O elemento PaidBurstingMaxBandwidthMibps está presente apenas para Premium contas do Azure Files, na versão 2024-11-04 ou posterior. Ele só será retornado se PaidBurstingEnabled for true para o compartilhamento. Esse elemento será retornado apenas para compartilhamentos, não para instantâneos.

Resposta da amostra

Consulte a seção Exemplo de solicitação e resposta mais adiante neste tópico.

Autorização

Somente o proprietário da conta pode chamar essa operação.

Comentários

Se você especificar um valor para o parâmetro maxresults e o número de compartilhamentos a serem retornados exceder esse valor ou exceder o valor padrão para maxresults, o corpo da resposta conterá um elemento NextMarker. Este elemento indica a próxima ação a ser retornada em uma solicitação subsequente. Para retornar o próximo conjunto de itens, especifique o valor de NextMarker como o parâmetro de marcador no URI para a solicitação subsequente.

Note que o valor de NextMarker deve ser tratado como opaco.

As ações são listadas em ordem alfabética no corpo da resposta.

A operação List Shares expira após 30 segundos.

Exemplo de solicitação e resposta

O URI de exemplo a seguir solicita a lista de compartilhamentos para uma conta. Ele define os resultados máximos a serem retornados para a operação inicial para três.

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

O pedido é enviado com estes cabeçalhos:

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

O código de status e os cabeçalhos de resposta são retornados da seguinte maneira:

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

O XML de resposta para esta solicitação é o seguinte. Observe que o elemento NextMarker segue o conjunto de compartilhamentos e inclui o nome do próximo compartilhamento a ser retornado.

<?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>

A operação de lista subsequente especifica o marcador no URI da solicitação, da seguinte maneira. O próximo conjunto de resultados é retornado, começando com o compartilhamento especificado pelo marcador.

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

Ver também

API REST de Arquivos do Azure