Listar Partilhas

  • Artigo

A List Shares operação devolve uma lista das partilhas e partilha de instantâneos na conta especificada. Esta API é totalmente suportada, mas é uma API de gestão legada. Utilize Partilhas de Ficheiros – Lista, fornecida pelo fornecedor de recursos de armazenamento (Microsoft.Storage), em vez disso. Para saber mais sobre a interação programática com recursos através FileShare do fornecedor de recursos de armazenamento, veja Operações em FileShares.

Disponibilidade do protocolo

Protocolo de partilha de ficheiros ativado Disponível
SMB Yes
NFS Yes

Pedir

Pode construir o pedido da List Shares seguinte forma. É recomendado HTTPS.

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

Substitua os componentes de caminho apresentados no URI do pedido pelo seu, da seguinte forma:

Componente caminho Description
myaccount O nome da sua conta de armazenamento.

Para obter detalhes sobre as restrições de nomenclatura de caminhos, veja Nomenclatura e referência de partilhas, diretórios, ficheiros e metadados.

Parâmetros URI

Pode especificar os seguintes parâmetros adicionais no URI do pedido.

Parâmetro Description
prefix Opcional. Filtra os resultados para devolver apenas as partilhas que têm nomes que começam com o prefixo especificado.
marker Opcional. Um valor de cadeia que identifica a parte da lista a devolver com a operação de lista seguinte. A operação devolve um valor de marcador no corpo da resposta, se a lista devolvida não tiver sido concluída. Em seguida, pode utilizar o valor do marcador numa chamada subsequente para pedir 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 partilhas a devolver. Se o pedido não especificar maxresultsou especificar um valor superior a 5000, o servidor devolverá até 5000 itens. Se o parâmetro estiver definido como um valor inferior ou igual a zero, o servidor devolverá o código de estado 400 (Pedido Incorreto).
include=metadata,snapshots,deleted Opcional. Especifica um ou mais conjuntos de dados a incluir na resposta:

- snapshots: Versão 2017-04-17 e posterior. Especifica que os instantâneos de partilha devem ser incluídos na resposta. Os instantâneos de partilha são listados do mais antigo para o mais recente na resposta.
- metadata: especifica que os metadados de partilha devem ser devolvidos na resposta.
- deleted: especifica que as partilhas de ficheiros eliminadas devem ser incluídas na resposta.

Para especificar mais do que uma destas opções no URI, tem de separar cada opção com uma vírgula codificada por URL ("%82").

Todos os nomes de metadados têm de cumprir as convenções de nomenclatura dos identificadores C#.
timeout Opcional. O timeout parâmetro é expresso em segundos. Para obter mais informações, veja Setting timeouts for Ficheiros do Azure operations (Definir tempos limite para operações de Ficheiros do Azure).

Cabeçalhos do pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Cabeçalho do pedido Description
Authorization Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
Date ou x-ms-date Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
x-ms-version Necessário para todos os pedidos autorizados. Especifica a versão da operação a utilizar para este pedido. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de carateres de 1 kibibyte (KiB) que é registado nos registos quando o registo é configurado. Recomendamos vivamente que utilize este cabeçalho para correlacionar as atividades do lado do cliente com os pedidos que o servidor recebe. Para obter mais informações, veja Monitorizar Ficheiros do Azure.

Corpo do pedido

Nenhum.

Resposta

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

Código de estado

Uma operação bem-sucedida devolve o código de estado 200 (OK). Para obter informações sobre códigos de estado, veja Códigos de estado 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 de resposta Descrição
Content-Type Cabeçalho HTTP/1.1 Padrão. Especifica o formato no qual os resultados são devolvidos. Atualmente, este valor é application/xml.
x-ms-request-id Este cabeçalho identifica exclusivamente o pedido que foi feito e pode ser utilizado para resolver o pedido. Para obter mais informações, veja Resolver problemas de operações da API.
x-ms-version Indica a versão do Ficheiros do Azure utilizada para executar o pedido.
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 este valor.
x-ms-client-request-id Pode utilizar este cabeçalho para resolver problemas de pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho, se estiver presente no pedido. O valor é, no máximo, 1024 carateres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente no pedido, este 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 de resposta apenas na versão 2020-02-10 e posterior.
  • O RootSquash elemento aparece no corpo da resposta apenas na versão 2020-02-10 e posterior, quando os protocolos ativados contêm NFS.
  • O Quota elemento só aparece no corpo da resposta na versão 2015-02-21 e posterior.
  • Os Versionelementos , Deleted, DeletedTimee RemainingRetentionDays aparecem no corpo da resposta apenas na versão 2019-12-12 e posterior.
  • Os Prefixelementos , Markere MaxResults só estão presentes se os especificar no URI. O NextMarker elemento só tem um valor se os resultados da lista não estiverem concluídos.
  • O Metadata elemento só está presente se especificar o include=metadata parâmetro no URI. Metadata No elemento , o valor de cada par nome-valor é listado dentro de um elemento correspondente ao nome do par.
  • Os instantâneos são incluídos na resposta apenas se especificar oinclude=snapshots parâmetro com o include parâmetro no URI do pedido.
  • O AccessTier elemento contém a camada da partilha. Se o escalão da partilha não tiver sido alterado, esta propriedade será o escalão TransactionOptimized predefinido nas contas de armazenamento da versão 2 (GPv2) para fins gerais. No Ficheiros do Azure contas de armazenamento, a propriedade será Premium, que é a única camada suportada.
  • O AccessTierChangeTime elemento só está presente se definir explicitamente a camada de acesso na partilha.
  • O AccessTierTransitionState elemento só está presente se a partilha estiver em transição de uma camada para outra. Indica o escalão a partir do qual está a transitar.
  • O ProvisionedIngressMBps elemento está presente apenas para Premium contas Ficheiros do Azure e versão 2019-07-07 ou posterior. Mostra a entrada aprovisionada em MiB/s.
  • O ProvisionedEgressMBps elemento está presente apenas para Premium contas Ficheiros do Azure e versão 2019-07-07 ou posterior. Mostra a saída aprovisionada em MiB/s.
  • O ProvisionedBandwidthMiBps elemento está presente apenas para Premium contas Ficheiros do Azure e versão 2021-02-12 ou posterior. Mostra a largura de banda aprovisionada (entrada + saída combinada) em MiB/s.

Resposta de amostra

Veja a secção Pedido de exemplo e resposta mais adiante neste tópico.

Autorização

Apenas o proprietário da conta pode chamar esta operação.

Observações

Se especificar um valor para o maxresults parâmetro e o número de partilhas a devolver exceder este valor ou exceder o valor predefinido para maxresults, o corpo da resposta contém um NextMarker elemento. Este elemento indica a partilha seguinte a devolver num pedido subsequente. Para devolver o próximo conjunto de itens, especifique o valor de como o parâmetro de NextMarker marcador no URI para o pedido subsequente.

Tenha em atenção que o valor de NextMarker deve ser tratado como opaco.

As partilhas são listadas por ordem alfabética no corpo da resposta.

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

Pedido e resposta de exemplo

O URI de exemplo seguinte pede a lista de partilhas de uma conta. Define os resultados máximos a devolver 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 estado e os cabeçalhos de resposta são devolvidos 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

O XML de resposta para este pedido é o seguinte. Tenha em atenção que o NextMarker elemento segue o conjunto de partilhas e inclui o nome da partilha seguinte a ser devolvida.

<?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 de lista subsequente especifica o marcador no URI do pedido, da seguinte forma. O próximo conjunto de resultados é devolvido, começando pela partilha especificada pelo marcador.

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

Ver também

Ficheiros do Azure API REST