Listar compartilhamentos

Artigo
07/19/2023

A List Shares operação retorna uma lista dos 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, fornecido pelo provedor de recursos de armazenamento (Microsoft.Storage). Para saber mais sobre como interagir programaticamente com FileShare recursos usando o provedor de recursos de armazenamento, consulte Operações em FileShares.

Disponibilidade do protocolo

Protocolo de compartilhamento de arquivos habilitado	Disponível
SMB
NFS

Solicitação

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

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

Substitua os componentes do caminho mostrados no URI da solicitação pelos seus próprios, como segue:

Componente Demarcador	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 de compartilhamentos, diretórios, arquivos e metadados.

Parâmetros do URI

Você pode especificar os seguintes parâmetros adicionais no URI de 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 na lista. A operação retornará um valor de marcador dentro do corpo da resposta, se a lista retornada não tiver sido 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 ao 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 na 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 Configurando tempos limite para operações de Arquivos do Azure.

Cabeçalhos da 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`	Obrigatórios. Especifica o esquema de autorização, o nome da conta e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
`Date` ou `x-ms-date`	Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para saber mais, confira 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 esta 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 Códigos de status e de erro.

Cabeçalhos de resposta

A resposta para esta 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 do protocolo HTTP/1.1.

Cabeçalho de resposta	Descrição
`Content-Type`	Cabeçalho HTTP/1.1 padrão. Especifica o formato em que 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 do 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 será igual ao valor do `x-ms-client-request-id` cabeçalho, se ele estiver presente na solicitação. O valor é, no máximo, 1024 caracteres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho 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>
      </Properties>  
      <Metadata>  
        <metadata-name>value</metadata-name>  
      </Metadata>  
    </Share>  
  </Shares>  
  <NextMarker>marker-value</NextMarker>  
</EnumerationResults>

O EnabledProtocols elemento aparece no corpo da resposta somente na versão 2020-02-10 e posterior.
O RootSquash elemento aparece no corpo da resposta somente na versão 2020-02-10 e posterior, quando os protocolos habilitados contêm NFS.
O Quota elemento aparece no corpo da resposta somente na versão 2015-02-21 e posterior.
Os Versionelementos , Deleted, DeletedTimee RemainingRetentionDays aparecem no corpo da resposta somente na versão 2019-12-12 e posterior.
Os Prefixelementos , Markere MaxResults só estarão presentes se você especificá-los no URI. O NextMarker elemento terá um valor somente se os resultados da lista não estiverem concluídos.
O Metadata elemento estará presente somente se você especificar o include=metadata parâmetro no URI. No elemento Metadata, o valor de cada par de nome-valor é listado em um elemento correspondente ao nome do par.
Os instantâneos serão incluídos na resposta somente se você especificar oinclude=snapshots parâmetro com o include parâmetro no URI de solicitação.
O AccessTier elemento contém a camada do compartilhamento. Se a camada do compartilhamento não tiver sido alterada, essa propriedade será a camada TransactionOptimized padrão em contas de armazenamento GPv2 (versão de uso geral 2). Em Arquivos do Azure contas de armazenamento, a propriedade será Premium, que é a única camada com suporte.
O AccessTierChangeTime elemento estará presente somente se você definir explicitamente a camada de acesso no compartilhamento.
O AccessTierTransitionState elemento estará presente somente se o compartilhamento estiver fazendo a transição de uma camada para outra. Indica a camada da qual está fazendo a transição.
O ProvisionedIngressMBps elemento está presente apenas para Premium contas Arquivos do Azure e versão 2019-07-07 ou posterior. Ele mostra a entrada provisionada em MiB/s.
O ProvisionedEgressMBps elemento está presente apenas para Premium contas Arquivos do Azure e versão 2019-07-07 ou posterior. Ele mostra a saída provisionada em MiB/s.
O ProvisionedBandwidthMiBps elemento está presente apenas para Premium contas Arquivos do Azure e versão 2021-02-12 ou posterior. Ele mostra a largura de banda provisionada (entrada + saída combinada) em MiB/s.

Resposta de exemplo

Consulte a seção Solicitação e resposta de exemplo 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 maxresults parâmetro 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 NextMarker elemento . 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 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 aparecem em ordem alfabética no corpo da resposta.

A operação List Shares expira depois de 30 segundos.

Exemplo de solicitação e resposta

O URI de exemplo a seguir solicita a lista de compartilhamentos de uma conta. Ele define o máximo de resultados 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=

Os cabeçalhos de código de status e de resposta são retornados da seguinte forma:

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

A resposta XML para essa solicitação é a seguinte. Observe que o NextMarker elemento 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>
        <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>

A operação subsequente da lista especifica o marcador no URI de solicitação, da seguinte forma. 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

Confira também

API REST Arquivos do Azure