Listar compartilhamentos

Artigo
08/07/2024

A operação List Shares retorna uma lista de compartilhamentos e instantâneos de compartilhamento na conta especificada. Essa API tem suporte total, mas é uma API de gerenciamento herdada. Use Compartilhamentos de Arquivos – Lista, fornecidos 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 Operations on FileShares.

Disponibilidade do protocolo

Protocolo de compartilhamento de arquivos habilitado	Disponível
SMB
NFS

Pedir

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

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

Substitua os componentes de caminho mostrados no URI da solicitação por seus próprios, da seguinte maneira:

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

Para obter detalhes sobre restrições de nomenclatura de caminho, consulte Nomenclatura e referência a 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 apenas compartilhamentos que têm nomes que começam 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 retornará um valor de marcador dentro do corpo da resposta, se a lista retornada não estiver concluída. 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 compartilhamentos a serem retornados. Se a solicitação não especificar `maxresults`ou 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 em 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 Definir tempos limite para operações de Arquivos do Azure.

Cabeçalhos de solicitação

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

Cabeçalho de 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 UTC (Tempo Universal Coordenado) para a solicitação. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
`x-ms-version`	Necessário para todas as solicitações autorizadas. 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 kib (1 kibibyte) que é registrado nos logs quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Monitorar arquivos do Azure.

Corpo da solicitação

Nenhum.

Resposta

A resposta inclui um código de status HTTP, um conjunto de cabeçalhos de resposta e um corpo de resposta no 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 Status e códigos de erro.

Cabeçalhos de resposta

A resposta dessa operação inclui os cabeçalhos a seguir. 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 de protocolo HTTP/1.1 .

Cabeçalho de 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 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 da 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 somente 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 somente na versão 2015-02-21 e posterior.
Os elementos Version, Deleted, DeletedTimee RemainingRetentionDays aparecem no corpo da resposta somente na versão 2019-12-12 e posterior.
Os elementos Prefix, Markere MaxResults só estarão presentes se você especificá-los no URI. O elemento NextMarker tem um valor somente se os resultados da lista não estiverem concluídos.
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 contém a camada do compartilhamento. Se a camada do compartilhamento não tiver sido alterada, essa propriedade será a camada padrão TransactionOptimized em contas de armazenamento GPv2 (versão de uso geral 2). Nas contas de armazenamento dos 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 o compartilhamento estiver fazendo a transição de uma camada para outra. Indica a camada da qual está fazendo a transição.
O elemento ProvisionedIngressMBps está presente apenas para Premium contas de Arquivos do Azure e a 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 a versão 2019-07-07 ou posterior. Ele mostra a saída provisionada em MiB/s.
O elemento ProvisionedBandwidthMiBps está presente apenas para Premium contas de Arquivos do Azure e a 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 de Arquivos do Azure, 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 de Arquivos do Azure, na versão 2024-11-04 ou posterior. Ele só será retornado se PaidBurstingEnabled for verdadeiro para o compartilhamento. Esse elemento será retornado apenas para compartilhamentos, não para instantâneos.
O elemento PaidBurstingMaxBandwidthMibps está presente apenas para Premium contas de Arquivos do Azure, na versão 2024-11-04 ou posterior. Ele só será retornado se PaidBurstingEnabled for verdadeiro para o compartilhamento. Esse elemento será retornado apenas para compartilhamentos, não para instantâneos.

Resposta de exemplo

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

Autorização

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

Observações

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. Esse elemento indica o próximo compartilhamento a ser retornado 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.

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

Os compartilhamentos são listados em ordem alfabética no corpo da resposta.

A operação List Shares atinge o tempo limite após 30 segundos.

Solicitação e resposta de exemplo

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

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

A solicitação é enviada 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 essa 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

Consulte também

API REST dos Arquivos do Azure

Compartilhar via