Put Block List

A operação Put Block List grava um blob especificando a lista de IDs de bloco que constituem o blob. Para ser gravado como parte de um blob, um bloco deve ter sido gravado com êxito no servidor em uma operação put block anterior.

Você pode chamar Put Block List para atualizar um blob carregando apenas os blocos que foram alterados e depois confirmando os blocos novos e existentes em conjunto. Para fazer isso, especifique se um bloco deve ser confirmado da lista de blocos confirmados ou da lista de blocos não confirmados, ou confirme a versão mais recente carregada do bloco, independentemente da lista à qual ele pertença.

Solicitação

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

URI de solicitação do método PUT Versão de HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist HTTP/1.1

URI 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 do método PUT Versão de HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=blocklist HTTP/1.1

O emulador de armazenamento dá suporte apenas a tamanhos de blob de até 2 GiB.

Para obter mais informações, consulte Usando o Azure Armazenamento Emulator para desenvolvimento e teste.

Parâmetros de URI

Os seguintes parâmetros adicionais podem ser especificados no URI de solicitação.

Parâmetro Descrição
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Setting Timeouts for Blob Service Operations.

Cabeçalhos de 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 obter mais informações, consulte Autorizar solicitações para o Azure Armazenamento.
Date ou x-ms-date Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para obter mais informações, consulte Autorizar solicitações para o Azure Armazenamento.
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 Versioning for the Azure Armazenamento Services.
Content-Length Obrigatórios. O comprimento do conteúdo da solicitação em bytes. Esse título refere-se ao comprimento do conteúdo da lista de blocos, não do próprio blob.
Content-MD5 Opcional. Um hash MD5 do conteúdo da solicitação. O hash é usado para verificar a integridade do conteúdo da solicitação durante o transporte. Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação Incorreta).

Esse título está associado ao conteúdo da solicitação e não ao conteúdo do próprio blob.
x-ms-content-crc64 Opcional. Um hash crc64 do conteúdo da solicitação. O hash é usado para verificar a integridade do conteúdo da solicitação durante o transporte. Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação Incorreta).

Esse título está associado ao conteúdo da solicitação e não ao conteúdo do próprio blob.

Se os headers Content-MD5 e x-ms-content-crc64 estão presentes, a solicitação falhará com um 400 (solicitação ruim).

Esse header tem suporte nas versões 2019-02-02 ou posterior.
x-ms-blob-cache-control Opcional. Define o controle de cache do blob. Se especificada, essa propriedade será armazenada com o blob e retornada com uma solicitação de leitura.

Se essa propriedade não for especificada com a solicitação, será apagada para o blob se a solicitação for bem-sucedida.
x-ms-blob-content-type Opcional. Define o tipo de conteúdo do blob. Se especificada, essa propriedade será armazenada com o blob e retornada com uma solicitação de leitura.

Se o tipo de conteúdo não for especificado, será definido como o tipo padrão, que é application/octet-stream.
x-ms-blob-content-encoding Opcional. Define a codificação do conteúdo do blob. Se especificada, essa propriedade será armazenada com o blob e retornada com uma solicitação de leitura.

Se essa propriedade não for especificada com a solicitação, será apagada para o blob se a solicitação for bem-sucedida.
x-ms-blob-content-language Opcional. Defina o idioma do conteúdo do blob. Se especificada, essa propriedade será armazenada com o blob e retornada com uma solicitação de leitura.

essa propriedade não for especificada com a solicitação, será apagada para o blob se a solicitação for bem-sucedida.
x-ms-blob-content-md5 Opcional. Um hash MD5 do conteúdo do blob. Esse hash não é validado, pois os hashes para os blocos individuais foram validados quando cada um foi carregado.

A operação Obter Blob retorna o valor desse título no título de resposta Content-MD5.

Se essa propriedade não for especificada com a solicitação, será apagada para o blob se a solicitação for bem-sucedida.
x-ms-meta-name:value Opcional. Pares de nome-valor definidos pelo usuário associados ao blob.

A partir da versão 2009-09-19, os nomes de metadados devem seguir as regras de nomen por identificadores C#.
x-ms-encryption-scope Opcional. Indica o escopo de criptografia a ser usado para criptografar o blob. Esse valor deve corresponder ao escopo de criptografia usado para criptografar todos os blocos que estão sendo confirmados. Esse header tem suporte nas versões 2019-02-02 ou posterior.
x-ms-tags Opcional. Define as marcas codificadas em cadeia de caracteres de consulta determinadas no blob. Confira os Comentários para obter informações adicionais. Com suporte na versão 2019-12-12 e mais recente.
x-ms-lease-id:<ID> Obrigatório se o blob tiver uma concessão ativa. Para executar essa operação em um blob com uma concessão ativa, especifique a ID de concessão válida para esse cabeçalho.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de 1 caractere KiB que é registrado nos logs de análise quando o log de análise de armazenamento está habilitado. O uso desse cabeçalho é altamente recomendável para correlacionar as atividades do lado do cliente com as solicitações recebidas pelo servidor. Para obter mais informações, consulte Sobre o log Armazenamento Analytics e Log do Azure: usando logspara rastrear Armazenamento solicitações .
x-ms-blob-content-disposition Opcional. Define o cabeçalho Content-Disposition do blob. Disponível para versões 2013-08-15 e posteriores.

O campo de header transmite informações adicionais sobre como processar a carga de resposta e também pode ser usado para Content-Disposition anexar metadados adicionais. Por exemplo, se for definido como attachment, indica que o agente de usuário não deve exibir a resposta, mas em vez disos mostra uma caixa de diálogo Salvar como.

A resposta das operações Obter Propriedades de Blob e Obter Blob inclui o título de disposição de conteúdo.
x-ms-access-tier Opcional. Versão 2018-11-09 e mais recente. Indica a camada a ser definida em um blob. Para blobs de blocos, com suporte no armazenamento de blobs ou contas de uso geral v2 somente com a versão 2018-11-09 e mais recente. Os valores válidos para camadas de blob de blocos são Hot / Cool / Archive . Para obter informações detalhadas sobre a camada de blob de blocos, consulte Camadas de armazenamento quente, esbora e arquivadas.
x-ms-immutability-policy-until-date Versão 2020-06-12 e mais recente. Especifica a data "retenção até" a ser definida no blob. Essa é a data até que o blob possa ser protegido contra modificação ou exclusão. Segue o formato RFC1123.
x-ms-immutability-policy-mode Versão 2020-06-12 e mais recente. Especifica o modo de política de imutabilidade a ser definido no blob. Os valores válidos são unlocked / locked . unlocked indica que o usuário pode alterar a política aumentando ou diminuindo a data de retenção até. locked indica que essas ações são proibidas.
x-ms-legal-hold Versão 2020-06-12 e mais recente. Especifica a espera legal a ser definida no blob, os valores válidos são true/false .

Essa operação também dará suporte ao uso de cabeçalhos condicionais para confirmar a lista de bloqueio somente se uma determinada condição for atendida. Para obter mais informações, confira Como especificar cabeçalhos condicionais para operações de serviço Blob.

Headers de solicitação (chaves de criptografia fornecidas pelo cliente)

A partir da versão 2019-02-02, os seguintes headers podem ser especificados na solicitação para criptografar um blob com uma chave fornecida pelo cliente. A criptografia com uma chave fornecida pelo cliente (e o conjunto correspondente de headers) é opcional.

Cabeçalho da solicitação Descrição
x-ms-encryption-key Obrigatórios. A chave de criptografia AES-256 codificada em Base64.
x-ms-encryption-key-sha256 Obrigatórios. O hash SHA256 codificado em Base64 da chave de criptografia.
x-ms-encryption-algorithm: AES256 Obrigatórios. Especifica o algoritmo a ser usado para criptografia. O valor deste cabeçalho deve ser AES256.

Corpo da solicitação

No corpo da solicitação, você pode especificar em qual lista de blocos o serviço Blob deverá procurar o bloco solicitado. Dessa forma, você pode atualizar um blob existente inserindo, substituindo ou excluindo blocos individuais, em vez de recarregar todo o blob. Após o carregamento dos blocos que foram alterados, você poderá confirmar uma nova versão do blob ao confirmar os novos blocos em conjunto com os blocos existentes que deseja manter.

Para atualizar um blob, você pode especificar que o serviço deve procurar uma ID de bloco na lista de blocos confirmados, na lista de blocos não confirmados ou na lista de blocos não confirmados primeiro e depois na lista de blocos confirmados. Para indicar o método a ser usado, especifique a ID do bloco dentro do elemento XML apropriado dentro do corpo da solicitação, da seguinte forma:

  • Especifique a ID do bloco no elemento Committed para indicar que o serviço Blob deve pesquisar somente a lista de blocos confirmados para o bloco indicado. Se o bloco não for encontrado na lista de blocos confirmados, ele não será gravado como parte do Blob, e o serviço Blob retornará o código de status 400 (Solicitação Incorreta).

  • Especifique a ID do bloco no elemento Uncommitted para indicar que o serviço Blob deve pesquisar somente a lista de blocos não confirmados para o bloco indicado. Se o bloco não for encontrado na lista de blocos não confirmados, ele não será gravado como parte do Blob, e o serviço Blob retornará o código de status 400 (Solicitação Incorreta).

  • Especifique a ID do bloco no elemento Latest para indicar que o serviço Blob deve pesquisar primeiro a lista de blocos não confirmados. Se o bloco for encontrado na lista de não confirmados, essa versão do bloco será a mais recente e deverá ser gravada no Blob. Se o bloco não for localizado na lista de não confirmados, o serviço deverá pesquisar a lista de blocos confirmados para o bloco indicado e gravar esse bloco no blob, se for encontrado.

O corpo da solicitação para essa versão do Put Block List usa o seguinte formato XML:

<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <Committed>first-base64-encoded-block-id</Committed>  
  <Uncommitted>second-base64-encoded-block-id</Uncommitted>  
  <Latest>third-base64-encoded-block-id</Latest>  
  ...  
</BlockList>  
  

Solicitação de Exemplo

Para demonstrar Put Block List, vamos supor que você carregou três blocos que agora deseja confirmar. O exemplo a seguir confirma um novo blob indicando que a última versão de cada bloco listado deve ser usada. Não é necessário saber se esses blocos já foram confirmados.

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist HTTP/1.1  
  
Request Headers:  
x-ms-date: Wed, 31 Aug 2011 00:17:43 GMT  
x-ms-version: 2011-08-18  
Content-Type: text/plain; charset=UTF-8  
Authorization: SharedKey myaccount:DJ5QZSVONZ64vAhnN/wxcU+Pt5HQSLAiLITlAU76Lx8=  
Content-Length: 133  
  
Request Body:  
<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <Latest>AAAAAA==</Latest>  
  <Latest>AQAAAA==</Latest>  
  <Latest>AZAAAA==</Latest>  
</BlockList>  
  

Em seguida, vamos supor que você queira atualizar o blob. O novo blob terá as seguintes alterações:

  • Um novo bloco com a ID ANAAAA==. Esse bloco deve primeiro ser carregado com uma chamada para Colocar Bloco e aparecerá na lista de blocos não confirmados até a chamada para Put Block List .

  • Uma versão atualizada do bloco com a ID AZAAAA==. Esse bloco deve primeiro ser carregado com uma chamada para Colocar Bloco e aparecerá na lista de blocos não confirmados até a chamada para Put Block List .

  • Remoção do bloco com a ID AAAAAA==. Considerando que esse bloco não está incluído na próxima chamada para Put Block List, o bloco será efetivamente removido do blob.

O exemplo a seguir mostra a chamada para Put Block List que atualiza o blob:

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist HTTP/1.1  
  
Request Headers:  
x-ms-date: Wed, 31 Aug 2009 00:17:43 GMT  
x-ms-version: 2011-08-18  
Content-Type: text/plain; charset=UTF-8  
Authorization: SharedKey myaccount:DJ5QZSVONZ64vAhnN/wxcU+Pt5HQSLAiLITlAU76Lx8=  
Content-Length: 133  
  
Request Body:  
<?xml version="1.0" encoding="utf-8"?>  
<BlockList>  
  <Uncommitted>ANAAAA==</Uncommitted>  
  <Committed>AQAAAA==</Committed>  
  <Uncommitted>AZAAAA==</Uncommitted>  
</BlockList>  
  

Resposta

A resposta inclui um código de status HTTP e um conjunto de cabeçalhos de resposta.

Código de status

Uma operação bem-sucedida retorna o código de status 201 (Criado).

Para obter informações sobre códigos de status, consulte Status e Códigos 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 padrão HTTP adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação de protocolo HTTP/1.1.

Resposta Descrições
ETag A marca de entidade contém um valor que o cliente pode usar para executar operações GET/PUT condicionais usando o cabeçalho de solicitação If-Match. Se a versão da solicitação for a 2011-08-18 ou mais recente, o valor de ETag será exibido entre aspas.
Last-Modified A data e a hora da última modificação feita no blob. O formato da data segue RFC 1123. Para obter mais informações, consulte Representação de Date-Time valores em headers.

Qualquer operação que modificar o blob, incluindo uma atualização dos metadados ou das propriedades do blob, alterará a hora da última modificação do blob.
Content-MD5 Esse cabeçalho é retornado para que o cliente possa verificar a integridade do conteúdo da mensagem. Esse cabeçalho se refere ao conteúdo da solicitação, ou seja, nesse caso, a lista de blocos, e não ao conteúdo do próprio blob. Para as versões 2019-02-02 ou posterior, esse header só é retornado quando a solicitação tem esse header.
x-ms-content-crc64 Para as versões 2019-02-02 e posteriores, esse título é retornado para que o cliente possa verificar a integridade do conteúdo da mensagem. Esse cabeçalho se refere ao conteúdo da solicitação, ou seja, nesse caso, a lista de blocos, e não ao conteúdo do próprio blob.

Esse header é retornado quando Content-md5 o header não está presente na solicitação.
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 Solução de 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 na versão 2009-09-19 e mais recente.
Date Um valor de data/hora UTC gerado pelo serviço que indica a hora em que a resposta foi iniciada.
x-ms-request-server-encrypted: true/false Versão 2015-12-11 ou mais recente. O valor desse header será definido como se o conteúdo da solicitação for criptografado com êxito usando o true algoritmo especificado e caso false contrário.
x-ms-encryption-key-sha256 Versão 2019-02-02 ou mais recente. Esse header será retornado se a solicitação tiver usado uma chave fornecida pelo cliente para criptografia, para que o cliente possa garantir que o conteúdo da solicitação seja criptografado com êxito usando a chave fornecida.
x-ms-encryption-scope Versão 2019-02-02 ou mais recente. Esse header será retornado se a solicitação tiver usado um escopo de criptografia, para que o cliente possa garantir que o conteúdo da solicitação seja criptografado com êxito usando o escopo de criptografia.
x-ms-version-id: <DateTime> Versão 2019-12-12 e mais recente. Esse header retorna um valor DateTime opaco que identifica exclusivamente o blob. O valor desse header indica a versão do blob e pode ser usado em solicitações subsequentes para acessar o blob.
x-ms-client-request-id Esse header pode ser usado para solucionar problemas de solicitações e respostas correspondentes. O valor desse header será igual ao valor do header se ele estiver presente na solicitação e o valor for, no máximo, x-ms-client-request-id 1024 caracteres ASCII visíveis. Se o x-ms-client-request-id header não estiver presente na solicitação, esse header não estará presente na resposta.

Exemplo de Resposta

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 00:17:44 GMT  
ETag: “0x8CB172A360EC34B”  
Last-Modified: Sun, 25 Sep 2011 00:17:43 GMT  
x-ms-version: 2011-08-18  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-version-id: <DateTime>  

Autorização

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 gravar nesse blob ou em seu contêiner.

Se uma solicitação especificar marcas com o x-ms-tags cabeçalho da solicitação, o chamador deverá atender aos requisitos de autorização da operação definir marcas de blob .

Comentários

A operação Put Block List impõe a ordem em que os blocos deverão ser combinados para criar um blob.

A mesma ID de bloco pode ser especificada mais de uma vez na lista de blocos. Se uma ID de bloco for especificada mais de uma vez, isso representará o intervalo de bytes em cada um desses locais na lista de blocos do blob confirmado final. Se uma ID de bloco aparecer mais de uma vez na lista, ambas as instâncias da ID do bloco deverão ser especificadas na mesma lista de blocos. Ou seja ambas as instâncias devem ser especificadas nos elementos Committed, Uncommitted ou Latest.

Com Put Block List, você pode modificar um blob existente, inserindo, atualizando ou excluindo blocos individuais, sem carregar o blob inteiro novamente. Você pode especificar IDs do bloco da lista de contatos bloqueados confirmada atual e da lista de blocos não confirmados para criar um novo blob ou para atualizar o conteúdo de um blob existente. Dessa forma, você pode atualizar um blob especificando alguns novos blocos da lista de blocos não confirmados e o restante da lista de blocos confirmados, que já fazem parte do blob existente.

Se uma ID de bloco for especificado no elemento Latest, e a mesma ID do bloco existir em listas de contatos bloqueados confirmadas e não confirmadas, Put Block List confirmará o bloco da lista de blocos não confirmados. Se a ID do bloco existir na lista de blocos confirmados, mas não na lista de blocos não confirmados, então Put Block List confirmará o bloco da lista de blocos confirmados.

Cada bloco em um blob de blocos pode ter um tamanho diferente. Um blob de blocos pode incluir no máximo 50.000 blocos confirmados. O número máximo de blocos não confirmados que podem ser associados a um blob é 100.000. A tabela a seguir descreve os tamanhos máximos de bloco e BLOB permitidos pela versão do serviço:

Versão do serviço Tamanho máximo do bloco (via Colocar Bloco) Tamanho máximo do blob (via Colocar Lista de Bloco) Tamanho máximo do blob via operação de gravação única (via Colocar Blob)
Versão 12/12/2019 e posterior 4000 MiB Aproximadamente 190,7 TiB (4000 MiB X 50.000 blocos) 5000 MiB (versão prévia)
Versão 31/05/2016 até a versão 07/07/2019 100 MiB Aproximadamente 4,75 TiB (100 MiB X 50.000 blocos) 256 MiB
Versões anteriores a 31/05/2016 4 MiB Aproximadamente 195 GiB (4 MiB X 50.000 blocos) (versão prévia) 64 MiB

Quando você chama Put Block List para atualizar um blob existente, as propriedades existentes e os metadados de blob são substituídos. No entanto, todos os instantâneos existentes são mantidos com o blob. Você pode usar os cabeçalhos de solicitação condicionais para executar a operação somente se uma condição especificada for atendida.

Se a operação Put Block List falhar devido a um bloco ausente, você precisará carregar o bloco ausente.

Todos os blocos não confirmados serão limpos se não houver nenhuma chamada bem-sucedida a Put Block ou a Put Block List no blob dentro de uma semana após a última operação Put Block bem-sucedida. Se Put Blob for chamado no BLOB, os blocos não confirmados serão coletados como lixo.

Se as marcas forem fornecidas no x-ms-tags cabeçalho, elas deverão ser codificadas para cadeia de caracteres de consulta. As chaves e os valores de marca devem estar de acordo com os requisitos de nomenclatura e comprimento conforme especificado em definir marcas de BLOB. Além disso, o x-ms-tags cabeçalho pode conter marcas de até 2 KiB de tamanho. Se mais marcas forem necessárias, use a operação definir marcas de blob .

Se o blob tiver uma concessão ativa, o cliente deverá especificar uma ID de concessão válida para confirmar a lista de blocos. Se o cliente não especificar uma ID de concessão ou especificar uma ID inválida, o serviço Blob retornará o código de status 412 (Falha na Pré-condição). Se o cliente especificar uma ID de concessão, mas o blob não tiver uma concessão ativa, o serviço Blob também retornará o código de status 412 (Falha na Pré-condição). Se o cliente especificar um ID de concessão em um blob que ainda não existir, o serviço Blob retornará o código de status 412 (falha na pré-condição) para solicitações feitas na versão 2013-08-15 e posterior; para versões anteriores, o serviço Blob retornará o código de status 201 (criado).

Se o blob tiver uma concessão ativa e você chamar Put Block List para atualizar o blob, a concessão será é mantida no blob atualizado.

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

Substituir um blob arquivado falhará e substituirá um hot / cool blob herdará a camada do blob antigo se o cabeçalho x-MS-Access-Tier não for fornecido.

Consulte Também

Noções básicas sobre blobs de bloco, blobs de acréscimo e blobs de página
autorizar solicitações para o Azure Armazenamento
Status e códigos de erro
Códigos de erro do serviço blob
Configurando os tempos limite para operações de serviço do Blob