Bloco acréscimo

Artigo
02/02/2023
10 minutos para o fim da leitura

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

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

Solicitação

Você pode construir a solicitação da Append Block seguinte maneira. HTTPS é recomendado. Substitua myaccount com o nome da sua conta de armazenamento.

URI de solicitação de método PUT	Versão 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 do host do emulador e Armazenamento de Blobs do Azure porta como 127.0.0.1:10000, seguido pelo nome da conta de armazenamento emulada.

URI de solicitação 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, consulte Usar o emulador Azurite para desenvolvimento local do armazenamento do Azure.

Parâmetros do URI

Parâmetro	Descrição
`timeout`	Opcional. O parâmetro `timeout` é expresso em segundos. Para obter mais informações, consulte Configurando tempos limite para operações de Armazenamento de Blobs do Azure.

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. Confira Autorizar solicitações ao 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 saber mais, confira Autorizar solicitações para o 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 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 acréscimo. Esse hash é usado para verificar a integridade do bloco de acréscimo 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 `Content-MD5` cabeçalhos e `x-ms-content-crc64` estiverem presentes, a solicitação falhará com o código de erro 400. 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 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.
`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 maior que o valor especificado neste cabeçalho, a solicitação falhará com o código de erro 412 (Falha na pré-condição).
`x-ms-blob-condition-appendpos`	Cabeçalho condicional opcional, usado apenas para a `Append Block` operação. Um número indica o deslocamento de bytes a ser comparado. `Append Block` só terá êxito se a posição de acréscimo for igual a esse número. Se não for, a solicitação falhará com o código de erro 412 (Falha na pré-condição).

Essa operação dá suporte ao uso de cabeçalhos condicionais adicionais para garantir que a API seja bem-sucedida somente se uma condição especificada for atendida. Para obter mais informações, consulte Especificando cabeçalhos condicionais para operações de Armazenamento de Blobs do Azure.

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

A partir da versão 2019-02-02, você pode especificar os cabeçalhos a seguir 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=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 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
`ETag`	O `ETag` contém um valor entre aspas. O cliente pode usar o valor para executar operações condicionais `PUT` usando o cabeçalho da solicitação `If-Match` .
`Last-Modified`	A data e hora da última modificação do blob. O formato da data segue RFC 1123. Para obter mais informações, consulte Representação de valores de data e hora em 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 é calculado pelo Armazenamento de Blobs. 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 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 é calculado pelo Armazenamento de Blobs. Não é necessariamente o mesmo valor especificado nos cabeçalhos de solicitação. Esse cabeçalho é retornado quando o `Content-md5` cabeçalho não está presente na solicitação.
`x-ms-request-id`	Esse cabeçalho identifica exclusivamente a solicitação que foi feita e pode ser usado para solucionar problemas da solicitação.
`x-ms-version`	Indica a versão do Armazenamento de Blobs usada 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 que indica a hora em que a resposta foi iniciada. O serviço gera esse valor.
`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. Você pode usar isso para controlar quantos acréscimos mais podem ser feitos.
`x-ms-request-server-encrypted: true/false`	Versão 2015-12-11 ou posterior. O valor desse cabeçalho será definido `true` como se o conteúdo da solicitação for criptografado com êxito usando o algoritmo especificado. Caso contrário, o valor será definido como `false`.
`x-ms-encryption-key-sha256`	Versão 2019-02-02 ou posterior. Esse cabeçalho será retornado se a solicitação tiver usado uma chave fornecida pelo cliente para criptografia. Em seguida, o cliente pode 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 posterior. Esse cabeçalho será retornado se a solicitação tiver usado um escopo de criptografia. Em seguida, o cliente pode garantir que o conteúdo da solicitação seja criptografado com êxito usando o escopo de criptografia.
`x-ms-client-request-id`	Você pode usar esse cabeçalho 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. O valor é, 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.

Resposta de exemplo

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

O proprietário da conta pode chamar essa operação. Qualquer pessoa com uma assinatura de acesso compartilhado que tenha permissão para gravar nesse blob ou em seu contêiner também pode chamar essa operação.

Comentários

Append Block carrega um bloco até o final de um blob de acréscimo existente. O bloco de dados fica imediatamente disponível depois que a chamada é bem-sucedida no servidor. Um bloco pode ter até 4 MiB de tamanho.

Append Block só terá êxito se o blob já existir.

Os blobs carregados usando Append Block não expõem IDs de bloco. Você não pode chamar Obter Lista de Bloqueios em um blob de acréscimo. Isso resulta em um erro.

Você pode especificar os seguintes cabeçalhos opcionais e condicionais na solicitação:

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

Os clientes que usam um único gravador podem usar esse cabeçalho para determinar se uma Append Block operação foi bem-sucedida, apesar de uma falha de rede.
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 do tamanho máximo esperado em bytes. Se a condição falhar, a solicitação falhará com o código de erro 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 são permitidos para cada blob de acréscimo. O tamanho máximo de um blob de acréscimo é, portanto, um pouco mais de 195 GiB (4 MiB X 50.000 blocos).

Se você tentar carregar um bloco maior que 4 MiB, o serviço retornará o código de erro 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 código de erro 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 de concessão inválida, o Armazenamento de Blobs retornará o código de erro 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 Armazenamento de Blobs também retornará o código de erro 412.

Se você chamar Append Block em um blob de blocos ou blob de páginas existente, o serviço retornará um erro de conflito. Se você chamar Append Block em um blob inexistente, o serviço também retornará um erro.

Evitar 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 *x-ms-blob-condition-appendpos cabeçalho condicional para verificar o deslocamento atual. O cliente também pode evitar duplicatas ou atrasos verificando o ETag condicionalmente, usando If-Match.

Em um cenário de gravador múltiplo, cada cliente pode usar cabeçalhos condicionais, mas isso pode não ser ideal para o desempenho. Para a maior taxa de transferência de acréscimo simultânea, os aplicativos devem lidar com acréscimos redundantes e acréscimos atrasados na camada do aplicativo. Por exemplo, o aplicativo pode adicionar épocas ou números de sequência nos dados que estão sendo acrescentados.