Acrescentar Bloco

A Append Block operação confirma um novo bloco de dados ao final de um blob de anexação existente.

A Append Block operação só será permitida se o blob tiver sido criado com definido como x-ms-blob-type AppendBlob . Append Block tem suporte apenas na versão 2015-02-21 ou posterior.

Solicitação

A solicitação Append 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=appendblock 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:

URI de solicitação do método PUT Versão de HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=appendblock HTTP/1.1

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

Parâmetros do URI

Parâmetro Descrição
tempo limite 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. Confira Autorizar solicitações para o Azure Armazenamento 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 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 bloco da solicitação em bytes. O bloco deve ser menor ou igual a 4 MiB de tamanho.

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 de anexação. Esse hash é usado para verificar a integridade do bloco de anexação 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 ambos Content-MD5 os x-ms-content-crc64 headers e 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-encryption-scope Opcional. Indica o escopo de criptografia a ser usado para criptografar o conteúdo da solicitação. Esse header 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 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 logs para rastrear Armazenamento solicitações .
x-ms-blob-condition-maxsize Header condicional opcional. O comprimento máximo em bytes permitido para o blob de anexação. Se a operação faria com que o blob excedesse esse limite ou se o tamanho do blob já fosse maior que o valor especificado nesse cabeçalho, a solicitação falhará com o erro Append Block MaxBlobSizeConditionNotMet (código de status HTTP 412 – Falha na pré-condição).
x-ms-blob-condition-appendpos Header condicional opcional, usado somente para a Append Block operação. Um número que indica o deslocamento de byte a ser comparado. Append Block terá êxito somente se a posição de anexação for igual a esse número. Se não estiver, a solicitação falhará com o erro AppendPositionConditionNotMet (código de status HTTP 412 – Falha na pré-condição).

Essa operação dá suporte ao uso de outros headers condicionais para garantir que a API seja bem-sucedida somente se uma condição especificada 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

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=appendblock  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048  
If-Match: "0x8CB172A360EC34B"  
  

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
ETag A ETag contém um valor entre aspas que o cliente pode usar para executar operações de PUT condicional usando o cabeçalho de solicitação If-Match.
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 valores de Date-Time nos cabeçalhos.

Qualquer operação de gravação no BLOB (incluindo atualizações nos metadados ou propriedades do blob) altera 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. 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 as 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 as 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 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 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-blob-append-offset Esse cabeçalho de resposta é retornado somente para operações de acréscimo. Ele retorna o deslocamento no qual o bloco foi confirmado, em bytes.
x-ms-blob-committed-block-count O número de blocos confirmados presentes no BLOB. Isso pode ser usado para controlar quantos outros acréscimos podem ser feitos.
x-ms-request-server-encrypted: true/false Versão 2015-12-11 ou mais recente. O valor desse cabeçalho será definido como true se o conteúdo da solicitação for criptografado com êxito usando o algoritmo especificado e, false caso contrário,.
x-ms-encryption-key-sha256 Versão 2019-02-02 ou mais recente. Esse cabeçalho é retornado se a solicitação usou 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 é retornado se a solicitação usou 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 é igual ao valor do x-ms-client-request-id cabeçalho se estiver presente na solicitação e o valor for de 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: <date>  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-blob-append-offset: 2097152  
x-ms-blob-committed–block-count: 1000  
  

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

O bloco de acréscimo carrega um bloco no final de um blob de acréscimo existente. O bloco de dados fica imediatamente disponível quando a chamada é realizada com sucesso no servidor. Um bloco pode ter até 4 MiB de tamanho.

Append Block Só terá sucesso se o blob já existir.

Os BLOBs carregados usando não Append Block expõem IDs de bloco, portanto, você não pode chamar a lista de blocos Get em um blob de acréscimo. Isso resulta em um erro 409.

Os seguintes cabeçalhos condicionais opcionais podem ser especificados na solicitação:

  1. x-ms-blob-condition-appendpos: Você pode definir esse cabeçalho como um deslocamento de byte no qual o cliente espera acrescentar o bloco. A solicitação só terá sucesso se o deslocamento atual corresponder ao especificado pelo cliente. Caso contrário, a solicitação falhará com o erro AppendPositionConditionNotMet (código de status HTTP 412 – falha na pré-condição).

    Os clientes que usam um único gravador podem usar esse cabeçalho para determinar se uma operação de bloco de acréscimo foi bem-sucedida, apesar da falha de rede.

  2. x-ms-blob-condition-maxsize: Os clientes podem usar esse cabeçalho para garantir que as operações de acréscimo não aumentem o tamanho do blob além de um tamanho máximo esperado em bytes. Se a condição falhar, a solicitação falhará com o erro MaxBlobSizeConditionNotMet (código de status HTTP 412 – falha na pré-condição).

Cada bloco pode ter um tamanho diferente, até um máximo de 4 MiB. Um máximo de 50.000 acréscimos é permitido para cada blob de acréscimo. O tamanho máximo de um blob de acréscimo é, portanto, um pouco maior do que 195 GiB (4 MiB X 50.000 blocos). Se você tentar carregar um bloco com mais de 4 MiB, o serviço retornará o código de status HTTP 413 (entidade de solicitação 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. Se você tentar carregar mais de 50.000 blocos, o serviço retornará o erro BlockCountExceedsLimit (código de status HTTP 409 – conflito).

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).

Chamar o bloco Append em um blob de blocos existente ou BLOB de páginas retornará um erro InvalidBlobType (código de status http 409-conflito). Chamar o bloco Append em um BLOB não existente retornará um erro BlobNotFound (código de status http 404 – não encontrado).

Evitando acréscimos duplicados ou atrasados

Em um único cenário de gravador, o cliente pode evitar acréscimos duplicados ou gravações atrasadas usando o cabeçalho condicional x-ms-blob-Condition-appendpos para verificar o deslocamento atual ou marcando a ETag condicionalmente usando If-Match .

Em um cenário de vários gravadores, cada cliente pode usar cabeçalhos condicionais, mas isso pode não ser uma abordagem ideal em termos de desempenho. Para a taxa de transferência de acréscimo simultânea mais alta, os aplicativos devem lidar com acréscimos redundantes e acréscimos atrasados em sua camada de aplicativo (por exemplo, adicionar épocas ou números de sequência nos dados que estão sendo acrescentados).