Listar compartilhamentos
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
Version
elementos ,Deleted
,DeletedTime
eRemainingRetentionDays
aparecem no corpo da resposta somente na versão 2019-12-12 e posterior. - Os
Prefix
elementos ,Marker
eMaxResults
só estarão presentes se você especificá-los no URI. ONextMarker
elemento terá um valor somente se os resultados da lista não estiverem concluídos. - O
Metadata
elemento estará presente somente se você especificar oinclude=metadata
parâmetro no URI. No elementoMetadata
, 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 o
include=snapshots
parâmetro com oinclude
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 camadaTransactionOptimized
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 paraPremium
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 paraPremium
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 paraPremium
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