Put Block

Artigo
06/13/2024

A operação Put Block cria um novo bloco a ser confirmado como parte de um blob.

Solicitação

Você pode construir a solicitação da Put Block seguinte maneira. Recomendamos que você use HTTPS. 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=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, seguido 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=block&blockid=id`	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
`blockid`	Obrigatórios. Um valor de cadeia de caracteres na Base64 válido que identifica o bloco. Antes de ser codificada, a cadeia de caracteres deve ser menor ou igual a 64 bytes de tamanho. Para um blob especificado, o comprimento do valor do `blockid` parâmetro deve ter 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 do 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órios. Especifica o esquema de autorização, o nome da conta e a assinatura. Confira Autorizar solicitações para o 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.000 miB (mebibytes) de tamanho para a versão 2019-12-12 e posterior. Consulte a seção Comentários para obter limites em versões mais antigas. Quando o comprimento não é fornecido, a operação falha com o código de status 411 (Comprimento Necessá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. 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-content-crc64`	Opcional. Um hash CRC64 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. 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 inválida). Se os cabeçalhos Content-MD5 e x-ms-content-crc64 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 da solicitação. Esse cabeçalho tem suporte nas versões 2019-02-02 e posteriores.
`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 o Armazenamento de Blobs do Azure.

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ó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=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2011-08-18  
x-ms-date: Sun, 25 Sep 2011 14:37:35 GMT  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048576

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 padrão HTTP 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
`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 e não é necessariamente o mesmo 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, 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 e não é necessariamente o mesmo valor especificado nos cabeçalhos de solicitação. Esse cabeçalho é retornado quando `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`	Indica a versão do Armazenamento de Blobs que foi usada para executar a solicitação. Esse cabeçalho é retornado para solicitações que foram feitas na versão 2009-09-19 ou posterior.
`Date`	Um valor de data/hora UTC gerado pelo serviço, que indica quando 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 `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 e posterior. Esse cabeçalho será retornado se a solicitação tiver usado 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. Esse cabeçalho será retornado se a solicitação tiver usado 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 suas 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 e o valor não contiver mais de 1.024 caracteres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho 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: Sun, 25 Sep 2011 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 Put Block operação conforme descrito abaixo.

Importante

A Microsoft recomenda usar a ID do Microsoft Entra com identidades gerenciadas para autorizar solicitações para o 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, um grupo, uma entidade de serviço de aplicativo ou uma 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 de Blob.

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

Permissões

Veja abaixo a ação RBAC necessária para um usuário, grupo, identidade gerenciada ou entidade de serviço do Microsoft Entra chamar a Put Block operação e a função rbac interna do Azure com privilégios mínimos que inclui esta ação:

Ação rbac do Azure: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, confira Atribuir uma função do Azure para acesso aos 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 Put Block operação dá suporte a três tipos de assinaturas de acesso compartilhado: SAS de delegação de usuário, SAS de serviço e SAS de conta.

Como prática recomendada de segurança, recomendamos que você use as credenciais do Microsoft Entra em vez da chave de 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 da conta não será permitido em uma solicitação para o Armazenamento de Blobs. Para saber mais, confira Entender como a não permissão da Chave Compartilhada afeta os tokens SAS.

SAS de delegação do usuário

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

Chamar a Put Block operação usando um token SAS delegado a um contêiner ou recurso de blob requer a permissão 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.

SAS de serviço

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.

Chamar a Put Block operação usando um token SAS delegado a um contêiner ou recurso de blob requer a permissão Gravar (w) como parte do token SAS de serviço.

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

SAS de Conta

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

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

Operação	Serviço assinado	Tipo de recurso assinado	Permissão assinada
Put Block	Blob (b)	Objeto (o)	Gravação (w)

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

Comentários

Put Block carrega um bloco para inclusão futura em um blob de blocos. Cada bloco em um blob de blocos pode ter um tamanho diferente. Um blob de blocos pode incluir no máximo 50.000 blocos confirmados.

A tabela a seguir descreve o máximo permitido de tamanhos de bloco e blob, por versão de serviço:

Versão do serviço	Tamanho máximo do bloco (via `Put Block`)	Tamanho máximo do blob (via `Put Block List`)	Tamanho máximo do blob por meio de operação de gravação única (via `Put Blob`)
Versão 12/12/2019 e posterior	4.000 MiB	Aproximadamente 190,7 tebibytes (TiB) (4.000 MiB × 50.000 blocos)	5.000 MiB
Versões 2016-05-31 a 2019-07-07	100 MiB	Aproximadamente 4,75 TiB (100 MiB × 50.000 blocos)	256 MiB
Versões anteriores a 31/05/2016	4 MiB	Aproximadamente 195 gibibytes (GiB) (4 MiB × 50.000 blocos)	64 MiB

O número máximo de blocos não confirmados que podem ser associados a um blob é 100.000. Se esse número for excedido, o serviço retornará o código de status 409 (RequestEntityTooLargeBlockCountExceedsLimit).

Depois de carregar um conjunto de blocos, você pode criar ou atualizar o blob no servidor desse conjunto chamando a operação Colocar Lista de Blocos . 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 em 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 pela operação List Blobs se a opção include=uncommittedblobs for especificada. O bloco ou os blocos que você carrega não são confirmados até que você chame Put Block List no novo blob. Um blob criado dessa forma é mantido no servidor por uma semana. Se você não adicionou mais blocos ou blocos confirmados ao blob nesse período de tempo, o blob será o lixo coletado.

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

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

Depois Put Block List de ser 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 se não houver chamadas bem-sucedidas para Put Block ou Put Block List no mesmo blob dentro de uma semana após a última operação bem-sucedida Put Block . Se Put Blob for chamado no blob, todos os blocos não confirmados serão coletados.

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 das IDs de bloco para blocos não confirmadas existentes, o serviço retornará o código de resposta de erro 400 (Solicitação Incorreta).

Se você tentar carregar um bloco maior que 4.000 MiB para a versão 2019-12-12 ou posterior, maior que 100 MiB para a versão 2016-05-31 ou posterior ou maior que 4 MiB para versões mais antigas, o serviço retornará o código de status 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 permitido do bloco, em bytes.

Chamar Put Block não atualiza a hora da última modificação de um blob existente.

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

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

Cobrança

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 Put Block solicitações com base no tipo de conta de armazenamento:

Operação	Tipo de conta de armazenamento	Categoria de cobrança
Put Block	Blob de blocos Premium Uso geral v2 Standard Uso geral v1 Standard	Operações de gravação¹

¹Put Block operações gravam blocos no armazenamento temporário usando a camada de acesso padrão da conta de armazenamento. Por exemplo, se você estiver carregando um blob para a camada de arquivo morto, todas Put Block as operações que fazem parte do upload serão cobradas como operações de gravação com base na camada de acesso padrão da conta de armazenamento, não na camada de destino. Put Block List e Put Blob as operações, no entanto, são cobradas como operações de gravação com base na camada de destino do blob.

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

Confira também

Autorizar solicitações para o Armazenamento do Azure
Status e códigos de erro
Códigos de erro do serviço blob
Definir tempos limite para operações de serviço blob

Compartilhar via