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.

A atualização de um blob de blocos existente substitui todos os metadados existentes no blob. Não há suporte para atualizações parciais com o Put Blob; o conteúdo do blob existente é substituído com o 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 .

Observe que você pode criar um blob de acréscimo somente na versão 2015-02-21 e posterior.

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

Solicitação

A solicitação Put Blob pode ser criada da seguinte maneira. HTTPS é recomendado. Substitua myaccount pelo nome da sua conta de armazenamento:

URI de solicitação do método PUT Versão de HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob HTTP/1.1

URI do serviço de armazenamento emulado

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

URI de solicitação do método PUT Versão de HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob HTTP/1.1

Observe que o emulador de armazenamento só dá suporte a tamanhos de blob de até 2 GiB.

Para obter mais informações, consulte Como usar o Armazenamento Emulator do Azure para desenvolvimento e teste.

Parâmetros de 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 Configurando tempos limite para operações de serviço de blob.

Cabeçalhos de solicitação (todos os tipos de blob)

A tabela a seguir descreve cabeçalhos de solicitação obrigatórios e opcionais para todos os tipos de blob.

Cabeçalho da solicitação Descrição
Authorization Obrigatórios. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, consulte Autorizar solicitações para o Azure Armazenamento.
Date ou x-ms-date Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para obter mais informações, consulte Autorizar solicitações para o Azure Armazenamento.
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ágina 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ágina existente, chame Put Page. Para gravar conteúdo em um blob de acréscimo, chame o Bloco de Acréscimo.
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 Get Blob é executada no recurso de blob. O cliente pode usar esse valor quando retornado para decodificar o conteúdo do blob.
Content-Language Opcional. Especifica os idiomas naturais usados 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 do conteúdo que chegou com o valor enviado. Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação Incorreta).

Quando omitido na versão 2012-02-12 e posteriores, o serviço Blob gera um hash MD5.

Os resultados de Obter Blob, Obter Propriedades de Blob e Blobs de Lista 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 do conteúdo que chegou com o valor 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 ou posteriores.

Se os cabeçalhos Content-MD5 e x-ms-content-crc64 estiverem presentes, a solicitação falhará com uma 400 (Solicitação Incorreta).
Cache-Control Opcional. O serviço Blob armazena esse valor, mas não o utiliza, nem 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ágina ou blob de acréscimo. O suporte para a criação de um blob de acréscimo está disponível somente na versão 2015-02-21 e posterior.
x-ms-meta-name:value Opcional. Pares de nome-valor associados ao blob como metadados.

Observe que, 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 ou posterior.
x-ms-tags Opcional. Define as marcas codificadas de cadeia de caracteres de consulta determinadas no blob. Consulte os Comentários para obter informações adicionais. Com suporte na versão 2019-12-12 e mais recente.
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 campo do cabeçalho de resposta Content-Disposition transmite informações adicionais sobre como processar a carga de resposta, e também pode ser usado para anexar metadados adicionais. Por exemplo, se for definido como attachment, ele indicará que o usuário agente não deve exibir a resposta, mas em vez disso, mostra uma caixa de diálogo Salvar como com um nome de arquivo diferente do nome de blob especificado.

A resposta das operações Obter Blob e Obter Propriedades de 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 cabeçalhos na resposta. Consulte o suporte cors para os serviços de Armazenamento para obter detalhes.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres de 1 KiB que é registrado nos logs de análise quando o log de análise de armazenamento está habilitado. O uso desse cabeçalho é altamente recomendável para correlacionar as atividades do lado do cliente com as solicitações recebidas pelo servidor. Para obter mais informações, consulte Sobre Análise de Armazenamento registro em log e log do Azure: usando logs para acompanhar solicitações de Armazenamento.
x-ms-access-tier Opcional. Indica a camada a ser definida no blob. Para blobs de página em uma conta de armazenamento premium somente com a versão 2017-04-17 e mais recente. Verifique Armazenamento Premium de alto desempenho e discos gerenciados para VMs para obter uma lista completa de camadas com suporte de blob de página. Para blobs de blocos, com suporte no armazenamento de blobs ou contas v2 de uso geral apenas com a versão 2018-11-09 e mais recente. Os valores válidos para camadas de blob de blocos são HotArchive/Cool/. Para obter informações detalhadas sobre camadas de blob de blocos, consulte camadas de armazenamento quente, esporádica e de arquivo.
x-ms-immutability-policy-until-date Versão 2020-06-12 e mais recente. Especifica a data de 'retenção até' a 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 mais recente. Especifica o modo de política de imutabilidade a ser definido no blob. Os valores válidos são unlocked/locked. unlocked indica que o usuário pode alterar a política aumentando ou diminuindo a data de retenção até a data. locked indica que essas ações são proibidas.
x-ms-legal-hold Versão 2020-06-12 e mais recente. Especifica a retenção legal a ser definida no blob, os valores válidos são true/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, confira Como especificar cabeçalhos condicionais para operações de serviço Blob.

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

A tabela a seguir descreve os cabeçalhos de solicitação aplicáveis apenas para operações em blobs de página.

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 do blob de página, até 8 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 serviço Blob 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 ficar entre 0 e 2^63 - 1. O valor padrão é 0.
x-ms-access-tier Versão 2017-04-17 e mais recente. Somente para blobs de página em uma conta de armazenamento premium. Especifica a camada a ser definida no blob. Verifique Armazenamento Premium de alto desempenho e discos gerenciados para VMs para obter uma lista completa de camadas com suporte.
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 é igual ao valor do x-ms-client-request-id cabeçalho se ele estiver presente na solicitação e o valor estiver no máximo 1024 caracteres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente na solicitação, esse cabeçalho 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ágina 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

Essa solicitação de exemplo cria um blob de páginas e especifica seu tamanho máximo como 1024 bytes. Observe que você deve chamar Put Page para adicionar conteúdo a um blob de página:

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  

Essa solicitação de exemplo cria um blob de acréscimo. Observe que você deve chamar o Bloco de Acréscimo para adicionar conteúdo ao blob 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 informações sobre códigos de status, consulte Status e Códigos 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 de protocolo HTTP/1.1.

Cabeçalho de resposta Descrição
ETag A ETag contém um valor que o cliente pode usar para executar operações PUT condicionais usando o cabeçalho de solicitação If-Match. Se a versão da solicitação for a 2011-08-18 ou mais recente, o valor de ETag será exibido entre aspas.
Last-Modified A data e a hora da última modificação feita no blob. O formato da data segue RFC 1123. Para obter mais informações, consulte Representação de valores Date-Time 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 Esse cabeçalho é retornado para um blob de blocos, para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor Content-MD5 retornado é computado pelo serviço Blob. Na versão 2012-02-12 e mais recentes, esse cabeçalho é retornado até mesmo quando a solicitação não inclui os cabeçalhos Content-MD5 ou x-ms-blob-content-md5.
x-ms-content-crc64 Esse cabeçalho é retornado para um blob de blocos, para que o cliente possa verificar a integridade do conteúdo da mensagem. O valor x-ms-content-crc64 retornado é computado pelo serviço Blob. Esse cabeçalho sempre será retornado a partir da versão 2019-02-02.
x-ms-request-id Esse cabeçalho identifica a solicitação que foi feita de forma exclusiva e pode ser usado para solucionar problemas na solicitação. Para obter mais informações, consulte Solução de problemas de operações de API.
x-ms-version Indica a versão do serviço Blob usado para executar a solicitação. Esse cabeçalho é retornado para solicitações feitas na versão 2009-09-19 e mais recente.
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. Este cabeçalho retorna o valor do cabeçalho de solicitação de origem no caso de 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 cabeçalho Origin e CORS estiver habilitado com uma regra de correspondência. que não permite todas as origens. Esse cabeçalho será definido como verdadeiro.
x-ms-request-server-encrypted: true/false Versão 2015-12-11 ou mais recente. O valor desse cabeçalho será definido para true se o conteúdo da solicitação for criptografado com êxito usando o algoritmo especificado e false , caso contrário.
x-ms-encryption-key-sha256 Versão 2019-02-02 ou mais recente. Esse cabeçalho será retornado se a solicitação usar 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 ou mais recente. Esse cabeçalho será retornado se a solicitação usar 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 mais recente. 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.

Exemplo de Resposta

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 poderá 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. Após a criação de um blob, o tipo de blob não pode ser alterado, a menos que seja excluído e recriado.

A tabela a seguir descreve os tamanhos máximos de bloco e de blob permitidos pela versão do serviço.

Versão do serviço Tamanho máximo do bloco (via Colocar Bloco) Tamanho máximo do blob (via Colocar Lista de Bloco) Tamanho máximo do blob via operação de gravação única (via Colocar Blob)
Versão 12/12/2019 e posterior 4000 MiB Aproximadamente 190,7 TiB (4000 MiB X 50.000 blocos) 5000 MiB (versão prévia)
Versão 31/05/2016 até a versão 07/07/2019 100 MiB Aproximadamente 4,75 TiB (100 MiB X 50.000 blocos) 256 MiB
Versões anteriores a 31/05/2016 4 MiB Aproximadamente 195 GiB (4 MiB X 50.000 blocos) (versão prévia) 64 MiB

Se você tentar carregar um blob de bloco 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 serviço Blob também retorna informações adicionais sobre o erro na resposta, inclusive o tamanho máximo permitido do blob em bytes.

Para criar um novo blob de página, primeiro inicialize o blob chamando Put Blob e especifique seu tamanho máximo, até 8 TiB. Ao criar um blob de páginas, não inclua o conteúdo no corpo da solicitação. Depois que o blob for 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 criar um blob com um comprimento de conteúdo de zero bytes. Depois que o blob de acréscimo for criado, chame Append Block para adicionar conteúdo ao final do blob.

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

Um blob tem as propriedades personalizadas (definidas pelos cabeçalhos) que você pode usar para armazenar os valores associados aos cabeçalhos HTTP padrão. Esses valores podem ser lidos posteriormente chamando Propriedades de Obter Blob ou modificados chamando Propriedades de Conjunto de Blobs. 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 esses valores de propriedade como persistentes 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 da propriedade personalizada, o valor será armazenado na propriedade personalizada correspondente associada ao blob, e retornado por uma chamada a 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 da 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 da 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 Definir Marcas de Blob. 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 inválida, o serviço Blob 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 serviço Blob também retornará o código de status 412 (Falha na Pré-condição). Se o cliente especificar um ID de concessão em um blob que ainda não existir, o serviço Blob retornará o código de status 412 (falha na pré-condição) para solicitações feitas na versão 2013-08-15 e posterior; para versões anteriores, o serviço Blob retornará o código de status 201 (criado).

Se um blob existente com uma concessão ativa for substituído por uma operação Put Blob, a concessão persistirá no blob atualizado, até ele expirar ou ser 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 terá tempo limite.

Substituir um blob arquivado falhará e substituir um hot/cool blob herdará a camada do blob antigo se o cabeçalho x-ms-access-tier não for fornecido.

Consulte Também

Autorizar solicitações ao Azure Armazenamento
Status e códigos de erro
Códigos de erro do serviço Blob
Configurando os tempos limite para operações de serviço do Blob