Exportar (0) Imprimir
Expandir Tudo

Listar blobs

Atualizado: fevereiro de 2014

A operação List Blobs enumera a lista de blobs no contêiner especificado.

A solicitação List Blobs pode ser criada da seguinte maneira. HTTPS é recomendado. Substitua myaccount pelo nome da sua conta de armazenamento:

 

Método URI de solicitação Versão de HTTP

GET

https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list

HTTP/1.1

Ao fazer uma solicitação no serviço de armazenamento emulado, especifique o nome de host do emulador e a porta do serviço Blob como 127.0.0.1:10000, seguido pelo nome da conta de armazenamento emulado:

 

Método URI de solicitação Versão de HTTP

GET

http://127.0.0.1:10000/devstoreaccount1/mycontainer?restype=container&comp=list

HTTP/1.1

Para obter mais informações, consulte Uso do Azure Storage Emulator para desenvolvimento e testes.

Os seguintes parâmetros adicionais podem ser especificados no URI.

 

Parâmetro Descrição

prefix

Opcional. Filtra os resultados para retornar apenas os blobs cujos nomes começam com o prefixo especificado.

delimiter

Opcional. Quando a solicitação inclui esse parâmetro, a operação retorna um elemento BlobPrefix no corpo de resposta que atua como um espaço reservado para todos os blobs cujos nomes começam com a mesma subcadeia de caracteres até o aparecimento do caractere delimitador. O delimitador pode ser um único caractere ou uma cadeia de caracteres.

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 de resposta se a lista retornada não estiver completa. O valor de marcador pode ser usado em uma chamada subsequente para solicitar o próximo conjunto de itens da lista.

O valor do marcador é opaco ao cliente.

maxresults

Opcional. Especifica o número máximo de blobs a ser retornado, inclusive todos os elementos BlobPrefix. Se a solicitação não especificar maxresults, nem especificar um valor maior do que 5.000, o servidor retornará até 5.000 itens.

A configuração de maxresults com um valor menor ou igual a zero resulta em um código de resposta de erro 400 (Solicitação Incorreta).

include={snapshots,metadata,uncommittedblobs,copy}

Opcional. Especifica um ou mais conjuntos de dados a serem incluídos na resposta:

  • snapshots: especifica que os instantâneos devem ser incluídos na enumeração. Os instantâneos são listados do mais antigo ao mais novo na resposta.

  • metadata: especifica que os metadados de blob são retornados na resposta.

  • uncommittedblobs: especifica que os blobs nos quais blocos foram carregados, mas que não foram confirmados usando Colocar lista de blocos, sejam incluídos na resposta.

  • copy: versão 2012-02-12 e mais recente. Especifica que os metadados relacionados a qualquer operação atual ou anterior de Copy Blob 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").

timeout

Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Definição de tempos limite para operações de serviço Blob.

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

 

Cabeçalho de solicitação Descrição

Authorization

Obrigatória. Especifica o esquema de autenticação, o nome da conta e a assinatura. Para obter mais informações, consulte Autenticação federada para os Serviços de Armazenamento do Azure.

Date ou x-ms-date

Obrigatória. Especifica o Tempo Universal Coordenado (UTC) para a solicitação. Para obter mais informações, consulte Autenticação federada para os Serviços de Armazenamento do Azure.

x-ms-version

Obrigatório para todas as solicitações autenticadas, opcional para solicitações anônimas. 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 caractere de 1 KB que é registrado nos logs analíticos quando o log analítico de armazenamento está habilitado. É altamente recomendável usar este cabeçalho para correlacionar atividades do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Sobre o registro em log da Análise de Armazenamento e Log do Azure: Usando logs para rastrear solicitações de armazenamento.

Consulte Enumerando recursos de blob para obter uma solicitação de exemplo.

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

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.

A resposta para esta operação inclui os cabeçalhos a seguir. A resposta também pode incluir cabeçalhos padrão HTTP adicionais. Todos os cabeçalhos padrão obedecem à especificação de protocolo HTTP/1.1.

 

Cabeçalho de resposta Descrição

Content-Type

Especifica o formato em que os resultados são retornados. Atualmente, esse valor é aplicativo/xml.

x-ms-request-id

Esse cabeçalho identifica a solicitação que foi feita de forma exclusiva e pode ser usado para solucionar problemas na solicitação. Para obter mais informações, consulte Solucionando problemas de operações de API.

x-ms-version

Indica a versão do serviço Blob usado para executar a solicitação. Esse cabeçalho é retornado para solicitações feitas com a versão 2009-09-19 e mais recentes.

Esse cabeçalho será retornado também para solicitações anônimas sem uma versão especificada se o contêiner foi marcado para acesso público usando a versão 2009-09-19 do serviço Blob.

Date

Um valor de data/hora UTC gerado pelo serviço que indica a hora em que a resposta foi iniciada.

O formato da resposta XML é mostrado a seguir.

Observe que os elementos Prefix, Marker, MaxResults e Delimiter somente estarão presentes se tiverem sido especificados no URI de solicitação. O elemento NextMarker terá um valor somente se os resultados da lista não estiverem completos.

Os instantâneos, os metadados de blob, e os blobs não confirmadas serão incluídos na resposta somente se forem especificados com o parâmetro include no URI de solicitação.

Na versão 2009-09-19 e mais recentes, as propriedades de blob são encapsuladas em um elemento Properties.

Na versão 2013-08-15 e mais recente, o elemento EnumerationResults contém um atributo ServiceEndpoint que especifica o ponto de extremidade do blob e um campo ContainerName que especifica o nome do contêiner. Em versões anteriores, esses dois atributos eram combinados no campo ContainerName. Também na versão 2013-08-15 e mais recente, o elemento Url em Blob foi removido.

<?xml version="1.0" encoding="utf-8"?>
<EnumerationResults ServiceEndpoint="http://myaccount.blob.core.windows.net/"  ContainerName="mycontainer">
  <Prefix>string-value</Prefix>
  <Marker>string-value</Marker>
  <MaxResults>int-value</MaxResults>
  <Delimiter>string-value</Delimiter>
  <Blobs>
    <Blob>
      <Name>blob-name</name>
      <Snapshot>date-time-value</Snapshot>
      <Properties>
        <Last-Modified>date-time-value</Last-Modified>
        <Etag>etag</Etag>
        <Content-Length>size-in-bytes</Content-Length>
        <Content-Type>blob-content-type</Content-Type>
        <Content-Encoding />
        <Content-Language />
        <Content-MD5 />
        <Cache-Control />
        <x-ms-blob-sequence-number>sequence-number</x-ms-blob-sequence-number>
        <BlobType>BlockBlob|PageBlob</BlobType>
        <LeaseStatus>locked|unlocked</LeaseStatus>
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>
        <LeaseDuration>infinite | fixed</LeaseDuration>
        <CopyId>id</CopyId>
        <CopyStatus>pending | success | aborted | failed </CopyStatus>
        <CopySource>source url</CopySource>
        <CopyProgress>bytes copied/bytes total</CopyProgress>
        <CopyCompletionTime>datetime</CopyCompletionTime>
        <CopyStatusDescription>error string</CopyStatusDescription>
      </Properties>
      <Metadata>   
        <Name>value</Name>
      </Metadata>
    </Blob>
    <BlobPrefix>
      <Name>blob-prefix</Name>
    </BlobPrefix>
  </Blobs>
  <NextMarker />
</EnumerationResults>

LeaseState e LeaseDuration aparecem somente na versão 2012-02-12 e mais recentes.

CopyId, CopyStatus, CopySource, CopyProgress, CopyCompletionTime e CopyStatusDescription aparecem somente na versão 2012-02-12 e mais recentes, quando essa operação inclui o parâmetro include={copy}. Esses elementos não serão exibidos se esse blob nunca tiver sido o destino em uma operação Copy Blob ou se esse blob tiver sido alterado depois de uma operação Copy Blob concluída usando Set Blob Properties, Put Blob ou Put Block List. Esses elementos também não são exibidas com um blob criado por Copiar Blob antes da versão 2012-02-12.

noteObservação
A partir da versão 2009-09-19, List Blobs retorna os seguintes elementos renomeados no corpo de resposta:

  • Last-Modified (anteriormente LastModified)

  • Content-Length (anteriormente Size)

  • Content-Type (anteriormente ContentType)

  • Content-Encoding (anteriormente ContentEncoding)

  • Content-Language (anteriormente ContentLanguage)

O elemento Content-MD5 é exibido para os blobs criados com a versão 2009-09-19 e mais recentes. Na versão 2012-02-12 e mais recentes, o serviço Blob calcula o valor de Content-MD5 quando você carrega um blob usando Colocar Blob, mas não calcula isso quando você cria um blob usando Colocar lista de blocos. Você pode definir explicitamente o valor de Content-MD5 quando cria o blob ou chamando as operações Colocar lista de blocos ou Definir propriedades de blob.

Consulte Enumerando recursos de blob, para obter um exemplo.

Se a lista de controle de acesso (ACL) do contêiner for definida para permitir o acesso anônimo ao contêiner, qualquer cliente poderá chamar essa operação. De outra forma, essa operação poderá ser chamada pelo proprietário da conta e por qualquer pessoa com uma assinatura de acesso compartilhado que tenha permissão para listar blobs em seu contêiner.

Propriedades de blob na resposta

Se você solicitou que os blobs não confirmadas sejam incluídos na enumeração, observe que algumas propriedades não serão definidas até o blob ser confirmado, portanto, algumas propriedades talvez não possam ser retornadas na resposta.

O elemento x-ms-blob-sequence-number somente é retornado para blobs de página.

Para blobs de página, o valor retornado no elemento Content-Length corresponde ao valor do cabeçalho x-ms-blob-content-length do blob.

O elemento Content-MD5 será exibido no corpo da resposta apenas se tiver sido definido no blob usando a versão 2009-09-19 ou mais recentes. Você pode definir a propriedade Content-MD5 quando o blob for criado ou chamando Definir propriedades de blob. Na versão 2012-02-12 e mais recente, Put Blob define o valor MD5 de um blob de blocos mesmo quando a solicitação Put Blob não inclui um cabeçalho MD5.

Metadados na resposta

O elemento Metadata estará presente apenas se o parâmetro include=metadata tiver sido especificado no URI. No elemento Metadata, o valor de cada par de nome-valor é listado em um elemento correspondente ao nome do par.

Observe que os metadados solicitados com esse parâmetro devem ser armazenados de acordo com as restrições de nomenclatura impostas pela versão 2009-09-19 do serviço Blob. A partir dessa versão, todos os nomes de metadados devem atender às convenções de nomenclatura para identificadores C#.

Se um par de nome-valor de metadados violar as restrições de nomenclatura impostas pela versão 2009-09-19, o corpo da resposta indicará o nome problemático dentro de um elemento x-ms-invalid-name, conforme mostrado no seguinte fragmento XML:


      …
      <Metadata>
        <MyMetadata1>first value</MyMetadata1>
        <MyMetadata2>second value</MyMetadata2>
        <x-ms-invalid-name>invalid-metadata-name</x-ms-invalid-name>
      </Metadata>
      …

Instantâneos na resposta

Os instantâneos serão listados na resposta somente se o parâmetro include=snapshots tiver sido especificado no URI. Os instantâneos listados na resposta não incluem o elemento LeaseStatus, pois os instantâneos não podem ter concessões ativas.

Se você chamar List Blobs com um delimitador, não poderá incluir também instantâneos na enumeração. Uma solicitação que inclui ambos retornará um erro de InvalidQueryParameter (código de status HTTP 400 – Solicitação Incorreta).

Blobs não confirmados na resposta

Os blobs não confirmados serão listados na resposta somente se o parâmetro include=uncommittedblobs tiver sido especificado no URI. Os blobs não confirmados listados na resposta não incluem nenhum dos seguintes elementos:

  • Last-Modified

  • Etag

  • Content-Type

  • Content-Encoding

  • Content-Language

  • Content-MD5

  • Cache-Control

  • Metadata

Retornando conjuntos de resultados usando um valor de marcador

Se você especificar um valor para o parâmetro maxresults e o número de blobs a serem retornados exceder esse valor ou exceder o valor padrão para maxresults, o corpo da resposta conterá um elemento NextMarker que indicará o blob seguinte 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.

Usando um delimitador para percorrer o namespace do blob

O parâmetro delimiter permite que o chamador percorra o namespace do blob usando um delimitador configurado pelo usuário. Desse modo, você pode atravessar uma hierarquia virtual de blobs como se fosse um sistema de arquivos. O delimitador pode ser um único caractere ou uma cadeia de caracteres. Quando a solicitação inclui esse parâmetro, ela retorna um elemento BlobPrefix. O elemento BlobPrefix é retornado no lugar de todos os blobs cujos nomes começam com a mesma subcadeia de caracteres até o aparecimento do caractere delimitador. O valor do elemento BlobPrefix é subcadeia de caracteres+delimitador, onde subcadeia de caracteres é a subcadeia de caracteres comum que inicia um ou mais nomes de blob, e delimitador é o valor do parâmetro delimitador.

Você pode usar o valor de BlobPrefix para fazer uma chamada subsequente para listar os blobs que começam com esse prefixo, especificando o valor de BlobPrefix para o parâmetro prefix no URI de solicitação.

Observe que cada elemento BlobPrefix retornado conta para o resultado máximo, assim como cada elemento Blob.

Os blobs são listados em ordem alfabética no corpo de resposta, com as letras maiúsculas primeiro.

Erros de cópia em CopyStatusDescription

CopyStatusDescription contém mais informações sobre a falha Copy Blob.

  • Quando uma tentativa de cópia falha e o serviço Blob ainda está repetindo a operação, CopyStatus é definido como pending e o texto CopyStatusDescription descreve a falha que pode ter ocorrido durante a última tentativa de cópia.

  • Quando CopyStatus é definido como failed, o texto CopyStatusDescription descreve o erro que causou a falha na operação de cópia.

A tabela a seguir descreve os três campos de cada valor CopyStatusDescription.

 

Componente Descrição

Código de status HTTP

O valor inteiro de três dígitos que especifica a falha.

Código de erro

Palavra-chave que descreve o erro que é fornecido pelo Azure no elemento <ErrorCode>. Se nenhum elemento <ErrorCode> aparecer, uma palavra-chave que contém o texto do erro padrão associado ao código de status HTTP de três dígitos na especificação HTTP será usada. Consulte Códigos de erro comuns da API REST.

Informações

Descrição detalhada da falha, entre aspas.

A tabela a seguir descreve os valores CopyStatus e CopyStatusDescription de cenários de falha comuns.

ImportantImportante
O texto da descrição mostrado aqui pode ser alterado sem aviso, mesmo sem uma alteração da versão, portanto, não conte com a correspondência exata a esse texto.

 

Cenário Valor de CopyStatus Valor de CopyStatusDescription

Operação de cópia concluída com êxito.

success

vazio

O usuário anulou a operação de cópia antes da conclusão.

aborted

vazio

Falha na leitura do blob de origem durante uma operação de cópia, mas a operação será repetida.

pending

502 BadGateway "Encontrado um erro reproduzível ao ler a origem. Uma nova tentativa será realizada. Hora da falha: <hora>"

Falha ao gravar no blob de destino de uma operação de cópia, mas a operação será repetida.

pending

500 InternalServerError "Encontrado um erro reproduzível. Uma nova tentativa será realizada. Hora da falha: <hora>"

Falha irrecuperável durante a leitura do blob de origem de uma operação de cópia.

failed

404 ResourceNotFound "Falha na cópia ao ler a origem.”

noteObservação
Ao informar esse erro subjacente, o Azure retorna ResourceNotFound no elemento <ErrorCode>. Se nenhum elemento <ErrorCode> apareceu na resposta, uma representação de cadeia de caracteres padrão do status HTTP, como NotFound, será exibida.

O tempo limite que limita todas as operações de cópia expirou. (Atualmente, o tempo limite é duas semanas.)

failed

500 OperationCancelled "A cópia excedeu o tempo máximo permitido.”

Ocorreram falhas muito frequentes na leitura da origem, e uma proporção mínima de tentativas e êxitos não foi atendida. (Esse tempo limite impede tentativas a partir de uma origem muito ruim por duas semanas antes da falha).

failed

500 OperationCancelled "Falha na cópia durante a leitura da origem.”

Mostrar:
© 2014 Microsoft