Anexar bloco do URL

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

A Append Block From URL operação só será permitida se o blob tiver sido criado com x-ms-blob-type definido como AppendBlob. Append Block From URL é compatível apenas com a versão 2018-11-09 ou posterior.

Solicitação

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

URI de solicitação do 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 a porta do Armazenamento de Blobs do Azure como 127.0.0.1:10000, seguidos pelo nome da conta de armazenamento emulada.

URI de solicitação do 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 do Azurite para o desenvolvimento local do Armazenamento do Azure.

Parâmetros de URI

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

Cabeçalhos da solicitação

A tabela a seguir descreve cabeçalhos de solicitação obrigatórios e opcionais.

Cabeçalho da solicitação	Descrição
`Authorization`	Obrigatório Especifica o esquema de autorização, o nome da conta e a assinatura. Consulte Autorizar solicitações para o Armazenamento do Azure para obter mais informações.
`Date` ou `x-ms-date`	Obrigatório Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para obter mais informações, consulte 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 essa solicitação. Para obter mais informações, consulte Controle de versão para os serviços de Armazenamento do Azure.
`Content-Length`	Obrigatório Especifica o número de bytes que estão sendo transmitidos no corpo da solicitação. O valor desse cabeçalho deve ser definido como zero. Quando o comprimento não for zero, a operação falhará com o código de erro 400 (Solicitação Incorreta).
`x-ms-copy-source:name`	Obrigatório Especifica a URL do blob de origem. O valor pode ser uma URL de até 2 KiB de comprimento que especifica um blob. O valor deve ser codificado em URL, como apareceria em um URI de solicitação. O blob de origem deve ser público ou autorizado por meio de uma assinatura de acesso compartilhado. Se o blob de origem for público, nenhuma autorização será necessária para executar a operação. Aqui estão alguns exemplos de URLs de objeto 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 para a origem da cópia. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure. Somente o portador do esquema é suportado para a ID do Microsoft Entra. Esse cabeçalho tem suporte na versão 2020-10-02 e posterior.
`x-ms-source-range`	Opcional. Carrega apenas os bytes do blob na URL de origem no intervalo especificado. Se isso não for especificado, todo o conteúdo do blob de origem será carregado como um único bloco de acréscimo. Consulte Especificando o cabeçalho de 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 de acréscimo do URI. Esse hash é usado para verificar a integridade do bloco de acréscimo durante o transporte dos dados do URI. Quando você especifica esse cabeçalho, o serviço de armazenamento compara o hash do conteúdo que chegou da fonte de cópia 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-source-content-crc64`	Opcional. Um hash CRC64 do conteúdo do bloco de acréscimo do URI. Esse hash é usado para verificar a integridade do bloco de acréscimo durante o transporte dos dados do URI. Quando você especifica esse cabeçalho, o serviço de armazenamento compara o hash do conteúdo que chegou da fonte de cópia 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 e `x-ms-source-content-md5x-ms-source-content-crc64` cabeçalhos estiverem presentes, a solicitação falhará com um 400 (Solicitação Incorreta). Esse cabeçalho é compatível com a versão 2019-02-02 ou posterior.
`x-ms-encryption-scope`	Opcional. Indica o escopo de criptografia a ser usado para criptografar o conteúdo de origem. Esse cabeçalho é compatível com a versão 2019-02-02 ou posterior.
`x-ms-lease-id:<ID>`	Necessá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 o 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 maior que o valor especificado nesse cabeçalho, a solicitação falhará com um 412 (Falha na pré-condição).
`x-ms-blob-condition-appendpos`	Cabeçalho condicional opcional, usado apenas para a `Append Block from URL` operação. Um número que indica o deslocamento de bytes a ser comparado. `Append Block from URL` só será bem-sucedido se a posição de acréscimo for igual a esse número. Se não for, a solicitação falhará com um 412 (Falha na pré-condição).
`x-ms-file-request-intent`	Obrigatório se `x-ms-copy-source` o cabeçalho for uma URL de arquivo do Azure e `x-ms-copy-source-authorization` o cabeçalho especificar um token OAuth. O valor aceitável é `backup`. Esse cabeçalho especifica que os `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` ou `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` devem ser concedidos se forem incluídos na política RBAC atribuída à identidade autorizada usando o cabeçalho `x-ms-copy-source-authorization`. Disponível para a versão 2025-07-05 e posterior.

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.

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ório A chave de criptografia AES-256 codificada em Base64.
`x-ms-encryption-key-sha256`	Obrigatório O hash SHA256 codificado em Base64 da chave de criptografia.
`x-ms-encryption-algorithm: AES256`	Obrigatório 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 contém 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: 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 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 dessa 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 de protocolo HTTP/1.1 .

Cabeçalho de resposta	Descrição
`Etag`	O `ETag` contém um valor entre aspas. O cliente usa o valor para executar operações condicionais `PUT` usando o cabeçalho da `If-Match` solicitação.
`Last-Modified`	A data/hora em que o blob foi modificado pela última vez. O formato de data segue o 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 Armazenamento de Blobs calcula o valor desse cabeçalho. Não é necessariamente o mesmo valor especificado nos cabeçalhos da solicitação. Para a versão 2019-02-02 ou posterior, esse cabeçalho só é retornado quando a solicitação tem esse cabeçalho.
`x-ms-content-crc64`	Para a versão 2019-02-02 ou posterior. Esse cabeçalho é retornado para que o cliente possa verificar a integridade do conteúdo da mensagem. O Armazenamento de Blobs calcula o valor desse cabeçalho. Não é necessariamente o mesmo valor especificado nos cabeçalhos da solicitação. Esse cabeçalho é retornado quando o `x-ms-source-content-md5` cabeçalho não está presente na solicitação.
`x-ms-request-id`	Esse cabeçalho identifica exclusivamente a solicitação 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 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`	Esse cabeçalho de resposta é retornado apenas para operações de acréscimo. 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 como `true` 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. 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. O cliente pode garantir que o conteúdo da solicitação seja criptografado com êxito usando o escopo de criptografia.

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

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

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

Importante

A Microsoft recomenda usar a ID do Microsoft Entra com identidades gerenciadas para autorizar solicitações ao Armazenamento do Azure. A ID do Microsoft Entra fornece segurança superior e facilidade de uso em comparação com a autorização de Chave Compartilhada.

O Armazenamento do Microsoft Azure dá suporte ao uso do Microsoft Entra ID para autorizar solicitações de dados de blob. Com a ID do Microsoft Entra, você pode usar o RBAC (controle de acesso baseado em função) do Azure para conceder permissões a uma entidade de segurança. A entidade de segurança pode ser um usuário, grupo, entidade de serviço de aplicativo ou identidade gerenciada do Azure. A entidade de segurança é autenticada pelo Microsoft Entra ID para retornar um token OAuth 2.0. Em seguida, o token pode ser usado para autorizar uma solicitação no serviço de Blob.

Para saber mais sobre a autorização usando a ID do Microsoft Entra, consulte Autorizar o acesso a blobs usando a ID do Microsoft Entra.

Permissões

Veja abaixo a ação RBAC necessária para que um usuário, grupo, identidade gerenciada ou entidade de serviço do Microsoft Entra chame a operação Append Block From URL e a função rbac interna do Azure com menos privilégios que inclua esta ação:

Ação do RBAC do Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action ou Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Função interna com privilégios mínimos:colaborador de dados de blob de armazenamento

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

Uma SAS (assinatura de acesso compartilhado) fornece acesso delegado seguro aos recursos em uma conta de armazenamento. Com uma SAS, você tem controle granular sobre como um cliente pode acessar dados. Você pode especificar qual recurso o cliente pode acessar, quais permissões eles têm para esses recursos e por quanto tempo a SAS é válida.

A operação dá suporte a três tipos de assinaturas de acesso compartilhado: sas de delegação de usuário,SAS do serviço e conta SAS.

Como prática recomendada de segurança, recomendamos que você use as credenciais do Microsoft Entra em vez da chave da conta de armazenamento, que pode ser comprometida com mais facilidade. Se o design do aplicativo exigir assinaturas de acesso compartilhado, use as credenciais do Microsoft Entra para criar uma SAS de delegação de usuário, quando possível.

Quando o acesso à Chave Compartilhada não for permitido para a conta de armazenamento, um token SAS de serviço ou um token SAS de conta não será permitido em uma solicitação ao Armazenamento de Blobs. Para saber mais, consulte Entender como a não permissão de Chave Compartilhada afeta tokens SAS.

SAS de delegação do usuário

Uma SAS de delegação do usuário é protegida com as credenciais do Microsoft Entra e também pelas permissões especificadas para a SAS.

Chamar a Append Block From URL operação usando um token SAS delegado a um contêiner ou recurso de blob requer a permissão Adicionar (a) ou Gravar (w) como parte do token SAS de delegação do usuário:

Para saber mais sobre a SAS de delegação de usuário, consulte Criar uma SAS de delegação de usuário.

Serviço SAS

Uma SAS de serviço é protegida com a chave da conta de armazenamento. Uma SAS de serviço delega acesso a um recurso em um único serviço de Armazenamento do Azure, como o armazenamento de blobs.

Para saber mais sobre a SAS de serviço, consulte Criar uma SAS de serviço.

SAS da conta

Uma SAS de conta é protegida com a chave da conta de armazenamento. Uma conta SAS delega acesso aos recursos em um ou mais dos serviços de armazenamento. Todas as operações disponíveis por meio de um serviço ou delegação de usuário SAS também estão disponíveis por meio de um SAS de conta.

A tabela a seguir indica o tipo de recurso assinado e as permissões assinadas a serem especificadas ao delegar o acesso:

Operação	Serviço assinado	Tipo de recurso assinado	Permissão assinada
Anexar bloco do URL	Bolha (b)	Objeto (o)	Adicionar (a) ou Gravar (w)

Para saber mais sobre a SAS da conta, consulte Criar uma conta sas.

A operação Append Block From URL dá suporte a de autorização de chave compartilhada. A autorização com chaves de conta não é recomendada para a maioria dos cenários, pois é menos segura.

A Microsoft recomenda não permitir a autorização de Chave Compartilhada para a conta de armazenamento quando possível. Para obter mais informações, consulte Impedir autorização com chave compartilhada.

Observações

Append Block From URL Carrega um bloco no final de um blob de acréscimo existente. O bloco de dados fica imediatamente disponível após a chamada ser bem-sucedida no servidor. Um máximo de 50.000 acréscimos são permitidos para cada blob de acréscimo. Cada bloco pode ser de tamanho diferente.

A tabela a seguir descreve os tamanhos máximos permitidos de bloco e blob, 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 (versão prévia)	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, há suporte para a autorização de ID do Microsoft Entra para a origem da operação de cópia.

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

Os blobs carregados usando Append Block From URL não expõem IDs de bloco, portanto, você não pode chamar Obter Lista de Blocos em um blob de acréscimo. Isso resulta em um erro.

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

x-ms-blob-condition-appendpos: Você pode definir esse cabeçalho como um deslocamento de byte no qual o cliente espera anexar o bloco. A solicitação será bem-sucedida somente 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 From URL operação foi bem-sucedida, apesar da 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 de um 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).

Se você tentar carregar um bloco maior que o tamanho permitido, o serviço retornará o código de erro HTTP 413 (Entidade de Solicitação Muito Grande). O serviço também retorna informações adicionais sobre o erro na resposta, incluindo o tamanho máximo do bloco permitido 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 serviço retornará o código de erro 412.

Se você chamar Append Block From URL um blob de blocos ou um blob de páginas existente, o serviço retornará o código de erro 409 (Conflito). Se você chamar Append Block From URL um blob inexistente, o serviço retornará o código de erro 404 (Não Encontrado).

Evite acréscimos duplicados ou atrasados

Em um cenário de gravador único, 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 a ETag condicionalmente, usando If-Matcho .

Em um cenário de vários gravadores, cada cliente pode usar cabeçalhos condicionais. Isso pode não ser ideal para o desempenho. Para obter a maior taxa de transferência de acréscimo simultâneo, os aplicativos devem lidar com acréscimos redundantes e acréscimos atrasados em sua camada de aplicativo. Por exemplo, os aplicativos podem adicionar épocas ou números de sequência nos dados que estão sendo acrescentados.

Para saber mais sobre os preços da categoria de cobrança especificada, consulte de Preços do Armazenamento de Blobs do Azure.

Faturamento

As solicitações de preços podem ser originadas de clientes que usam APIs de Armazenamento de Blobs, diretamente por meio da API REST do Armazenamento de Blobs ou de uma biblioteca de clientes do Armazenamento do Azure. Essas solicitações acumulam encargos por transação. O tipo de transação afeta a forma como a conta é cobrada. Por exemplo, as transações de leitura se acumulam em uma categoria de cobrança diferente das transações de gravação. A tabela a seguir mostra a categoria de cobrança para solicitações Append Block From URL com base no tipo de conta de armazenamento:

Operação	Tipo de conta de armazenamento	Categoria de cobrança
Anexar Bloquear do URL (conta^{de destino 1})	Blob de blocos Premium Uso geral v2 Standard Uso geral v1 Standard	Operações de gravação
Anexar bloqueio da URL (conta de origem²)	Blob de blocos Premium Uso geral v2 Standard Uso geral v1 Standard	Operações de leitura

¹A conta de destino é cobrada por uma transação para iniciar a gravação.
^algarismoA conta de origem incorre em uma transação para cada solicitação de leitura para a origem.

Last updated on 2025-05-11

Compartilhar via