Put Blob

A Put Blob operação cria um novo blob de bloco, página ou acréscimo ou atualiza o conteúdo de um blob de blocos existente.

Ao atualizar um blob de blocos existente, você substitui todos os metadados existentes no blob. Não há suporte para atualizações parciais com Put Blob. O conteúdo do blob existente é substituído pelo conteúdo do novo blob. Para executar uma atualização parcial do conteúdo de um blob de blocos, use a operação Colocar Lista de Blocos .

Você pode criar um blob de acréscimo nas versões 2015-02-21 e posteriores apenas.

Uma chamada para um Put Blob para criar um blob de páginas ou um blob de acréscimo inicializa apenas o blob. Para adicionar conteúdo a um blob de páginas, chame a operação Colocar Página . Para adicionar conteúdo a um blob de acréscimo, chame a operação Anexar Bloco .

Solicitação

Você pode construir a solicitação da Put Blob 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 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 HTTP/1.1

O emulador de armazenamento dá suporte apenas a tamanhos de blob de até 2 gibibytes (GiB).

Para obter mais informações, consulte Usar o emulador Azurite para desenvolvimento local do armazenamento do Azure.

Parâmetros do URI

Os seguintes parâmetros adicionais podem ser especificados no URI de solicitação:

Parâmetro Descrição
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 de solicitação (todos os tipos de blob)

Os cabeçalhos de solicitação obrigatórios e opcionais para todos os tipos de blob 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. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
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 da solicitação.

Para um blob de páginas ou um blob de acréscimo, o valor desse cabeçalho deve ser definido como zero, pois Put Blob é usado apenas para inicializar o blob. Para gravar conteúdo em um blob de páginas existente, chame Put Page. Para gravar conteúdo em um blob de acréscimo, chame Append Block.
Content-Type Opcional. O tipo de conteúdo MIME do blob. O tipo padrão é application/octet-stream.
Content-Encoding Opcional. Especifica quais codificações de conteúdo foram aplicadas ao blob. Esse valor é retornado ao cliente quando a operação Obter Blob é executada no recurso de blob. Quando esse valor é retornado, o cliente pode usá-lo para decodificar o conteúdo do blob.
Content-Language Opcional. Especifica as linguagens naturais usadas por esse recurso.
Content-MD5 Opcional. Um hash MD5 do conteúdo do blob. O hash é usado para verificar a integridade do blob durante o transporte. Quando esse cabeçalho é especificado, o serviço de armazenamento verifica o hash que chegou em relação ao que foi enviado. Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação Incorreta).

Quando o cabeçalho é omitido na versão 2012-02-12 ou posterior, o Armazenamento de Blobs gera um hash MD5.

Os resultados de Obter Blob, Obter Propriedades de Blob e Listar Blobs incluem o hash MD5.
x-ms-content-crc64 Opcional. Um hash CRC64 do conteúdo do blob. O hash é usado para verificar a integridade do blob durante o transporte. Quando esse cabeçalho é especificado, o serviço de armazenamento verifica o hash que chegou em relação ao que foi enviado. Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação Incorreta). Esse cabeçalho tem suporte nas versões 02-02-2019 e posteriores.

Se os cabeçalhos Content-MD5 e x-ms-content-crc64 estiverem presentes, a solicitação falhará com um 400 (Solicitação Incorreta).
Cache-Control Opcional. O Armazenamento de Blobs armazena esse valor, mas não o usa nem o modifica.
x-ms-blob-content-type Opcional. Defina o tipo de conteúdo do blob.
x-ms-blob-content-encoding Opcional. Defina a codificação do conteúdo do blob.
x-ms-blob-content-language Opcional. Defina o idioma do conteúdo do blob.
x-ms-blob-content-md5 Opcional. Defina o hash MD5 do blob.
x-ms-blob-cache-control Opcional. Define o controle de cache do blob.
x-ms-blob-type: <BlockBlob ¦ PageBlob ¦ AppendBlob> Obrigatórios. Especifica o tipo de blob a ser criado: blob de blocos, blob de páginas ou blob de acréscimo. O suporte para criar um blob de acréscimo só está disponível na versão 2015-02-21 e posterior.
x-ms-meta-name:value Opcional. Pares de nome-valor associados ao blob como metadados.

Observação: a partir da versão 2009-09-19, os nomes de metadados devem seguir as regras de nomenclatura para identificadores C#.
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-tags Opcional. Define as marcas codificadas de cadeia de caracteres de consulta fornecidas no blob. Consulte os Comentários para obter informações adicionais. Com suporte na versão 2019-12-12 e 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-blob-content-disposition Opcional. Define o cabeçalho Content-Disposition do blob. Disponível para versões 2013-08-15 e posteriores.

O Content-Disposition campo cabeçalho de resposta transmite informações adicionais sobre como processar o conteúdo da resposta e você pode usá-lo para anexar metadados adicionais. Por exemplo, se o cabeçalho estiver definido attachmentcomo , isso indicará que o agente do usuário não deve exibir a resposta. Em vez disso, ele deve exibir uma caixa de diálogo Salvar como com um nome de arquivo diferente do nome de blob especificado.

A resposta das operações Obter Propriedades de Blob e Obter Blob inclui o content-disposition cabeçalho .
Origin Opcional. Especifica a origem da qual a solicitação será emitida. A presença desse cabeçalho resulta em recursos de origens cruzadas compartilhando (CORS) cabeçalhos na resposta. Para obter mais informações, consulte Suporte a CORS para os serviços de Armazenamento do Azure.
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 de análise 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 Sobre o log de análise de armazenamento.
x-ms-access-tier Opcional. A camada a ser definida no blob. Para blobs de páginas em uma conta Armazenamento Premium somente com a versão 2017-04-17 e posterior. Para obter uma lista completa das camadas compatíveis com blob de páginas, consulte Armazenamento premium de alto desempenho e discos gerenciados para VMs (máquinas virtuais). Para blobs de blocos, com suporte no armazenamento de blobs ou contas de uso geral v2 somente com a versão 2018-11-09 e posterior. Os valores válidos para camadas de blob de blocos são Hot, Cool, Colde Archive. Para obter informações detalhadas sobre camadas de blob de blocos, consulte Camadas de armazenamento frequentes, esporádicas e de arquivos. Observação: Cold a camada está atualmente em versão prévia e tem suporte para a versão 2021-12-02 e posterior.
x-ms-immutability-policy-until-date Versão 2020-06-12 e posterior. Especifica a data de retenção até ser definida no blob. Essa é a data até a qual o blob pode ser protegido contra modificação ou exclusão. Segue o formato RFC1123.
x-ms-immutability-policy-mode Versão 2020-06-12 e posterior. Especifica o modo de política de imutabilidade a ser definido no blob. Os valores válidos são unlocked e locked. Com unlockedo , os usuários podem alterar a política aumentando ou diminuindo a data de retenção até. Com locked, essas ações são proibidas.
x-ms-legal-hold Versão 2020-06-12 e posterior. Especifica a retenção legal a ser definida no blob. Os valores válidos são true e false.

Essa operação também dará suporte ao uso de cabeçalhos condicionais para gravar o blob somente se uma determinada condição for atendida. Para obter mais informações, consulte Especificar cabeçalhos condicionais para operações de Armazenamento de Blobs.

Cabeçalhos de solicitação (somente blobs de páginas)

Os cabeçalhos de solicitação aplicáveis somente para operações em blobs de páginas são descritos na tabela a seguir:

Cabeçalho da solicitação Descrição
x-ms-blob-content-length: bytes Necessário para blobs de páginas. Esse cabeçalho especifica o tamanho máximo para o blob de páginas, até 8 tebibytes (TiB). O tamanho do blob de páginas deve ser alinhado a um limite de 512 bytes.

Se esse cabeçalho for especificado para um blob de blocos ou um blob de acréscimo, o Armazenamento de Blobs retornará o código de status 400 (Solicitação Incorreta).
x-ms-blob-sequence-number: <num> Opcional. Defina para blobs de página apenas. O número de sequência é um valor controlado pelo usuário que você pode usar para rastrear solicitações. O valor do número de sequência deve ser de 0 a 2^63 – 1. O valor padrão é 0.
x-ms-access-tier Versão 2017-04-17 e posterior. Somente para blobs de páginas em uma conta de armazenamento Premium. Especifica a camada a ser definida no blob. Para obter uma lista completa de camadas com suporte, consulte Armazenamento premium de alto desempenho e discos gerenciados para VMs.
x-ms-client-request-id Esse cabeçalho pode ser usado 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 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.

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

Para um blob de blocos, o corpo da solicitação tem o conteúdo do blob.

Para um blob de páginas ou um blob de acréscimo, o corpo da solicitação está vazio.

Solicitação de exemplo

O exemplo a seguir mostra uma solicitação para criar um blob de blocos:

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblockblob HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
Content-Type: text/plain; charset=UTF-8  
x-ms-blob-content-disposition: attachment; filename="fname.ext"  
x-ms-blob-type: BlockBlob  
x-ms-meta-m1: v1  
x-ms-meta-m2: v2  
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=  
Content-Length: 11  
  
Request Body:  
hello world

Esta solicitação de exemplo cria um blob de páginas e especifica seu tamanho máximo como 1.024 bytes. Para adicionar conteúdo a um blob de páginas, você deve chamar Put Page:

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/mypageblob HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
Content-Type: text/plain; charset=UTF-8  
x-ms-blob-type: PageBlob  
x-ms-blob-content-length: 1024  
x-ms-blob-sequence-number: 0  
Authorization: SharedKey   
Origin: http://contoso.com  
Vary: Origin  
myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=  
Content-Length: 0  

Esta solicitação de exemplo cria um blob de acréscimo. Para adicionar conteúdo ao blob de acréscimo, você deve chamar o Bloco de Acréscimo:

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myappendblob HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
Content-Type: text/plain; charset=UTF-8  
x-ms-blob-type: AppendBlob  
Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g=  
Origin: http://contoso.com  
Vary: Origin  
Content-Length: 0  

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 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 Contém um valor que o cliente pode usar para executar operações condicionais PUT usando o cabeçalho da solicitação If-Match . Se a versão da solicitação for 2011-08-18 ou posterior, o valor de ETag será colocado entre aspas.
Last-Modified A data/hora em que o blob foi modificado pela última vez. O formato da data segue RFC 1123. Para obter mais informações, consulte Representar valores de data/hora em cabeçalhos.

Qualquer operação de gravação no blob (incluindo atualizações nos metadados ou nas propriedades do blob), altera a hora da última modificação do blob.
Content-MD5 Retornado para um blob de blocos para que o cliente possa verificar a integridade do conteúdo da mensagem. O Content-MD5 valor retornado é calculado pelo Armazenamento de Blobs. Na versão 2012-02-12 e posterior, esse cabeçalho é retornado mesmo quando a solicitação não inclui Content-MD5 cabeçalhos ou x-ms-blob-content-md5 .
x-ms-content-crc64 Retornado para um blob de blocos para que o cliente possa verificar a integridade do conteúdo da mensagem. O x-ms-content-crc64 valor retornado é calculado pelo Armazenamento de Blobs. Esse cabeçalho sempre é retornado a partir da versão 2019-02-02.
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. 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.
Access-Control-Allow-Origin Retornado se a solicitação incluir um cabeçalho Origin e CORS estiver habilitado com uma regra de correspondência. Esse cabeçalho retornará o valor do cabeçalho de solicitação de origem se houver uma correspondência.
Access-Control-Expose-Headers Retornado se a solicitação incluir um cabeçalho Origin e CORS estiver habilitado com uma regra de correspondência. Retorna a lista de cabeçalhos de resposta que devem ser expostos ao cliente ou ao emissor da solicitação.
Access-Control-Allow-Credentials Retornado se a solicitação incluir um Origin cabeçalho e CORS estiver habilitado com uma regra correspondente que não permita todas as origens. Esse cabeçalho é definido como true.
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 é 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-version-id: <DateTime> Versão 2019-12-12 e posterior. Esse cabeçalho retorna um valor opaco DateTime que identifica exclusivamente o blob. O valor desse cabeçalho indica a versão do blob e pode ser usado em solicitações subsequentes para acessar o blob.

Corpo da resposta

Nenhum.

Resposta de exemplo

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==  
x-ms-content-crc64: 77uWZTolTHU
Date: <date>  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: <date>  
Access-Control-Allow-Origin: http://contoso.com  
Access-Control-Expose-Headers: Content-MD5  
Access-Control-Allow-Credentials: True  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-version-id: <DateTime>  

Autorização

Essa operação pode ser chamada pelo proprietário da conta e por qualquer cliente com uma assinatura de acesso compartilhado que tenha permissão para gravar nesse blob ou em seu contêiner.

Se uma solicitação especificar marcas com o cabeçalho da x-ms-tags solicitação, o chamador deverá atender aos requisitos de autorização da operação Definir Marcas de Blob .

Comentários

Ao criar um blob, você deve especificar se ele é um blob de blocos, blob de acréscimo ou blob de página especificando o valor do x-ms-blob-type cabeçalho. Depois que um blob for criado, o tipo do blob não poderá ser alterado, a menos que seja excluído e recriado.

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) 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 mebibytes (MiB) Aproximadamente 190,7 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 2016-05-31 4 MiB Aproximadamente 195 GiB (4 MiB × 50.000 blocos) 64 MiB

Se você tentar carregar um blob de blocos maior que o tamanho máximo permitido para essa versão de serviço ou um blob de página maior que 8 TiB, o serviço retornará o código de status 413 (Entidade de Solicitação Muito Grande). O Armazenamento de Blobs também retorna informações adicionais sobre o erro na resposta, incluindo o tamanho máximo permitido do blob, em bytes.

Para criar um novo blob de páginas, primeiro inicialize o blob chamando Put Blobe especifique seu tamanho máximo, até 8 TiB. Ao criar um blob de páginas, não inclua conteúdo no corpo da solicitação. Depois que o blob tiver sido criado, chame Colocar Página para adicionar conteúdo ao blob ou modificá-lo.

Para criar um novo blob de acréscimo, chame Put Blob para criá-lo com um comprimento de conteúdo de 0 bytes. Depois que o blob de acréscimo for criado, chame Append Block para adicionar conteúdo ao final dele.

Se você chamar Put Blob para substituir um blob existente com o mesmo nome, todos os instantâneos associados ao blob original serão mantidos. Para remover instantâneos associados, primeiro chame Excluir Blob e chame Put Blob para recriar o blob.

Um blob tem propriedades personalizadas (definidas por meio de cabeçalhos) que você pode usar para armazenar valores associados a cabeçalhos HTTP padrão. Posteriormente, você pode ler esses valores chamando Obter Propriedades do Blob ou modificá-los chamando Definir Propriedades de Blob. Os cabeçalhos de propriedade personalizada e o cabeçalho HTTP padrão correspondente são listados na seguinte tabela:

Cabeçalho HTTP Cabeçalho da propriedade personalizada do blob
Content-Type x-ms-blob-content-type
Content-Encoding x-ms-blob-content-encoding
Content-Language x-ms-blob-content-language
Content-MD5 x-ms-blob-content-md5
Cache-Control x-ms-blob-cache-control

A semântica para definir ou persistir esses valores de propriedade com o blob é a seguinte:

  • Se o cliente especificar um cabeçalho de propriedade personalizada, conforme indicado pelo prefixo x-ms-blob, esse valor será armazenado com o blob.

  • Se o cliente especificar um cabeçalho HTTP padrão, mas não o cabeçalho de propriedade personalizado, o valor será armazenado na propriedade personalizada correspondente associada ao blob e será retornado por uma chamada para Get Blob Properties. Por exemplo, se o cliente definir o cabeçalho Content-Type na solicitação, esse valor será armazenado na propriedade x-ms-blob-content-type do blob.

  • Se o cliente definir o cabeçalho HTTP padrão e o cabeçalho de propriedade correspondente na mesma solicitação, a solicitação PUT usará o valor fornecido para o cabeçalho HTTP padrão, mas o valor especificado para o cabeçalho de propriedade personalizada será mantido com o blob e retornado por solicitações GET subsequentes.

Se as marcas forem fornecidas no x-ms-tags cabeçalho, elas deverão ser codificadas em cadeia de caracteres de consulta. As chaves de marca e os valores devem estar em conformidade com os requisitos de nomenclatura e comprimento, conforme especificado em Set Blob Tags. Além disso, o x-ms-tags cabeçalho pode conter até 2kb de marcas. Se mais marcas forem necessárias, use a operação Definir Marcas de Blob .

Se o blob tiver uma concessão ativa, o cliente deverá especificar uma ID de concessão válida na solicitação para substituir o 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). Se o cliente especificar uma ID de concessão em um blob que ainda não existe, o Armazenamento de Blobs retornará o código de status 412 (Falha de Pré-condição) para solicitações feitas na versão 2013-08-15 e posterior. Para versões anteriores a 2013-08-15, o Armazenamento de Blobs retorna o código de status 201 (Criado).

Se um blob existente com uma concessão ativa for substituído por uma Put Blob operação, a concessão persistirá no blob atualizado até que ele expire ou seja liberado.

Uma Put Blob operação tem permissão de 10 minutos por MiB para ser concluída. Se a operação estiver demorando mais de 10 minutos por MiB em média, a operação atingirá o tempo limite.

A substituição de um archive blob falha e a substituição de um hot blob ou cool herda a camada do blob antigo se um x-ms-access-tier cabeçalho não for fornecido.

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