Get Block List

Artigo
02/03/2024

A operação Get Block List recupera a lista de blocos que foram carregados como parte de um blob de blocos.

Há duas listas de bloqueio mantidas para um blob:

Lista de Blocos Confirmados: a lista de blocos que foram confirmados com êxito em um blob especificado usando Put Block List.
Lista de blocos não confirmada: a lista de blocos que foram carregados para um blob usando Put Block, mas que ainda não foram confirmados. Esses blocos são armazenados no Azure em associação com um blob, mas ainda não fazem parte do blob.

Você pode chamar Get Block List para retornar a lista de bloqueio confirmada, a lista de bloqueios não confirmadas ou ambas as listas. Você também pode chamar essa operação para recuperar a lista de bloqueio confirmada para um instantâneo.

Solicitação

A solicitação Get Block List pode ser criada da seguinte maneira. Recomendamos que você use HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento:

URI de solicitação de método GET	Versão HTTP
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&snapshot=<DateTime>` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&versionid=<DateTime>`	HTTP/1.1

Solicitação de serviço de armazenamento emulado

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:

URI de solicitação de método GET	Versão HTTP
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=blocklist`	HTTP/1.1

Para obter mais informações, consulte Usar o emulador Azurite para desenvolvimento local do armazenamento do Azure.

Parâmetros do URI

Você pode especificar os seguintes parâmetros adicionais no URI da solicitação:

Parâmetro do URI	Descrição
`snapshot`	Opcional. O parâmetro de instantâneo é um valor `DateTime` opaco que, quando presente, especifica a lista de blobs a ser recuperada. Para obter mais informações sobre como trabalhar com instantâneos de blob, consulte Create um instantâneo de um blob.
`versionid`	Opcional para versões 2019-12-12 e posteriores. O `versionid` parâmetro é um valor opaco `DateTime` que, quando presente, especifica a versão do blob a ser recuperada.
`blocklisttype`	Especifica se é necessário retornar a lista de blocos confirmados, a lista de blocos não confirmados ou as duas listas. Os valores válidos são `committed`, `uncommitted` ou `all`. Se você omitir esse parâmetro, `Get Block List` retornará a lista de blocos confirmados.
`timeout`	Opcional. O parâmetro `timeout` é expresso em segundos. Para obter mais informações, consulte Definir tempos limite para operações de Armazenamento de Blobs.

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, 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-lease-id:<ID>`	Opcional. Se esse cabeçalho for especificado, a operação será executada apenas se as seguintes condições forem atendidas: - A concessão do blob está ativa no momento. - A ID de concessão especificada na solicitação corresponde à do blob. Se esse cabeçalho for especificado e qualquer condição não for atendida, a solicitação falhará e a operação falhará com status código 412 (Falha na pré-condição).
`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 Armazenamento de Blobs do Azure.

Essa operação também oferece suporte ao uso de cabeçalhos condicionais para executar a operação somente se uma determinada condição for atendida. Para obter mais informações, consulte Especificar cabeçalhos condicionais para operações de Armazenamento de Blobs.

Corpo da solicitação

Nenhum.

Solicitação de exemplo

O URI de solicitação de exemplo a seguir retorna a lista de bloqueio confirmada para um blob chamado MOV1.avi:

GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=committed HTTP/1.1

O URI de solicitação de exemplo a seguir retorna a lista de bloqueio confirmada e não confirmada:

GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=all HTTP/1.1

O URI de solicitação de exemplo a seguir retorna a lista de bloqueio confirmada para um instantâneo. Uma instantâneo consiste apenas em blocos confirmados, portanto, não há blocos não confirmados associados a ele.

GET http://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&snapshot=2009-09-30T20%3a11%3a15.2735974Z

Resposta

A resposta inclui um código de status HTTP, um conjunto de cabeçalhos de resposta e um corpo de resposta que contém a lista de blocos.

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 pode incluir 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
`Last-Modified`	A data/hora em que o blob foi modificado pela última vez. O formato da data segue RFC 1123. Para obter mais informações, consulte Representar valores de data/hora em cabeçalhos. Retornado somente se o blob tiver blocos confirmados. Qualquer operação que modificar o blob, incluindo atualizações nos metadados ou nas propriedades do blob, altera a hora da última modificação do blob.
`ETag`	A ETag do blob. Retornado somente se o blob tiver blocos confirmados.
`Content-Type`	O tipo de conteúdo MIME do blob. O valor padrão é `application/xml`.
`x-ms-blob-content-length`	O tamanho do blob em bytes.
`x-ms-request-id`	Esse cabeçalho identifica exclusivamente a solicitação que foi feita e pode ser usada para solucionar problemas da solicitação. Para obter mais informações, consulte Solucionar problemas de operações de API.
`x-ms-version`	Indica a versão do serviço que foi usada para executar a solicitação. Esse cabeçalho é retornado para solicitações feitas na versão 2009-09-19 e mais recente. Esse cabeçalho também será retornado para solicitações anônimas sem uma versão especificada se o contêiner tiver sido marcado para acesso público usando o Armazenamento de Blobs versão 2009-09-19. Observação: somente a lista de bloqueio confirmada pode ser retornada por meio de uma solicitação anônima.
`Date`	Um valor de data/hora UTC gerado pelo serviço, que indica a hora em que a resposta foi iniciada.
`x-ms-client-request-id`	Pode ser usado 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 e o valor não contiver mais de 1.024 caracteres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho não estiver presente na solicitação, ele não estará presente na resposta.

Essa operação também dá suporte ao uso de cabeçalhos condicionais para obter a lista de bloqueios somente se uma condição especificada for atendida. Para obter mais informações, consulte Especificar cabeçalhos condicionais para operações de Armazenamento de Blobs.

Corpo da resposta

O formato do corpo de resposta para uma solicitação que retorna somente blocos confirmados é o seguinte:

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>base64-encoded-block-id</Name>
      <Size>size-in-bytes</Size>
    </Block>
  <CommittedBlocks>
</BlockList>

O formato do corpo de resposta para uma solicitação que retorna blocos confirmados e não confirmados é o seguinte:


<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
     <Block>
        <Name>base64-encoded-block-id</Name>
        <Size>size-in-bytes</Size>
     </Block>
  </CommittedBlocks>
  <UncommittedBlocks>
    <Block>
      <Name>base64-encoded-block-id</Name>
      <Size>size-in-bytes</Size>
    </Block>
  </UncommittedBlocks>
 </BlockList>

Resposta de exemplo

No exemplo a seguir, o parâmetro blocklisttype foi definido como committed, de forma que apenas os blocos confirmados do blob são retornados na resposta.

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Sun, 25 Sep 2011 00:33:19 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>4194304</Size>
    </Block>
  </CommittedBlocks>
</BlockList>

Neste exemplo, o parâmetro blocklisttype foi definido como all, e os blocos confirmados e não confirmados do blob são retornados na resposta.

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Sun, 25 Sep 2011 00:35:56 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>4194304</Size>
    </Block>
  </CommittedBlocks>
  <UncommittedBlocks>
    <Block>
      <Name>BlockId003</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId004</Name>
      <Size>1024000</Size>
    </Block>
  </UncommittedBlocks>
</BlockList>

Neste próximo exemplo, o blocklisttype parâmetro foi definido como all, mas o blob ainda não foi confirmado, portanto, o CommittedBlocks elemento está vazio.

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Wed, 14 Sep 2011 00:40:22 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks />
  <UncommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId003</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId004</Name>
      <Size>1024</Size>
    </Block>
  </UncommittedBlocks>
</BlockList>

Autorização

A autorização é necessária ao chamar qualquer operação de acesso a dados no Armazenamento do Azure. Você pode autorizar a Get Block List operação, conforme descrito abaixo.

Importante

A Microsoft recomenda usar Microsoft Entra ID com identidades gerenciadas para autorizar solicitações ao Armazenamento do Azure. Microsoft Entra ID fornece segurança superior e facilidade de uso em comparação com a autorização de Chave Compartilhada.

O Armazenamento do Azure dá suporte ao uso de Microsoft Entra ID para autorizar solicitações para dados de blob. Com Microsoft Entra ID, você pode usar o RBAC (controle de acesso baseado em função) do Azure para conceder permissões a uma entidade de segurança. A entidade de segurança pode ser um usuário, grupo, entidade de serviço de aplicativo ou identidade gerenciada do Azure. A entidade de segurança é autenticada por Microsoft Entra ID para retornar um token OAuth 2.0. Em seguida, o token pode ser usado para autorizar uma solicitação no serviço de Blob.

Para saber mais sobre a autorização usando Microsoft Entra ID, consulte Autorizar o acesso a blobs usando Microsoft Entra ID.

Permissões

Veja abaixo a ação RBAC necessária para um usuário Microsoft Entra, grupo, identidade gerenciada ou entidade de serviço para chamar a Get Block List operação e a função RBAC interna do Azure com menos privilégios que inclui esta ação:

Ação RBAC do Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Função interna com privilégios mínimos:Leitor de Dados do Blob de Armazenamento

Para saber mais sobre como atribuir funções usando o RBAC do Azure, confira Atribuir uma função do Azure para acesso aos dados de blob.

Uma SAS (assinatura de acesso compartilhado) fornece acesso delegado seguro aos recursos em uma conta de armazenamento. Com uma SAS, você tem controle granular sobre como um cliente pode acessar dados. Você pode especificar qual recurso o cliente pode acessar, quais permissões eles têm para esses recursos e por quanto tempo a SAS é válida.

A Get Block List operação dá suporte a três tipos de assinaturas de acesso compartilhado: SAS de delegação de usuário, SAS de serviço e SAS de conta.

Como prática recomendada de segurança, recomendamos que você use Microsoft Entra credenciais em vez da chave da conta de armazenamento, que pode ser comprometida com mais facilidade. Se o design do aplicativo exigir assinaturas de acesso compartilhado, use Microsoft Entra credenciais para criar uma SAS de delegação de usuário, quando possível.

Quando o acesso à Chave Compartilhada não for permitido para a conta de armazenamento, um token SAS de serviço ou um token SAS de conta não será permitido em uma solicitação para o Armazenamento de Blobs. Para saber mais, confira Entender como a não permissão de Chave Compartilhada afeta tokens SAS.

SAS de delegação do usuário

Uma SAS de delegação de usuário é protegida com Microsoft Entra credenciais e também pelas permissões especificadas para a SAS.

Chamar a Get Block List operação usando um token SAS delegado a um recurso de contêiner ou blob requer a permissão Leitura (r) como parte do token SAS de delegação do usuário.

Para saber mais sobre a SAS de delegação de usuário, consulte Create uma SAS de delegação de usuário.

SAS de serviço

Uma SAS de serviço é protegida com a chave da conta de armazenamento. Uma SAS de serviço delega acesso a um recurso em um único serviço de Armazenamento do Azure, como o armazenamento de blobs.

Chamar a Get Block List operação usando um token SAS delegado a um contêiner ou recurso de blob requer a permissão Leitura (r) como parte do token SAS de serviço.

Para saber mais sobre a SAS de serviço, consulte Create uma SAS de serviço.

SAS de Conta

Uma SAS de conta é protegida com a chave da conta de armazenamento. Uma SAS de conta delega acesso a recursos em um ou mais dos serviços de armazenamento. Todas as operações disponíveis através de uma SAS de serviço ou de delegação do usuário também estão disponíveis por meio de uma SAS de conta.

A tabela a seguir indica o tipo de recurso assinado e as permissões assinadas a serem especificadas ao delegar o acesso:

Operação	Serviço assinado	Tipo de recurso assinado	Permissão assinada
Get Block List	Blob (b)	Objeto (o)	Leitura (r)

Para saber mais sobre a SAS da conta, consulte Create uma SAS de conta.

A Get Block List operação dá suporte à autorização de Chave Compartilhada. A autorização com chaves de conta não é recomendada para a maioria dos cenários, pois é menos segura.

A Microsoft recomenda não permitir a autorização de Chave Compartilhada para a conta de armazenamento quando possível. Para obter mais informações, consulte Impedir autorização com chave compartilhada.

Comentários

Chame Get Block List para retornar a lista de blocos que foram confirmados em um blob de blocos, a lista de blocos que ainda não foram confirmados ou ambas as listas. Use o parâmetro blocklisttype para especificar qual lista de blocos deve ser retornada. A lista de blocos confirmados é retornada na mesma ordem em que foram confirmados pela operação Colocar Lista de Blocos .

Você pode usar a lista de bloqueios não confirmada para determinar quais blocos estão ausentes do blob nos casos em que as chamadas para Put Block ou Put Block List falharam. A lista de blocos não confirmados é retornada em ordem alfabética. Se uma ID de bloco tiver sido carregada mais de uma vez, apenas o bloco carregado recentemente aparecerá na lista.

Observação

Quando um blob ainda não foi confirmado, chamar Get Block List com blocklisttype=all retorna os blocos não confirmados e o CommittedBlocks elemento está vazio.

Get Block List não dá suporte à simultaneidade quando lê a lista de blocos não confirmados. Chamadas para Get Block List onde blocklisttype=uncommitted ou blocklisttype=all têm uma taxa de solicitação máxima menor do que outras operações de leitura. Para obter detalhes sobre a taxa de transferência de destino para operações de leitura, consulte Metas de escalabilidade e desempenho do Armazenamento do Azure.

A partir da versão 2019-12-12, um blob de blocos pode conter blocos de até 4.000 mebibytes (MiB). Para proteger aplicativos que usam um inteiro com sinal de 32 bits para representar o tamanho do bloco, chamar Get Block List em um blob de blocos que contém um bloco maior que 100 MiB com uma versão REST anterior a 2019-12-12 resulta em status código 409 (Conflito).

Get Block List é aplicável apenas a blobs de bloco. A chamada de Get Block List em um blob de páginas resulta no código de status 400 (Solicitação Incorreta).

Get Block List em um blob de blocos arquivado falhará.

Cobrança

As solicitações de preços podem ser originadas de clientes que usam APIs de Armazenamento de Blobs, diretamente por meio da API REST do Armazenamento de Blobs ou de uma biblioteca de clientes do Armazenamento do Azure. Essas solicitações acumulam encargos por transação. O tipo de transação afeta a forma como a conta é cobrada. Por exemplo, as transações de leitura se acumulam em uma categoria de cobrança diferente das transações de gravação. A tabela a seguir mostra a categoria de cobrança para Get Block List solicitações com base no tipo de conta de armazenamento:

Operação	Tipo de conta de armazenamento	Categoria de cobrança
Get Block List	Blob de blocos Premium Uso geral v2 Standard	Outras operações
Get Block List	Uso geral v1 Standard	Operações de leitura

Para saber mais sobre os preços para a categoria de cobrança especificada, consulte Armazenamento de Blobs do Azure Preços.

Confira também

Autorizar solicitações para o Status do Armazenamento do Azure e códigos de erro Códigos de erro do Armazenamento de Blobs Definir tempos limite para operações de Armazenamento de Blobs

Compartilhar via