Bloco de Acréscimo do URL

  • Artigo

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

A Append Block From URL operação só é permitida se o blob tiver sido criado com x-ms-blob-type definido como AppendBlob. Append Block From URL só é suportado na versão 2018-11-09 ou posterior.

Pedir

Pode construir o pedido da Append Block From URL seguinte forma. É recomendado HTTPS. Substitua myaccount pelo nome da 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 parâmetro de tempo limite é expresso em segundos. Para obter mais informações, veja Definir tempos limite para operações de Armazenamento de Blobs.

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. Especifica o número de bytes que estão a ser transmitidos no corpo do pedido. O valor deste cabeçalho tem de ser definido como zero. Quando o comprimento não for zero, a operação falhará com o código de erro 400 (Pedido Incorreto).
x-ms-copy-source:name Obrigatório. Especifica o URL do blob de origem. O valor pode ser um URL de até 2 KiB de comprimento que especifica um blob. O valor deve ser codificado por URL, tal como apareceria num URI de pedido. O blob de origem tem de ser público ou tem de ser autorizado através de uma assinatura de acesso partilhado. Se o blob de origem for público, não é necessária autorização para executar a operação. Eis alguns exemplos de URLs de objetos de origem:

https://myaccount.blob.core.windows.net/mycontainer/myblob
https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-copy-source-authorization: <scheme> <signature> Opcional. Especifica o esquema de autorização e a assinatura da origem de cópia. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
Apenas o portador do esquema é suportado para Microsoft Entra ID.
Este cabeçalho é suportado na versão 2020-10-02 e posterior.
x-ms-source-range Opcional. Carrega apenas os bytes do blob no URL de origem no intervalo especificado. Se isto não for especificado, todo o conteúdo do blob de origem é carregado como um único bloco de acréscimo. Veja Especificar o cabeçalho do intervalo para operações de Armazenamento de Blobs para obter mais informações.
x-ms-source-content-md5 Opcional. Um Hash MD5 do conteúdo do bloco do apêndice do URI. Este Hash é utilizado para verificar a integridade do bloco de apêndice durante o transporte dos dados do URI. Quando especifica este cabeçalho, o serviço de armazenamento compara o hash do conteúdo que chegou da origem de cópia com este valor de 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 falha com o código de erro 400 (Pedido Incorreto).
x-ms-source-content-crc64 Opcional. Um Hash CRC64 do conteúdo do bloco de apêndice do URI. Este Hash é utilizado para verificar a integridade do bloco de apêndice durante o transporte dos dados do URI. Quando especifica este cabeçalho, o serviço de armazenamento compara o hash do conteúdo que chegou da origem de cópia com este valor de 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 falha com o código de erro 400 (Pedido Incorreto).

Se os cabeçalhos e x-ms-source-content-crc64 os x-ms-source-content-md5 cabeçalhos estiverem presentes, o pedido falha com um 400 (Pedido Incorreto).

Este cabeçalho é suportado na versão 2019-02-02 ou posterior.
x-ms-encryption-scope Opcional. Indica o âmbito de encriptação a utilizar para encriptar o conteúdo de origem. Este cabeçalho é suportado na versão 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. O comprimento máximo em bytes permitido para o blob de acréscimo. Se a Append Block From URL 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 um 412 (Falha na Pré-condição).
x-ms-blob-condition-appendpos Cabeçalho condicional opcional, utilizado apenas para a Append Block from URL operação. Um número que indica o desvio de bytes a comparar. Append Block from URL só é bem-sucedida se a posição de acréscimo for igual a este número. Se não estiver, o pedido falha com um 412 (Falha de 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.

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: 2018-11-09  
x-ms-date: <date>  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0 
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 utiliza o valor para realizar operações condicionais PUT com o cabeçalho do If-Match pedido.
Last-Modified A data/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 Armazenamento de Blobs calcula o valor deste cabeçalho. Não é necessariamente o mesmo valor especificado nos cabeçalhos do pedido. Para a versão 2019-02-02 ou posterior, este cabeçalho só é devolvido quando o pedido tiver este cabeçalho.
x-ms-content-crc64 Para a versão 2019-02-02 ou posterior. Este cabeçalho é devolvido para que o cliente possa verificar a integridade do conteúdo da mensagem. O Armazenamento de Blobs calcula o valor deste cabeçalho. Não é necessariamente o mesmo valor especificado nos cabeçalhos do pedido.

Este cabeçalho é devolvido quando o x-ms-source-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 gerado pelo serviço que indica a hora em que a resposta foi iniciada.
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 com o âmbito de encriptação.

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 From URL operação conforme descrito abaixo.

Os detalhes de autorização nesta secção aplicam-se ao destino de cópia. Para obter mais informações sobre a autorização de origem de cópia, veja os detalhes do cabeçalho x-ms-copy-sourcedo pedido .

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 From URL 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 From URL 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, em que. 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 From URL) 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)

Na versão 2020-10-02 e posterior, Microsoft Entra ID autorização é suportada para a origem da operação de cópia.

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

Os blobs carregados através de não expõem IDs de blocos, pelo Append Block From URL que não pode chamar 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 From URL operação foi efetuada com êxito, apesar da 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 HTTP 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 serviço devolve o código de erro 412.

Se chamar Append Block From URL um blob de bloco ou blob de página existente, o serviço devolve o código de erro 409 (Conflito). Se chamar Append Block From URL um blob inexistente, o serviço devolve o código de erro 404 (Não Encontrado).

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. Isto pode não ser 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 respetiva camada de aplicação. Por exemplo, as aplicações podem adicionar épocas ou números de sequência nos dados que estão a ser acrescentados.

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

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 From URL pedidos com base no tipo de conta de armazenamento:

Operação Tipo de conta de armazenamento Categoria de faturação
URL de Bloco de Acréscimo (conta de destino1) Blob de bloco premium
Standard para fins gerais v2
Standard para fins gerais v1		 Operações de escrita
Anexar Bloco a Partir do URL (conta deorigem 2) Blob de bloco premium
Standard para fins gerais v2
Standard para fins gerais v1		 Operações de leitura

1A conta de destino é cobrada por uma transação para iniciar a escrita.
2A conta de origem incorre numa transação para cada pedido de leitura para a origem.