Set Blob Properties

Artigo
02/13/2024

A operação Set Blob Properties define as propriedades do sistema no blob.

Solicitação

A solicitação Set Blob Properties pode ser criada da 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=properties`	HTTP/1.1

URI 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 Armazenamento de Blobs 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=properties`	HTTP/1.1

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

Parâmetros do URI

Você pode especificar os seguintes parâmetros adicionais no URI da 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 de Armazenamento de Blobs.

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

A tabela a seguir descreve os 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 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.
`x-ms-blob-cache-control`	Opcional. Modifica a cadeia de caracteres de controle de cache para o blob. Se essa propriedade não for especificada na solicitação, a propriedade será desmarcada para o blob. As chamadas subsequentes para Obter Propriedades do Blob não retornam essa propriedade, a menos que ela seja definida explicitamente no blob novamente.
`x-ms-blob-content-type`	Opcional. Define o tipo de conteúdo do blob. Se essa propriedade não for especificada na solicitação, a propriedade será desmarcada para o blob. As chamadas subsequentes para Obter Propriedades do Blob não retornam essa propriedade, a menos que ela seja definida explicitamente no blob novamente.
`x-ms-blob-content-md5`	Opcional. Define o hash MD5 do blob. Se essa propriedade não for especificada na solicitação, a propriedade será desmarcada para o blob. As chamadas subsequentes para Obter Propriedades do Blob não retornam essa propriedade, a menos que ela seja definida explicitamente no blob novamente.
`x-ms-blob-content-encoding`	Opcional. Define a codificação do conteúdo do blob. Se essa propriedade não for especificada na solicitação, a propriedade será desmarcada para o blob. As chamadas subsequentes para Obter Propriedades do Blob não retornam essa propriedade, a menos que ela seja definida explicitamente no blob novamente.
`x-ms-blob-content-language`	Opcional. Define o idioma do conteúdo do blob. Se essa propriedade não for especificada na solicitação, a propriedade será desmarcada para o blob. As chamadas subsequentes para Obter Propriedades do Blob não retornam essa propriedade, a menos que ela seja definida explicitamente no blob novamente.
`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 Armazenamento de Blobs do Azure.
`x-ms-blob-content-disposition`	Opcional. Define o cabeçalho `Content-Disposition` do blob. Disponível para a versão 2013-08-15 e posterior. O `Content-Disposition` campo de cabeçalho de resposta transmite informações adicionais sobre como processar o conteúdo da resposta e pode ser usado para anexar metadados adicionais. Por exemplo, se estiver definido `attachment`como , isso indicará que o agente do usuário não deve exibir a resposta, mas, em vez disso, mostrará 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 cabeçalhos na resposta. Para obter mais informações, confira Suporte a CORS (compartilhamento de recursos entre origens) para os serviços de Armazenamento do Azure.

Essa operação também dará suporte ao uso de cabeçalhos condicionais para definir as propriedades do 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)

A tabela a seguir descreve cabeçalhos de solicitação que se aplicam somente a operações em blobs de páginas:

Cabeçalho da solicitação	Descrição
`x-ms-blob-content-length: byte value`	Opcional. Redimensiona um blob da página ao tamanho especificado. Se o valor especificado for menor que o tamanho atual do blob, todos os blobs de páginas com valores maiores que o valor especificado serão limpos. Essa propriedade não pode ser usada para alterar o tamanho de um blob de blocos ou um blob de acréscimo. Definir essa propriedade para um blob de blocos ou um blob de acréscimo retorna status código 400 (Solicitação Incorreta).
`x-ms-sequence-number-action: {max, update, increment}`	Opcional, mas necessário se o cabeçalho `x-ms-blob-sequence-number` for definido para a solicitação. Essa propriedade só se aplica a blobs de páginas. Essa propriedade indica como o serviço deve modificar o número de sequência do blob. Especifique uma das seguintes opções dessa propriedade: - `max`: define o número de sequência como o maior do valor incluído na solicitação e o valor armazenado atualmente para o blob. - `update`: define o número de sequência como o valor incluído na solicitação. - `increment`: incrementa o valor do número de sequência em 1. Se você estiver especificando essa opção, não inclua o `x-ms-blob-sequence-number header`. Isso retorna status código 400 (Solicitação Incorreta).
`x-ms-blob-sequence-number: <num>`	Opcional, mas obrigatório se a propriedade `x-ms-sequence-number-action` for definida como `max` ou `update`. Essa propriedade só se aplica a blobs de páginas. A propriedade define o número de sequência do blob. O número de sequência é uma propriedade controlada pelo usuário que você pode usar para monitorar solicitações e gerenciar problemas de simultaneidade. Para obter mais informações, consulte a operação Put Page . Use essa propriedade junto com `x-ms-sequence-number-action` para atualizar o número de sequência do blob para o valor especificado ou o mais alto dos valores especificados com a solicitação ou armazenados atualmente com o blob. Esse cabeçalho não deve ser especificado se `x-ms-sequence-number-action` estiver definido `increment`como , nesse caso, o serviço incrementa automaticamente o número da sequência em um. Para definir o número de sequência como um valor da sua escolha, essa propriedade deve ser especificada na solicitação juntamente com `x-ms-sequence-number-action`.

Corpo da solicitação

Nenhum.

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 200 (OK).

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 padrão HTTP adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Sintaxe	Descrição
`ETag`	Contém um valor que você pode usar para executar operações condicionalmente. Consulte Especificar cabeçalhos condicionais para operações de Armazenamento de Blobs para obter mais informações. Se a versão da solicitação for 2011-08-18 ou posterior, o valor ETag será colocado 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 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.
`x-ms-blob-sequence-number`	Se o blob for de páginas, o seu número de sequência atual será retornado com esse cabeçalho.
`x-ms-request-id`	Identifica exclusivamente a solicitação que foi feita e pode ser usada 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 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. Se houver uma correspondência, esse cabeçalho retornará o valor do cabeçalho de solicitação de origem.
`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. O cabeçalho será definido como `true`.
`x-ms-client-request-id`	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.

Corpo da resposta

Nenhum.

Autorização

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

Importante

A Microsoft recomenda usar Microsoft Entra ID com identidades gerenciadas para autorizar solicitações ao Armazenamento do Azure. Microsoft Entra ID 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 de Microsoft Entra ID para autorizar solicitações para dados de blob. Com Microsoft Entra ID, 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 por 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 Microsoft Entra ID, consulte Autorizar o acesso a blobs usando Microsoft Entra ID.

Permissões

Veja abaixo a ação RBAC necessária para um usuário Microsoft Entra, grupo, identidade gerenciada ou entidade de serviço para chamar a Set Blob Properties operação e a função RBAC interna do Azure com menos privilégios 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 do 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 Set Blob Properties 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 Microsoft Entra credenciais 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 Microsoft Entra credenciais 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 para o Armazenamento de Blobs. Para saber mais, confira 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 de usuário é protegida com Microsoft Entra credenciais e também pelas permissões especificadas para a SAS.

Chamar a Set Blob Properties operação usando um token SAS delegado a um recurso de contêiner ou 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 Create 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 Set Blob Properties operação usando um token SAS delegado a um recurso de contêiner ou 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 Create 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 o acesso:

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

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

A Set Blob Properties operação dá suporte à 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.

Comentários

A semântica para atualizar as propriedades de um blob é a seguinte:

O número de sequência de um blob de páginas será atualizado somente se a solicitação estiver de acordo com uma das seguintes condições:
- A solicitação define o x-ms-sequence-number-action como max ou updatee especifica um valor para o x-ms-blob-sequence-number cabeçalho.
- A solicitação define o x-ms-sequence-number-action como increment, que indica que o serviço deve incrementar o número da sequência em um.
O tamanho de um blob de páginas será modificado apenas se a solicitação especificar um valor para o cabeçalho x-ms-content-length.
Para alterar o tamanho de um blob de páginas em uma conta de armazenamento premium, o novo tamanho não deve exceder o tamanho do conteúdo permitido pela camada existente. Chame Definir Camada de Blob antes de redimensionar o blob. Para obter uma lista de camadas e comprimento de conteúdo permitido, consulte Armazenamento premium de alto desempenho e discos gerenciados para VMs.
Se uma solicitação definir apenas x-ms-blob-sequence-number ou x-ms-content-length, nenhuma das outras propriedades do blob será modificada.
Se uma ou mais das propriedades a seguir estiverem definidas na solicitação, todas as propriedades serão definidas juntas. Se um valor não for fornecido para uma propriedade quando pelo menos um deles estiver definido, essa propriedade será desmarcada para o blob.
- x-ms-blob-cache-control
- x-ms-blob-content-type
- x-ms-blob-content-md5
- x-ms-blob-content-encoding
- x-ms-blob-content-language
- x-ms-blob-content-disposition

Observação

Para uma SAS (assinatura de acesso compartilhado), você pode substituir determinadas propriedades armazenadas para o blob especificando parâmetros de consulta como parte da assinatura de acesso compartilhado. Essas propriedades incluem as propriedades cache-control, content-type, content-encoding, content-language e content-disposition. Para obter mais informações, consulte Create uma SAS de serviço.

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

Operação	Tipo de conta de armazenamento	Categoria de cobrança
Set Blob Properties	Blob de blocos Premium Uso geral v2 Standard	Outras operações
Set Blob Properties	Uso geral v1 Standard	Operações de gravação

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

Compartilhar via