Compartilhar via

Colocar Bloquear da URL

A Put Block From URL operação cria um novo bloco a ser confirmado como parte de um blob em que o conteúdo é lido de uma URL. Essa API está disponível a partir da versão 28/03/2018.

Solicitação

Você pode construir a solicitação Put Block From URL da seguinte maneira. Recomendamos que você use HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento:

URI da solicitação do método PUT Versão HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=id HTTP/1.1

Solicitação de serviço de armazenamento emulado

Ao fazer uma solicitação no serviço de armazenamento emulado, especifique o nome do host do emulador e a porta do serviço Blob como 127.0.0.1:10000, seguidos pelo nome da conta de armazenamento emulada:

URI da solicitação do método PUT Versão HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=block&blockid=id 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
blockid Obrigatório Um valor de cadeia de caracteres Base64 válido que identifica o bloco. Antes da codificação, a cadeia de caracteres deve ser menor ou igual a 64 bytes de tamanho.

Para um blob especificado, o comprimento do valor especificado para o blockid parâmetro deve ser o mesmo tamanho para cada bloco.

Observação: a cadeia de caracteres Base64 deve ser codificada por URL.
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Definir tempos limite para operações de serviço blob.

Cabeçalhos da solicitação

Os cabeçalhos de solicitação obrigatórios e opcionais são descritos na tabela a seguir:

Cabeçalho da solicitação Descrição
Authorization Obrigatório Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
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. Para Put Block From URL, a versão deve ser 2018-03-28 ou posterior.
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 0. Quando o comprimento não é 0, a operação falha com o código de status 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 kibibytes (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 da origem da cópia. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.

Observação: há suporte apenas para um esquema de portador para o Microsoft Entra.

Observação: se o objeto de origem estiver acessível publicamente ou o objeto de origem estiver em uma conta de armazenamento e você estiver usando um token SAS que está sendo passado em x-ms-copy-source:name, esse cabeçalho não será necessário.

Esse cabeçalho tem suporte nas versões 2020-10-02 e posteriores.
x-ms-source-range Opcional. Carrega apenas os bytes do blob na URL de origem no intervalo especificado. Se esse cabeçalho não for especificado, todo o conteúdo do blob de origem será carregado como um único bloco. Para obter mais informações, consulte Especificar o cabeçalho de intervalo para operações de serviço Blob.
x-ms-source-content-md5 Opcional. Um hash MD5 do conteúdo do bloco do URI. Esse hash é usado para verificar a integridade do bloco durante o transporte dos dados do URI. Quando esse cabeçalho é especificado, o serviço de armazenamento compara o hash do conteúdo que chegou da fonte de cópia com esse valor de cabeçalho.

Observação: 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 do URI. Esse hash é usado para verificar a integridade do bloco durante o transporte dos dados do URI. Quando esse cabeçalho é especificado, o serviço de armazenamento compara o hash do conteúdo que chegou da fonte de cópia com esse valor de cabeçalho.

Observação: 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 tem suporte nas versões 2019-02-02 e posteriores.
x-ms-encryption-scope Opcional. Indica o escopo de criptografia a ser usado para criptografar o conteúdo de origem. Esse cabeçalho tem suporte nas versões 2019-02-02 e posteriores.
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-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.

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

A partir da versão 2019-02-02, os cabeçalhos a seguir 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 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 desse cabeçalho deve ser AES256.

Corpo da solicitação

Nenhum.

Solicitação de exemplo

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2018-03-28  
x-ms-date: Sat, 31 Mar 2018 14:37:35 GMT    
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-499

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 mais 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
Content-MD5 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 que o valor especificado nos cabeçalhos de solicitação. Para as versões 2019-02-02 e posteriores, esse cabeçalho é retornado somente quando a solicitação tem esse cabeçalho.
x-ms-content-crc64 Para as versões 2019-02-02 e posteriores. 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 que o valor especificado nos cabeçalhos da solicitação.

Retornado quando x-ms-source-content-md5 o cabeçalho não está presente na solicitação.
x-ms-request-id Identifica exclusivamente a solicitação que foi feita e você pode usá-la para solucionar problemas da solicitação. Para obter mais informações, consulte Solucionar problemas de operações de API.
x-ms-version A versão do Armazenamento de Blobs que foi usada para executar a solicitação.
Date Um valor de data/hora UTC gerado pelo serviço, que indica a hora em que a resposta foi iniciada.
x-ms-request-server-encrypted: true/false Versão 2015-12-11 e posterior. O valor desse cabeçalho será definido como true se o conteúdo do bloco 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 e posterior. 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 e posterior. 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 Pode ser usado para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho é igual ao valor do cabeçalho x-ms-client-request-id se ele estiver presente na solicitação e o valor não contiver mais de 1.024 caracteres ASCII visíveis. Se o cabeçalho x-ms-client-request-id não estiver presente na solicitação, ele 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: Sat, 31 Mar 2018 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

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 Put Block From URL, conforme descrito abaixo.

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 Azure dá suporte ao uso da ID do Microsoft Entra para autorizar solicitações para 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 pela ID do Microsoft Entra para retornar um token OAuth 2.0. Em seguida, o token pode ser usado para autorizar uma solicitação no serviço 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 Put Block From URL e a função rbac interna do Azure com menos privilégios que inclua esta ação:

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.

Observações

Put Block From URL carrega um bloco para inclusão futura em um blob de blocos. Um blob de blocos pode incluir no máximo 50.000 blocos. Cada bloco pode ter um tamanho diferente. O tamanho máximo de um bloco carregado é Put Block From URL de 100 mebibytes (MiB). Para fazer upload de blocos maiores (até 4.000 MiB), consulte Put Block.

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

Um blob pode ter no máximo 100.000 blocos não confirmados a qualquer momento. Se esse máximo for excedido, o serviço retornará o código de status 409 (RequestEntityTooLargeBlockCountExceedsLimit).

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 Put Block From URL) Tamanho máximo do blob (via Put Block List) Tamanho máximo do blob por meio de uma única operação de gravação (via Put Blob From URL)
Versão 2020-04-08 e posterior 4.000 MiB Aproximadamente 190,7 tebibytes (TiB) (4.000 MiB × 50.000 blocos) 5.000 MiB
Versões anteriores a 2020-04-08 100 MiB Aproximadamente 4,75 TiB (100 MiB × 50.000 blocos) 256 MiB

Depois de carregar um conjunto de blocos, você pode criar ou atualizar o blob no servidor desse conjunto chamando a operação Put Block List . Cada bloco no conjunto é identificado por uma ID de bloco exclusiva dentro desse blob. As IDs de bloco têm como escopo um blob específico, portanto, blobs diferentes podem ter blocos com as mesmas IDs.

Se você chamar Put Block From URL um blob que ainda não existe, um novo blob de blocos será criado com um comprimento de conteúdo de 0. Esse blob será enumerado List Blobs pela operação se a include=uncommittedblobs opção for especificada. O bloco ou blocos que você carregou não são confirmados até que você chame Put Block List o novo blob. Um blob criado dessa maneira é mantido no servidor por uma semana. Se você não tiver adicionado mais blocos ou blocos confirmados ao blob dentro desse período de tempo, o blob será coletado como lixo.

Um bloco que foi carregado com êxito com a Put Block From URL operação não se torna parte de um blob até que seja confirmado com Put Block List. Antes de Put Block List ser chamado para confirmar o blob novo ou atualizado, todas as chamadas para Get Blob retornam o conteúdo do blob sem a inclusão do bloco não confirmado.

Se você carregar um bloco que tenha o mesmo ID de bloco que outro bloco que ainda não foi confirmado, o último bloco carregado com esse ID será confirmado na próxima operação bem-sucedida Put Block List .

Depois de Put Block List chamado, todos os blocos não confirmados especificados na lista de blocos são confirmados como parte do novo blob. Todos os blocos não confirmados que não foram especificados na lista de blocos para o blob são coletados e removidos do Armazenamento de Blobs. Todos os blocos não confirmados também serão coletados como lixo se não houver chamadas bem-sucedidas para Put Block From URL ou Put Block List no mesmo blob dentro de uma semana após a última operação bem-sucedida Put Block From URL . Se Put Blob for chamado no blob, todos os blocos não confirmados serão coletados como lixo.

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 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 Armazenamento de Blobs também retornará o código de status 412 (Falha na pré-condição).

Para um blob especificado, todas as IDs de bloco devem ter o mesmo comprimento. Se um bloco for carregado com uma ID de bloco de comprimento diferente daquela das IDs de bloco para quaisquer blocos não confirmados existentes, o serviço retornará o código de resposta de erro 400 (Solicitação Incorreta).

A chamada Put Block From URL não atualiza a hora da última modificação de um blob existente.

Chamar Put Block From URL um blob de páginas retorna um erro.

Chamar Put Block From URL um blob de 'arquivo' retorna um erro e chamá-lo em um hot blob ou cool não altera a camada de blob.

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

Operação Tipo de conta de armazenamento Categoria de cobrança
Colocar Bloquear do URL (conta de destino1) Blob de blocos Premium
Uso geral padrão v2
Uso geral padrão v1		 Operações de gravação
Colocar Bloquear do URL (conta de origem2) Blob de blocos Premium
Uso geral padrão v2
Uso geral padrão v1		 Operações de leitura

1A conta de destino é cobrada por uma transação para iniciar a gravação.
2A conta de origem incorre em uma transação para cada solicitação de leitura para o objeto de origem.

Além disso, se as contas de origem e destino residirem em regiões diferentes (por exemplo, Norte dos EUA e Sul dos EUA), a largura de banda usada para transferir a solicitação será cobrada para a conta de armazenamento de origem como saída. A saída entre contas na mesma região é gratuita.

Para saber mais sobre os preços das categorias de cobrança especificadas, consulte de Preços do Armazenamento de Blobs do Azure.

Consulte também