Put Block

A operação Put Block cria um novo bloco a ser confirmado como parte de um blob.

Solicitação

A solicitação Put Block 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=block&blockid=id 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=block&blockid=id HTTP/1.1

Para obter mais informações, consulte Usando o Armazenamento Emulator do Azure para Desenvolvimento e Teste.

Parâmetros de URI

Parâmetro Descrição
blockid Obrigatórios. Um valor de cadeia de caracteres na Base64 válido que identifica o bloco. Antes da codificação, a cadeia de caracteres deve ter um tamanho menor ou igual a 64 bytes.

Para um determinado blob, o comprimento do valor especificado para o parâmetro blockid deve ter o mesmo tamanho para cada bloco.

Observe que a cadeia de caracteres na Base64 deve ser codificada com URL.
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Configurando tempos limite para operações de serviço blob.

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. Consulte As solicitações do Authorize para Armazenamento do Azure para obter mais informações.
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 ao 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.
Content-Length Obrigatórios. O comprimento do bloco da solicitação em bytes. O bloco deve ser menor ou igual a 4000 MiB em tamanho para a versão 2019-12-12 e posterior. Consulte os Comentários para obter limites em versões mais antigas.

Quando o comprimento não for fornecido, a operação falhará com o código de status 411 (Comprimento Obrigatório).
Content-MD5 Opcional. Um hash MD5 do conteúdo do bloco. O hash é usado para verificar a integridade do bloco durante o transporte. Quando esse cabeçalho é especificado, o serviço de armazenamento compara o hash do conteúdo que foi recebido com esse valor de cabeçalho.

Observe que esse hash MD5 não é armazenado com o blob.

Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação Incorreta).
x-ms-content-crc64 Opcional. Um hash CRC64 do conteúdo do bloco. O hash é usado para verificar a integridade do bloco durante o transporte. Quando esse cabeçalho é especificado, o serviço de armazenamento compara o hash do conteúdo que foi recebido com esse valor de cabeçalho.

Observe que esse hash CRC64 não é armazenado com o blob.

Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação Incorreta).

Se os cabeçalhos Content-MD5 e x-ms-content-crc64 estiverem presentes, a solicitação falhará com um 400 (Solicitação Incorreta).

Esse cabeçalho tem suporte nas versões 2019-02-02 ou posterior.
x-ms-encryption-scope Opcional. Indica o escopo de criptografia a ser usado para criptografar o conteúdo da solicitação. Esse cabeçalho tem suporte nas versões 2019-02-02 ou posterior.
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 caracteres de 1 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 Análise de Armazenamento registro em log e log do Azure: usando logs para acompanhar solicitações de Armazenamento.

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

A partir da versão 2019-02-02, os cabeçalhos a seguir 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 cabeçalhos) é 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

O corpo da solicitação tem o conteúdo do bloco.

Solicitação de Exemplo

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2011-08-18  
x-ms-date: Sun, 25 Sep 2011 14:37:35 GMT  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048576  

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.

Cabeçalho de resposta Descrição
Content-MD5 Esse cabeçalho é retornado para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor desse cabeçalho é computado pelo serviço Blob; ele não é necessariamente o mesmo valor especificado nos cabeçalhos de solicitação. Para versões 2019-02-02 ou posteriores, esse cabeçalho só é retornado quando a solicitação tem esse cabeçalho.
x-ms-content-crc64 Para versões 2019-02-02 ou posteriores, esse cabeçalho é retornado para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor desse cabeçalho é computado pelo serviço Blob; ele não é necessariamente o mesmo valor especificado nos cabeçalhos de solicitação.

Esse cabeçalho é retornado quando Content-md5 o cabeçalho 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 cabeçalho será definido para true se o conteúdo da solicitação for criptografado com êxito usando o algoritmo especificado e false de outra forma.
x-ms-encryption-key-sha256 Versão 2019-02-02 ou mais recente. Esse cabeçalho 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 cabeçalho 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-client-request-id Esse cabeçalho 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 estiver 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.

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 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  

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.

Comentários

Put Block carrega um bloco para inclusão futura em um blob de blocos. Cada bloco em um blob de blocos pode ter um tamanho diferente. Um blob de blocos pode incluir um máximo de 50.000 blocos confirmados. A tabela a seguir descreve os tamanhos máximos de bloco e blob permitidos pela versão de 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

O número máximo de blocos não confirmados que podem ser associados a um blob é de 100.000. Se esse máximo for excedido, o serviço retornará o código de status 409 (RequestEntityTooLargeBlockCountExceedsLimit).

Depois de carregar um conjunto de blocos, você pode criar ou atualizar o blob no servidor desse conjunto chamando a operação Colocar Lista de Blocos . Cada bloco no conjunto é identificado por uma ID de bloco que é exclusiva dentro desse blob. As IDs do bloco têm escopo para um blob específico, de forma que os blobs diferentes possam ter os mesmos blocos com as mesmas IDs.

Se você chamar Put Block em um blob que ainda não exista, um novo blob de blocos será criado, com um comprimento de conteúdo de 0. Esse blob será enumerado pela operação List Blobs se a opção include=uncommittedblobs for especificada. O bloco ou os blocos carregados não são confirmados até você chamar Put Block List no novo blob. Um blob criado dessa maneira é mantido no servidor por uma semana; se você não adicionar mais blocos ou blocos confirmadas ao blob nesse período, o blob será limpo.

Um bloco que foi carregado com êxito com a operação Put Block não se torna parte de um blob até que seja confirmado com Put Block List. Antes Put Block List de ser chamado para confirmar o blob novo ou atualizado, todas as chamadas para Obter Blob retornam o conteúdo do blob sem a inclusão do bloco não confirmado.

Se você carregar um bloco com a mesma ID de bloco de outro bloco que ainda não foi confirmado, o bloco carregado pela última vez com essa ID será confirmado na próxima operação Put Block List bem-sucedida.

Depois de chamar Put Block List, todos os blocos não confirmadas especificados na lista de blocos são confirmados como parte do novo blob. Todos os blocos não confirmados que não estiverem especificados na lista de blocos do blob serão limpos e removidos do serviço Blob. Todos os blocos não confirmados também serão limpos se não houver nenhuma chamada bem-sucedida a Put Block ou a Put Block List no mesmo blob dentro de uma semana após a última operação Put Block bem-sucedida. Se Put Blob for chamado no blob, todos os blocos não confirmados serão coletados.

Se o blob tiver uma concessão ativa, o cliente deverá especificar uma ID de concessão válida na solicitação para gravar um bloco no blob. 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).

Para um determinado blob, todas as IDs de bloco devem ter o mesmo tamanho. Se um bloco for carregado com uma ID de bloco de comprimento diferente das IDs de bloco para blocos não confirmadas existentes, o serviço retornará o código de resposta de erro 400 (Solicitação Incorreta).

Se você tentar carregar um bloco maior que 4000 MiB para a versão 2019-12-12 e posterior, maior que 100 MiB para a versão 2016-05-31 e posterior e maior que 4 MiB para versões mais antigas, o serviço retornará o código de status 413 (Solicitação Entidade Muito Grande). O serviço também retorna informações adicionais sobre o erro na resposta, inclusive o tamanho máximo permitido do bloco em bytes.

Chamar Put Block não atualiza a hora em que um blob existente foi modificado pela última vez.

Chamar Put Block em um blob de páginas retorna um erro.

Chamar Put Block um blob arquivado retornará um erro e o Hot/Cool blob não alterará a camada de blob.

Consulte Também

Autorizar solicitações para o Azure Armazenamento
Códigos de status e de erro
Códigos de erro do serviço Blob
Configurando os tempos limite para operações de serviço do Blob