Definir a retenção legal do blob

  • Artigo

A Set Blob Legal Hold operação define a retenção legal em um blob. Essa operação não atualiza a ETag do blob. Essa API está disponível a partir da versão 2020-04-08.

Solicitação

A solicitação Set Blob Legal Hold pode ser criada da seguinte maneira. Recomendamos que você use HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento e myblob pelo nome do blob para o qual a retenção legal deve ser alterada.

Método URI da solicitação Versão HTTP
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=legalhold HTTP/1.1

Parâmetros do URI

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

Parâmetro Descrição
snapshot Opcional. O parâmetro instantâneo é um valor opaco DateTime que, quando presente, especifica o blob instantâneo para definir uma camada. Para obter mais informações sobre como trabalhar com instantâneos de blob, consulte Criar um instantâneo de um blob
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 na qual definir uma camada.
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 de armazenamento 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-legal-hold Opcional. Define ou remove a retenção legal no blob. Para contas do Armazenamento de Blobs ou de uso geral v2, os valores válidos são true e false.
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-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.

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 informações sobre códigos de status, consulte Códigos de status e de erro.

Cabeçalhos de resposta

A resposta para essa operação inclui os cabeçalhos abaixo. 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 usada para executar a solicitação. Esse cabeçalho é retornado para solicitações feitas na versão 2009-09-19 e mais recente.
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.
x-ms-legal-hold Indica a retenção legal definida no blob. Os valores válidos são true e false.

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 Legal Hold 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, 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 que um usuário, grupo ou entidade de serviço Microsoft Entra chame a Set Blob Legal Hold 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

Definir a retenção legal do blob em uma conta de armazenamento de blobs ou de uso geral v2 tem as seguintes restrições:

  • A definição de uma retenção legal em um instantâneo ou uma versão é permitida a partir da versão REST 2020-06-12.
  • Quando a retenção legal é definida truecomo , os usuários não podem modificar ou excluir o blob, exceto em algumas operações especiais, PutBlockList/PutBlob/CopyBlob, porque essas operações geram uma nova versão.

Observação

Para obter informações detalhadas sobre o armazenamento imutável, consulte Armazenamento imutável.

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

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

Para saber mais sobre os preços da categoria de cobrança especificada, confira Preços 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 Armazenamento de Blobs
Definir tempos limite para operações de Armazenamento de Blobs