Lease Blob

  • Artigo

A Lease Blob operação cria e gerencia um bloqueio em um blob para operações de gravação e exclusão. A duração do bloqueio pode ser de 15 a 60 segundos, ou pode ser infinita. Em versões anteriores a 2012-02-12, a duração do bloqueio é de 60 segundos.

Importante

A partir da versão 2012-02-12, alguns comportamentos da operação Lease Blob diferem de versões anteriores. Por exemplo, em versões anteriores, você poderia renovar uma concessão depois de liberá-la. A partir da versão 2012-02-12, essa solicitação de concessão falha, mas as chamadas que usam versões mais antigas de Lease Blob ainda são bem-sucedidas. Para obter uma lista de alterações no comportamento desta operação, consulte a seção "Comentários" mais adiante neste artigo.

Você pode chamar a Lease Blob operação em um dos seguintes modos:

  • Acquire, para solicitar uma nova concessão.

  • Renew, para um renovar uma concessão existente.

  • Change, para alterar a ID de uma concessão existente.

  • Release, para liberar a concessão se ela não for mais necessária, para que outro cliente possa adquirir imediatamente uma concessão no blob.

  • Break, para encerrar a concessão, mas verifique se outro cliente não pode adquirir uma nova concessão até que o período de concessão atual expire.

Solicitação

Você pode construir a solicitação da Lease Blob seguinte maneira. HTTPS é recomendado. Substitua myaccount pelo nome da sua conta de armazenamento.

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

URI do serviço de armazenamento emulado

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

URI de solicitação de método PUT Versão HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=lease HTTP/1.0

HTTP/1.1

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

Parâmetros do URI

Você pode especificar o parâmetro adicional a seguir 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 Armazenamento de Blobs.

Cabeçalhos da solicitação

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

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 Opcional. 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-lease-id: <ID> Necessário para renovar, alterar ou liberar a concessão.

Você pode especificar o valor de em qualquer formato de cadeia de x-ms-lease-id caracteres GUID válido. Consulte Construtor guid (cadeia de caracteres) para obter uma lista de formatos válidos.
x-ms-lease-action: <acquire ¦ renew ¦ change ¦ release ¦ break> acquire: solicita uma nova concessão. Se o blob não tiver uma concessão ativa, o Armazenamento de Blobs criará uma concessão no blob e retornará uma nova ID de concessão. Se o blob tiver uma concessão ativa, você só poderá solicitar uma nova concessão usando a ID de concessão ativa. No entanto, você pode especificar um novo x-ms-lease-duration, incluindo um negativo (-1) para uma concessão que nunca expira.

renew: renova a concessão. Você poderá renovar a concessão se a ID de concessão especificada na solicitação corresponder à associada ao blob. Observe que a concessão pode ser renovada mesmo que tenha expirado, desde que o blob não tenha sido modificado ou concedido novamente desde a expiração dessa concessão. Quando você renova uma concessão, o relógio de duração é redefinido.

change: versão 2012-02-12 e posterior. Altera a ID de uma concessão ativa. Um change deve incluir a ID de concessão atual no x-ms-lease-ide uma nova ID de concessão no x-ms-proposed-lease-id.

release: libera a concessão. Você poderá liberar a concessão se a ID de concessão especificada na solicitação corresponder à associada ao blob. A liberação da concessão permite que outro cliente adquira imediatamente a concessão do blob assim que a versão for concluída.

break: interromperá a concessão se o blob tiver uma concessão ativa. Depois que uma concessão é quebrada, ela não pode ser renovada. Qualquer solicitação autorizada pode interromper a concessão; a solicitação não precisa especificar uma ID de concessão correspondente. Quando uma concessão é interrompida, o período de interrupção de concessão é permitido decorrido, durante o qual o tempo break e release são as únicas operações de concessão que você pode executar no blob. Quando uma concessão é interrompida com êxito, a resposta indica o intervalo em segundos até que uma nova concessão possa ser adquirida.

Uma concessão que foi interrompida também pode ser liberada, caso em que outro cliente pode adquirir imediatamente a concessão no blob.
x-ms-lease-break-period: N Opcional. Versão 2012-02-12 e posterior. Para uma operação break, entre 0 e 60 segundos é a duração proposta que a concessão deve continuar antes de ser interrompida. Esse período de interrupção só será usado se for menor do que o tempo restante na concessão. Se for mais longo, o tempo restante da concessão será usado. Uma nova concessão não estará disponível antes do período de interrupção expirar, mas a concessão pode ser mantida por mais tempo do que o período de interrupção. Se esse cabeçalho não aparecer com uma break operação, uma concessão de duração fixa será interrompida após o período de concessão restante decorrido e uma concessão infinita será interrompida imediatamente.
x-ms-lease-duration: -1 ¦ n seconds Versão 2012-02-12 e posterior. Somente permitido e necessário em uma acquire operação. Especifica a duração de concessão, em segundos, ou um negativo (- 1) para uma concessão que nunca expira. A duração de uma concessão não infinita pode ser entre 15 e 60 segundos. Uma duração de concessão não pode ser alterada usando renew ou change.
x-ms-proposed-lease-id: <ID> Versão 2012-02-12 e posterior. Opcional para acquiree necessário para change. ID proposta da concessão, em um formato de cadeia de caracteres GUID. O Armazenamento de Blobs retornará 400 (Invalid request) se a ID de concessão proposta não estiver no formato correto. Consulte Construtor guid (cadeia de caracteres) para obter uma lista de formatos válidos.
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. Confira Suporte do 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 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 também dá suporte ao uso de cabeçalhos condicionais para executar a operação, somente se uma condição especificada for atendida. Para obter mais informações, consulte Especificando cabeçalhos condicionais para operações de Armazenamento de Blobs.

Corpo da solicitação

Nenhum.

Solicitação de exemplo

A solicitação de exemplo a seguir mostra como adquirir uma concessão:

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=lease HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-lease-action: acquire  
x-ms-lease-duration: -1  
x-ms-proposed-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-date: <date>  
Authorization: SharedKey testaccount1:esSKMOYdK4o+nGTuTyeOLBI+xqnqi6aBmiW4XI699+o=

Resposta

A resposta inclui um código de status HTTP e um conjunto de cabeçalhos de resposta.

Código de status

Os códigos de status de êxito retornados para operações de concessão são os seguintes:

  • Acquire: uma operação bem-sucedida retorna o código de status 201 (Criado).

  • Renew: uma operação bem-sucedida retorna o código de status 200 (OK).

  • Change: uma operação bem-sucedida retorna o código de status 200 (OK).

  • Release: uma operação bem-sucedida retorna o código de status 200 (OK).

  • Break: uma operação bem-sucedida retorna o código de status 202 (Aceito).

Para obter 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.

Sintaxe Descrição
ETag Contém um valor que você pode usar para executar operações condicionalmente. Consulte Especificando cabeçalhos condicionais para operações de Armazenamento de Blobs para obter mais informações.

Esse cabeçalho é retornado para solicitações feitas na versão 2013-08-15 e posterior e o valor está entre aspas ETag .

A Lease Blob operação não modifica essa propriedade.
Last-Modified A data e a hora da última modificação feita no blob. Para obter mais informações, consulte Representação de valores de data e 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. A Lease Blob operação não modifica essa propriedade.
x-ms-lease-id: <id> Quando você solicita uma concessão, o Armazenamento de Blobs retorna uma ID de concessão exclusiva. Quando a concessão estiver ativa, você deverá incluir a ID com qualquer solicitação de gravação no blob ou renovar, alterar ou liberar a concessão.

Uma operação de renovação bem-sucedida também retorna a ID da concessão ativa.
x-ms-lease-time: seconds Tempo aproximado restante do período de concessão, em segundos. Esse cabeçalho é retornado somente para uma solicitação bem-sucedida de interrupção da concessão. Se a interrupção for imediata, 0 será retornado.
x-ms-request-id Esse cabeçalho identifica exclusivamente a solicitação que foi feita e pode ser usado para solucionar problemas da 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 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.
Date Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera esse valor.
Access-Control-Allow-Origin Retornado se a solicitação incluir um Origin cabeçalho e o CORS estiver habilitado com uma regra correspondente. 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 Origin cabeçalho e o CORS estiver habilitado com uma regra correspondente. 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-client-request-id Você pode usar esse cabeçalho 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. O valor é no máximo 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.

Resposta de exemplo

Veja a seguir uma resposta de exemplo de uma solicitação para adquirir uma concessão:

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2015-02-21  
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
Date: <date>

Autorização

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

Importante

A Microsoft recomenda usar Microsoft Entra ID com identidades gerenciadas para autorizar solicitações para o 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, 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 um usuário Microsoft Entra, grupo, identidade gerenciada ou entidade de serviço para chamar a Lease Blob operação e a função rbac interna do Azure com privilégios mínimos que inclui 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

Uma concessão em um blob fornece acesso de gravação e exclusão exclusivo ao blob. Para gravar em um blob com uma concessão ativa, um cliente deverá incluir a ID da concessão ativa com a solicitação de gravação. A concessão é concedida pela duração especificada quando a concessão é adquirida. Essa duração pode ser entre 15 e 60 segundos ou uma duração infinita.

Quando um cliente adquire uma concessão, uma ID de concessão é retornada. O Armazenamento de Blobs gerará uma ID de concessão se uma não for especificada na solicitação de aquisição. O cliente pode usar essa ID de concessão para renovar a concessão, alterar sua ID de concessão ou liberar a concessão.

Quando uma concessão está ativa, sua ID deve ser incluída na solicitação de qualquer uma das seguintes operações:

Se a ID de concessão não estiver incluída, essas operações falharão em um blob concedido, com 412 – Precondition failed.

As seguintes operações são bem-sucedidas em um blob concedido, sem incluir a ID de concessão:

Não é necessário incluir a ID de concessão para GET operações em um blob que tenha uma concessão ativa. No entanto, todas as GET operações dão suporte a um parâmetro de concessão condicional, em que a operação só prossegue se a ID de concessão incluída na solicitação for válida.

Todas as operações de contêiner são permitidas em um contêiner que inclui blobs com uma concessão ativa, inclusive Excluir contêiner. Portanto, um contêiner pode ser excluído mesmo que os blobs dentro dele tenham concessões ativas. Use a operação Contêiner sob concessão para controlar direitos de excluir um contêiner.

Estados de concessão

O diagrama a seguir mostra os cinco estados de uma concessão, bem como os comandos ou os eventos que causam alterações no estado da concessão.

Diagrama que mostra os estados de concessão de blob e os gatilhos de alteração de estado.

Uma concessão pode estar em um desses estados, com base em se a concessão está bloqueada ou desbloqueada, e se a concessão é renovável nesse estado. As ações de concessão mostradas no diagrama anterior causam transições de estado.

Status de renovação Concessão bloqueada Concessão desbloqueada
Concessão renovável Concedida Expirado
Concessão não renovável Quebra Interrompida, disponível

  • Available: a concessão é desbloqueada e pode ser adquirida. Ação permitida: acquire.

  • Leased: a concessão está bloqueada. Ações permitidas: acquire (somente na mesma ID de concessão), renew, change, release e break.

  • Expired: a duração da concessão expirou. Ações permitidas: acquire, renew, release e break.

  • Breaking: a concessão foi interrompida, mas a concessão continuará bloqueada até que o período de interrupção tenha expirado. Ações permitidas: release e break.

  • Broken: a concessão foi interrompida e o período de interrupção expirou. Ações permitidas: acquire, release e break.

Depois que uma concessão tiver expirado, a ID de concessão será mantida pelo Armazenamento de Blobs até que o blob seja modificado ou concedido novamente. Um cliente pode tentar renovar ou liberar a concessão usando sua ID de concessão expirada. Se a operação for bem-sucedida, isso significa que o blob não foi alterado desde que a ID de concessão foi válida pela última vez.

Se o cliente tentar renovar ou liberar uma concessão com sua ID de concessão anterior e a solicitação falhar, o blob será modificado ou concedido novamente desde que a concessão do cliente foi ativa pela última vez. O cliente deverá adquirir uma nova concessão do blob.

Se uma concessão expirar em vez de ser liberada explicitamente, talvez um cliente precise aguardar até um minuto antes que uma nova concessão possa ser adquirida para o blob. No entanto, o cliente poderá renovar a concessão com sua ID de concessão imediatamente, se o blob não tiver sido modificado.

Observe que uma concessão não pode ser concedida para um blob instantâneo, pois os instantâneos são somente leitura. A solicitação de uma concessão em um instantâneo resulta no código de status 400 (Solicitação Incorreta).

A propriedade do Last-Modified-Time blob não é atualizada por chamadas para Lease Blob.

As tabelas a seguir mostram resultados de ações em blobs com concessões em vários estados. Letras (A), (B) e (C) representam IDs de concessão e (X) representa uma ID de concessão gerada pelo Armazenamento de Blobs.

Resultados de tentativas de uso em blobs por estado da concessão

Ação Disponível Concedida (A) Em interrupção (A) Interrompida (A) Expirada (A)
Gravar com (A) Falha (412) Concedida (A), gravação bem-sucedida Em interrupção (A), gravação bem-sucedida Falha (412) Falha (412)
Gravar com (B) Falha (412) Falha (409) Falha (412) Falha (412) Falha (412)
Gravação, nenhuma concessão especificada Disponível, gravação bem-sucedida Falha (412) Falha (412) Disponível, gravação bem-sucedida Disponível, gravação bem-sucedida
Ler com (A) Falha (412) Concedida (A), leitura bem-sucedida Em interrupção (A), leitura bem-sucedida Falha (412) Falha (412)
Ler com (B) Falha (412) Falha (409) Falha (409) Falha (412) Falha (412)
Leitura, nenhuma concessão especificada Disponível, leitura bem-sucedida Concedida (A), leitura bem-sucedida Em interrupção (A), leitura bem-sucedida Interrompida (A), leitura bem-sucedida Expirada (A), leitura bem-sucedida

Resultados de operações de concessão em blobs por estado da concessão

Ação Disponível Concedida (A) Em interrupção (A) Interrompida (A) Expirada (A)
Acquire, nenhuma ID de concessão proposta Concedida (X) Falha (409) Falha (409) Concedida (X) Concedida (X)
Acquire (A) Concedida (A) Concedida (A), nova duração Falha (409) Concedida (A) Concedida (A)
Acquire (B) Concedida (B) Falha (409) Falha (409) Concedida (B) Concedida (B)
Break, período=0 Falha (409) Interrompida (A) Interrompida (A) Interrompida (A) Interrompida (A)
Break, período>0 Falha (409) Em interrupção (A) Em interrupção (A) Interrompida (A) Interrompida (A)
Change, (A) a (B) Falha (409) Concedida (B) Falha (409) Falha (409) Falha (409)
Change, (B) a (A) Falha (409) Concedida (A) Falha (409) Falha (409) Falha (409)
Change, (B) a (C) Falha (409) Falha (409) Falha (409) Falha (409) Falha (409)
Renew (A) Falha (409) Concedida (A), relógio de validade redefinido Falha (409) Falha (409) Concessão(A), se o blob não tiver sido modificado.

Falha (409) se o blob não tiver sido modificado.
Renew (B) Falha (409) Falha (409) Falha (409) Falha (409) Falha (409)
Release (A) Falha (409) Disponível Disponível Disponível Disponível
Release (B) Falha (409) Falha (409) Falha (409) Falha (409) Falha (409)
A duração expira Disponível Expirada (A) Interrompida (A) Interrompida (A) Expirada (A)

Alterações no Blob de Concessão introduzido na versão 2012-02-12

A lista a seguir especifica alterações no Lease Blob comportamento introduzido na versão 2012-02-12.

  • Uma chamada para Lease Blob para adquirir uma concessão agora deve incluir um cabeçalho de duração de concessão. Se você tentar adquirir uma concessão sem especificar uma duração de concessão, o serviço retornará 400 Bad Request – Missing required header.

  • Não é mais possível renovar uma concessão depois de liberá-la. Se você tentar fazer isso, o serviço retornará 409 Conflict – The lease ID specified did not match the lease ID for the blob. Os aplicativos que chamaram a versão e, em seguida, chamaram renovar, agora devem salvar o ETag da chamada de versão. Em seguida, os aplicativos devem chamar acquire, com um If-Match cabeçalho condicional, para adquirir a concessão somente quando o blob não for alterado.

  • Não é mais possível interromper uma concessão depois de liberá-la. Se você tentar fazer isso, o serviço retornará 409 Conflict – There is currently no lease on the blob.

  • É possível interromper uma concessão em interrupção ou interrompida, tornando as operações de interrupção idempotentes. Em versões anteriores, esse procedimento resultava em erro, com a exibição do código 409 Conflict – The lease has already been broken and cannot be broken again. Essa alteração permite que você reduza a duração de uma interrupção. Se você interromper uma concessão que está no estado de interrupção e incluir uma duração mais curta do que o período de interrupção restante, sua duração mais curta será usada.

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

Operação Tipo de conta de armazenamento Categoria de cobrança
Blob de Concessão (adquirir, liberar, renovar) Blob de blocos Premium
Uso geral v2 Standard		 Outras operações
Blob de Concessão (adquirir, liberar, renovar) Uso geral v1 Standard Operações de leitura
Blob de Concessão (quebra, alteração) Blob de blocos Premium
Uso geral v2 Standard		 Outras operações
Blob de Concessão (quebra, alteração) Uso geral v1 Standard Operações de gravação

Confira também

new-blob-lease-features-infinite-leases-smaller-lease-times-and-more.aspx)
Autorizar solicitações para o Armazenamento do Azure
Status e códigos de erro
Códigos de erro do Armazenamento de Blobs
Lease Container