Definir marcas de blob

  • Artigo

A Set Blob Tags operação define marcas definidas pelo usuário para o blob especificado como um ou mais pares chave-valor.

Solicitação

A solicitação Set Blob Tags 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=tags

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=tags&versionid=<DateTime>		 HTTP/1.1

Parâmetros do URI

Você pode especificar os seguintes parâmetros adicionais no URI da solicitação:

Parâmetro Descrição
versionid Opcional para a versão 2019-12-12 e posterior. O versionid parâmetro é um valor opaco DateTime que, quando presente, especifica a versão do blob a ser recuperada.
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 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. 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 do conteúdo da solicitação em bytes. Esse cabeçalho refere-se ao comprimento do conteúdo do documento de marcas, não ao blob em si.
Content-Type Obrigatórios. O valor desse cabeçalho deve ser application/xml; charset=UTF-8.
Content-MD5 Opcional. Um hash MD5 do conteúdo da solicitação. O hash é usado para verificar a integridade do conteúdo da solicitação durante o transporte. Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação inválida).

Esse cabeçalho está associado ao conteúdo da solicitação e não ao conteúdo do próprio blob.
x-ms-content-crc64 Opcional. Um hash CRC64 do conteúdo da solicitação. O hash é usado para verificar a integridade do conteúdo da solicitação durante o transporte. Se os dois hashes não corresponderem, a operação falhará com o código de erro 400 (Solicitação inválida).

Esse cabeçalho está associado ao conteúdo da solicitação e não ao conteúdo do próprio blob.

Se os Content-MD5 cabeçalhos e x-ms-content-crc64 estiverem presentes, a solicitação falhará com o código de erro 400 (Solicitação Incorreta).
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. Se uma ID de concessão válida não for especificada na solicitação, a operação falhará com status código 403 (Proibido).
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.

Essa operação dá suporte ao x-ms-if-tags cabeçalho condicional para definir marcas de blob somente se uma condição especificada for atendida. Para obter mais informações, consulte Especificar cabeçalhos condicionais para operações de Armazenamento de Blobs.

Corpo da solicitação

Formato do corpo da solicitação:

<?xml version="1.0" encoding="utf-8"?>  
<Tags>  
    <TagSet>  
        <Tag>  
            <Key>tag-name-1</Key>  
            <Value>tag-value-1</Value>  
        </Tag>  
        <Tag>  
            <Key>tag-name-2</Key>  
            <Value>tag-value-2</Value>  
        </Tag>  
    </TagSet>  
</Tags>

O corpo da solicitação deve ser um documento XML UTF-8 bem formado e conter um conjunto de marcas que represente as marcas do blob.

O conjunto de marcas pode conter no máximo 10 marcas. As chaves e os valores de marca diferenciam maiúsculas de minúsculas. As teclas de marca devem ter de 1 a 128 caracteres e os valores de marca devem ser de 0 a 256 caracteres. Os caracteres válidos de chave de marca e valor incluem:

  • Letras minúsculas e maiúsculas (a-z, A-Z)
  • Dígitos (0-9)
  • Um espaço ( )
  • Mais (+), menos (-), ponto (.), barra (/), dois-pontos (:), igual a (=) e sublinhado (_)

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 204 (Sem conteúdo).

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.

Cabeçalho de resposta Descrição
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 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-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 Tags operação conforme descrito abaixo.

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, um grupo, uma entidade de serviço de aplicativo ou uma 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 que um usuário, grupo ou entidade de serviço Microsoft Entra chame a Set Blob Tags operação 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, confira Atribuir uma função do Azure para acesso aos dados de blob.

Comentários

A Set Blob Tags operação tem suporte na API REST versão 2019-12-12 e posterior.

Para contas com namespace hierárquico habilitado, não há suporte para a Set Blob Tags operação, pois não há suporte para marcas de blob para contas de namespace hierárquicas.

A Set Blob Tags operação substitui todas as marcas existentes no blob. Para remover todas as marcas de um blob, envie uma Set Blob Tags solicitação com um vazio <TagSet>.

Essa operação não atualiza a ETag nem a hora da última modificação do blob. É possível definir marcas em um blob arquivado.

O serviço de armazenamento mantém forte consistência entre um blob e suas marcas. As alterações nas marcas de blob são imediatamente visíveis para operações subsequentes Get Blob Tags no blob. O índice secundário, no entanto, é eventualmente consistente. As alterações nas marcas de um blob podem não estar imediatamente visíveis para Find Blobs by Tags as operações.

Se uma solicitação fornecer marcas inválidas, o Armazenamento de Blobs retornará status código 400 (Solicitação Incorreta).

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

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

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

Confira também

Gerenciar e localizar dados do Armazenamento de Blobs com marcas de índice de blob
Autorizar solicitações para o Armazenamento do Azure
Status e códigos de erro
Códigos de erro do Armazenamento de Blobs