Bloco de Acréscimo

  • Artigo

A Append Block operação consolida um novo bloco de dados no final de um blob de acréscimo existente.

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

Pedir

Pode construir o pedido da Append Block seguinte forma. É recomendado HTTPS. Substitua myaccount pelo nome de sua conta de armazenamento.

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

Quando estiver a fazer um pedido contra o serviço de armazenamento emulado, especifique o nome do anfitrião do emulador e Armazenamento de Blobs do Azure porta como 127.0.0.1:10000, seguido do nome da conta de armazenamento emulada.

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

Para obter mais informações, veja Utilizar o emulador do Azurite para o desenvolvimento local do Armazenamento do Azure.

Parâmetros URI

Parâmetro Description
timeout Opcional. O timeout parâmetro é expresso em segundos. Para obter mais informações, veja Setting timeouts for Armazenamento de Blobs do Azure operations (Definir tempos limite para operações de Armazenamento de Blobs do Azure).

Cabeçalhos do pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Cabeçalho do pedido Description
Authorization Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Veja Autorizar pedidos para o Armazenamento do Azure para obter mais informações.
Date ou x-ms-date Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
x-ms-version Necessário para todos os pedidos autorizados. Especifica a versão da operação a utilizar para este pedido. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure.
Content-Length Obrigatório. O comprimento do conteúdo do bloco em bytes. O tamanho do bloco tem de ser inferior ou igual a 100 MiB (pré-visualização) em tamanho para a versão 2022-11-02 e posterior. Veja a secção Observações para obter limites em versões mais antigas.

Quando o comprimento não for fornecido, a operação falhará com o código de estado 411 (Comprimento Necessário).
Content-MD5 Opcional. Um Hash MD5 do conteúdo do bloco. Este Hash é utilizado para verificar a integridade do bloco durante o transporte. Quando este cabeçalho é especificado, o serviço de armazenamento compara o hash do conteúdo que chegou com este valor do cabeçalho.

Tenha em atenção que este hash MD5 não está armazenado com o blob.

Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Pedido Incorreto).
x-ms-content-crc64 Opcional. Um Hash CRC64 do conteúdo do bloco do apêndice. Este Hash é utilizado para verificar a integridade do bloco de apêndice durante o transporte. Quando este cabeçalho é especificado, o serviço de armazenamento compara o hash do conteúdo que chegou com este valor do cabeçalho.

Tenha em atenção que este hash CRC64 não está armazenado com o blob.

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

Se ambos os Content-MD5x-ms-content-crc64 cabeçalhos estiverem presentes, o pedido falhará com o código de erro 400.

Este cabeçalho é suportado nas versões 2019-02-02 ou posterior.
x-ms-encryption-scope Opcional. Indica o âmbito de encriptação a utilizar para encriptar o conteúdo do pedido. Este cabeçalho é suportado nas versões 2019-02-02 ou posterior.
x-ms-lease-id:<ID> Necessário se o blob tiver uma concessão ativa. Para efetuar esta operação num blob com uma concessão ativa, especifique o ID de concessão válido para este cabeçalho.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de carateres de 1 kibibyte (KiB) que é registado nos registos quando o registo é configurado. Recomendamos vivamente que utilize este cabeçalho para correlacionar as atividades do lado do cliente com os pedidos que o servidor recebe. Para obter mais informações, veja Monitorizar Armazenamento de Blobs do Azure.
x-ms-blob-condition-maxsize Cabeçalho condicional opcional. Especifica o comprimento máximo em bytes permitidos para o blob de acréscimo. Se a Append Block operação fizer com que o blob exceda esse limite ou se o tamanho do blob já for superior ao valor especificado neste cabeçalho, o pedido falha com o código de erro 412 (Falha na Pré-condição).
x-ms-blob-condition-appendpos Cabeçalho condicional opcional, utilizado apenas para a Append Block operação. Um número indica o desvio de bytes a comparar. Append Block só é bem-sucedida se a posição de acréscimo for igual a este número. Se não estiver, o pedido falha com o código de erro 412 (Falha na Pré-condição).

Esta operação suporta a utilização de cabeçalhos condicionais adicionais para garantir que a API só é bem-sucedida se uma condição especificada for cumprida. Para obter mais informações, veja Especificar cabeçalhos condicionais para operações de Armazenamento de Blobs do Azure.

Cabeçalhos de pedido (chaves de encriptação fornecidas pelo cliente)

A partir da versão 2019-02-02, pode especificar os seguintes cabeçalhos no pedido para encriptar um blob com uma chave fornecida pelo cliente. A encriptação com uma chave fornecida pelo cliente (e o conjunto de cabeçalhos correspondente) é opcional.

Cabeçalho do pedido Description
x-ms-encryption-key Obrigatório. A chave de encriptação AES-256 codificada com Base64.
x-ms-encryption-key-sha256 Obrigatório. O hash SHA256 codificado com Base64 da chave de encriptação.
x-ms-encryption-algorithm: AES256 Obrigatório. Especifica o algoritmo a utilizar para encriptação. O valor deste cabeçalho tem de ser AES256.

Corpo do pedido

O corpo do pedido contém o conteúdo do bloco.

Pedido 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 estado HTTP e um conjunto de cabeçalhos de resposta.

Código de estado

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

Para obter informações sobre códigos de estado, veja Códigos de estado e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os seguintes cabeçalhos. 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
ETag Contém ETag um valor em aspas. O cliente pode utilizar o valor para realizar operações condicionais PUT com o cabeçalho do If-Match pedido.
Last-Modified A data e hora em que o blob foi modificado pela última vez. O formato de data segue RFC 1123. Para obter mais informações, veja Representação dos valores de data/hora nos cabeçalhos.

Qualquer operação de escrita no blob (incluindo atualizações nos metadados ou propriedades do blob) altera a hora da última modificação do blob.
Content-MD5 Este cabeçalho é devolvido para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor deste cabeçalho é calculado pelo Armazenamento de Blobs. Não é necessariamente o mesmo valor especificado nos cabeçalhos do pedido. Para as versões 2019-02-02 ou posterior, este cabeçalho só é devolvido quando o pedido tiver este cabeçalho.
x-ms-content-crc64 Para as versões 2019-02-02 ou posterior, este cabeçalho é devolvido para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor deste cabeçalho é calculado pelo Armazenamento de Blobs. Não é necessariamente o mesmo valor especificado nos cabeçalhos do pedido.

Este cabeçalho é devolvido quando o Content-md5 cabeçalho não está presente no pedido.
x-ms-request-id Este cabeçalho identifica exclusivamente o pedido que foi feito e pode ser utilizado para resolver o pedido.
x-ms-version Indica a versão do Armazenamento de Blobs utilizada para executar o pedido. Este cabeçalho é devolvido para pedidos feitos na versão 2009-09-19 e posterior.
Date Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera este valor.
x-ms-blob-append-offset Este cabeçalho de resposta é devolvido apenas para operações de acréscimo. Devolve o desvio no qual o bloco foi consolidado, em bytes.
x-ms-blob-committed-block-count O número de blocos consolidados presentes no blob. Pode utilizá-lo para controlar quantos mais acréscimos podem ser feitos.
x-ms-request-server-encrypted: true/false Versão 2015-12-11 ou posterior. O valor deste cabeçalho está definido como true se os conteúdos do pedido forem encriptados com êxito com o algoritmo especificado. Caso contrário, o valor está definido como false.
x-ms-encryption-key-sha256 Versão 2019-02-02 ou posterior. Este cabeçalho é devolvido se o pedido tiver utilizado uma chave fornecida pelo cliente para encriptação. Em seguida, o cliente pode garantir que os conteúdos do pedido são encriptados com êxito com a chave fornecida.
x-ms-encryption-scope Versão 2019-02-02 ou posterior. Este cabeçalho é devolvido se o pedido tiver utilizado um âmbito de encriptação. Em seguida, o cliente pode garantir que os conteúdos do pedido são encriptados com êxito através do âmbito de encriptação.
x-ms-client-request-id Pode utilizar este cabeçalho para resolver problemas de pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho se estiver presente no pedido. O valor é, no máximo, 1024 carateres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente no pedido, este cabeçalho não está presente na resposta.

Resposta de amostra

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

A autorização é necessária ao chamar qualquer operação de acesso a dados no Armazenamento do Azure. Pode autorizar a Append Block operação conforme descrito abaixo.

O Armazenamento do Azure suporta a utilização de Microsoft Entra ID para autorizar pedidos para dados de blobs. Com Microsoft Entra ID, pode utilizar o controlo de acesso baseado em funções do Azure (RBAC do Azure) para conceder permissões a um principal de segurança. O principal de segurança pode ser um utilizador, grupo, principal de serviço de aplicação ou identidade gerida do Azure. O principal de segurança é autenticado por Microsoft Entra ID para devolver um token OAuth 2.0. Em seguida, o token pode ser utilizado para autorizar um pedido contra o serviço Blob.

Para saber mais sobre a autorização através de Microsoft Entra ID, veja Autorizar o acesso a blobs com Microsoft Entra ID.

Permissões

Abaixo estão listadas as ações RBAC necessárias para que um utilizador, grupo ou principal de serviço Microsoft Entra chame a Append Block operação e a função RBAC do Azure com menos privilégios que inclua esta ação:

Para saber mais sobre como atribuir funções com o RBAC do Azure, veja Atribuir uma função do Azure para acesso a dados de blobs.

Observações

Append Block carrega um bloco até ao fim de um blob de acréscimo existente. O bloco de dados está imediatamente disponível após a chamada ser efetuada com êxito no servidor. É permitido um máximo de 50 000 acréscimos para cada blob de acréscimo. Cada bloco pode ter um tamanho diferente.

A tabela seguinte descreve os tamanhos máximos permitidos de blocos e blobs, por versão de serviço:

Versão do serviço Tamanho máximo do bloco (via Append Block) Tamanho máximo do blob
Versão 2022-11-02 e posterior 100 MiB (Pré-visualização) Aproximadamente 4,75 TiB (100 MiB × 50.000 blocos)
Versões anteriores a 2022-11-02 4 MiB Aproximadamente 195 gibibytes (GiB) (4 MiB × 50.000 blocos)

Append Block só é bem-sucedido se o blob já existir.

Os blobs carregados com Append Block não expõem IDs de bloco. Não pode ligar para Obter Lista de Blocos num blob de acréscimo. Fazê-lo resulta num erro.

Pode especificar os seguintes cabeçalhos condicionais opcionais no pedido:

  • x-ms-blob-condition-appendpos: pode definir este cabeçalho como um desvio de byte no qual o cliente espera acrescentar o bloco. O pedido só é bem-sucedido se o desvio atual corresponder ao especificado pelo cliente. Caso contrário, o pedido falha com o código de erro 412 (Falha na Pré-condição).

    Os clientes que utilizam um único escritor podem utilizar este cabeçalho para determinar se uma Append Block operação foi efetuada com êxito, apesar de uma falha de rede.

  • x-ms-blob-condition-maxsize: os clientes podem utilizar este cabeçalho para garantir que as operações de acréscimo não aumentam o tamanho do blob para além de um tamanho máximo esperado em bytes. Se a condição falhar, o pedido falhará com o código de erro 412 (Falha na Pré-condição).

Se tentar carregar um bloco maior do que o tamanho permitido, o serviço devolve o código de erro 413 (Entidade do Pedido Demasiado Grande). O serviço também devolve informações adicionais sobre o erro na resposta, incluindo o tamanho máximo de bloco permitido em bytes. Se tentar carregar mais de 50 000 blocos, o serviço devolve o código de erro 409 (Conflito).

Se o blob tiver uma concessão ativa, o cliente tem de especificar um ID de concessão válido no pedido para escrever um bloco no blob. Se o cliente não especificar um ID de concessão ou especificar um ID de concessão inválido, o Armazenamento de Blobs devolve o código de erro 412 (Falha na Pré-condição). Se o cliente especificar um ID de concessão, mas o blob não tiver uma concessão ativa, o Armazenamento de Blobs também devolve o código de erro 412.

Se chamar Append Block um blob de bloco ou blob de página existente, o serviço devolve um erro de conflito. Se chamar Append Block um blob inexistente, o serviço também devolve um erro.

Evitar acréscimos duplicados ou atrasados

Num único cenário de escritor, o cliente pode evitar acréscimos duplicados ou escritas atrasadas utilizando o *x-ms-blob-condition-appendpos cabeçalho condicional para verificar o desvio atual. O cliente também pode evitar duplicados ou atrasos ao verificar condicionalmente, ETag utilizando If-Match.

Num cenário de vários escritores, cada cliente pode utilizar cabeçalhos condicionais, mas este pode não ser o ideal para o desempenho. Para o débito de acréscimo simultâneo mais elevado, as aplicações devem processar acréscimos redundantes e acréscimos atrasados na camada da aplicação. Por exemplo, a aplicação pode adicionar épocas ou números de sequência nos dados que estão a ser acrescentados.

Faturação

Os pedidos de preços podem ter origem em clientes que utilizam APIs de Armazenamento de Blobs, diretamente através da API REST do Armazenamento de Blobs ou a partir de uma biblioteca de cliente do Armazenamento do Azure. Estes pedidos acumulam custos por transação. O tipo de transação afeta a forma como a conta é cobrada. Por exemplo, as transações de leitura acumulam-se numa categoria de faturação diferente das transações de escrita. A tabela seguinte mostra a categoria de faturação dos Append Block pedidos com base no tipo de conta de armazenamento:

Operação Tipo de conta de armazenamento Categoria de faturação
Bloco de Acréscimo Blob de bloco premium
Standard para fins gerais v2
Standard para fins gerais v1		 Operações de escrita

Para saber mais sobre os preços da categoria de faturação especificada, veja Armazenamento de Blobs do Azure Preços.