Lease Container

  • Artigo

A operação Lease Container estabelece e gerencia um bloqueio em um contêiner para operações de exclusão. A duração do bloqueio pode ser de 15 a 60 segundos, ou pode ser infinita.

Você pode chamar a Lease Container 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 em relação ao contêiner.

  • 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.

Observação

A operação Lease Container está disponível na versão 2012-02-12 e posterior.

Solicitação

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

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

Para especificar o contêiner raiz, insira $root como o nome do contêiner.

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.

Método URI da solicitação Versão HTTP
PUT http://127.0.0.1:10000/mycontainer?comp=lease&restype=container 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 contêiner não tiver uma concessão ativa, o Armazenamento de Blobs criará uma concessão no contêiner e retornará uma nova ID de concessão. Se o contêiner 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 contêiner. Observe que a concessão pode ser renovada mesmo que tenha expirado, desde que o contêiner não tenha sido alugado novamente desde a expiração dessa concessão. Quando você renova uma concessão, o relógio de duração é redefinido.

change: 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 contêiner. A liberação da concessão permite que outro cliente adquira imediatamente a concessão para o contêiner, assim que a versão for concluída.

break: interromperá a concessão se o contêiner 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 é necessária para especificar uma ID de concessão correspondente. Quando uma concessão é quebrada, o período de interrupção de concessão é permitido decorrido. Você só pode executar break e release conceder operações no contêiner durante esse tempo. Quando uma concessão é interrompida com êxito, a resposta indica o intervalo em segundos até que uma nova concessão possa ser adquirida.

A concessão que foi interrompida também pode ser liberada. Um cliente pode adquirir imediatamente uma concessão de contêiner que tenha sido liberada.
x-ms-lease-break-period: N Opcional. Para uma break operação, esse cabeçalho é a duração proposta que a concessão deve continuar antes de ser quebrada, entre 0 e 60 segundos. 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 Necessário para acquire. 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> 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?restype=container&comp=lease HTTP/1.1  
  
Request Headers:  
x-ms-version: 2012-02-12  
x-ms-lease-action: acquire  
x-ms-lease-duration: -1  
x-ms-proposed-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-date: Thu, 26 Jan 2012 23:30:18 GMT  
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 O ETag para o contêiner. Esse cabeçalho é retornado para solicitações feitas na versão 2013-08-15 e posterior, e o valor está entre aspas ETag . Lease Container as operações feitas na versão 2013-08-15 e posteriores não modificam essa propriedade, mas as versões anteriores o fazem.
Last-Modified Retornado para solicitações feitas na versão 2013-08-15 e posterior. Retorna a data e a hora em que o contêiner foi modificado pela última vez. Para obter mais informações, consulte Representação de valores de data e hora em cabeçalhos.

Qualquer operação que modifique o contêiner, ou suas propriedades ou metadados, atualiza a hora da última modificação. Isso inclui a definição das permissões do contêiner. As operações em blobs não afetam a hora da última modificação do contêiner. Lease Container as operações feitas na versão 2013-08-15 e posteriores não modificam essa propriedade, mas as versões anteriores o fazem.
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 exclusão no contêiner 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.
Data 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 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 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 permite todas as origens. Esse cabeçalho será 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 é 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: 2012-02-12  
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
Date: Thu, 26 Jan 2012 23:30:18 GMT

Autorização

A autorização é necessária quando você está chamando qualquer operação de acesso a dados no Armazenamento do Azure. Você pode autorizar a Lease Container operação conforme descrito nas seções a seguir.

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 Armazenamento de Blobs.

Para saber mais sobre a autorização usando Microsoft Entra ID, consulte Autorizar o acesso a blobs usando Microsoft Entra ID.

Permissões

As seguintes ações rbac são necessárias para que um usuário, grupo ou entidade de serviço Microsoft Entra chame a Lease Container 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

Uma concessão em um contêiner fornece acesso de gravação e exclusão exclusivo ao contêiner. Uma concessão de contêiner controla apenas a capacidade de excluir o contêiner usando a operação Excluir Contêiner . Para excluir um contêiner com uma concessão ativa, o cliente deve incluir a ID da concessão ativa com a solicitação de exclusão. Se a ID de concessão não estiver incluída, a operação falhará com 412 (falha na pré-condição). Todas as outras operações de contêiner têm êxito em um contêiner alugado, sem incluir a ID de concessão. A concessão é concedida pela duração especificada quando a concessão é adquirida, que 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 gera 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. O diagrama a seguir mostra os estados possíveis de uma concessão e os comandos ou eventos que causam alterações no estado de concessão.

Diagrama de estados de concessão de contêiner e gatilhos de alteração de estado.

Uma concessão pode estar em um dos cinco 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 de concessão expirou. Ações permitidas: acquire, renew, release e break.

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

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

O Armazenamento de Blobs mantém a ID de concessão após a expiração de uma concessão de contêiner. Um cliente pode renovar ou liberar a concessão usando sua ID de concessão expirada. Se o cliente tentar renovar ou liberar uma concessão expirada com sua ID de concessão anterior e a solicitação falhar, o contêiner será concedido novamente ou excluído, pois a concessão do cliente estava ativa pela última vez.

Se uma concessão expirar em vez de ser lançada explicitamente, um cliente poderá precisar aguardar até um minuto antes que uma nova concessão possa ser adquirida para o contêiner. No entanto, o cliente pode renovar a concessão com a ID expirada imediatamente.

A propriedade do Last-Modified-Time contêiner não é atualizada por chamadas para Lease Container.

As tabelas a seguir mostram resultados de ações em contêineres 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 contêineres por estado da concessão

Ação Disponível Concedida (A) Em interrupção (A) Interrompida (A) Expirada (A)
Excluir com (A) Falha (412) Concedida (A), exclusão bem-sucedida Em interrupção (A), exclusão bem-sucedida Falha (412) Falha (412)
Excluir com (B) Falha (412) Falha (409) Falha (412) Falha (412) Falha (412)
Exclusão, nenhuma concessão especificada Disponível, exclusão bem-sucedida Falha (412) Falha (412) Disponível, exclusão bem-sucedida Disponível, exclusão bem-sucedida
Outras operações com (A) Falha (412) Concedida (A), operação bem-sucedida Em interrupção (A), operação bem-sucedida Falha (412) Falha (412)
Outras operações com (B) Falha (412) Falha (409) Falha (409) Falha (412) Falha (412)
Operações, sem concessão especificada Disponível, a operação foi bem-sucedida Concedida (A), operação bem-sucedida Em interrupção (A), operação bem-sucedida Interrompida (A), operação bem-sucedida Expirada (A), operação bem-sucedida

Resultados de operações de concessão em contêineres 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) Concedida (A)
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)

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

Operação Tipo de conta de armazenamento Categoria de cobrança
Contêiner de Concessão (adquirir, liberar, renovar) Blob de blocos Premium
Uso geral v2 Standard		 Outras operações
Contêiner de Concessão (adquirir, liberar, renovar) Uso geral v1 Standard Operações de leitura
Contêiner de Concessão (quebra, alteração) Blob de blocos Premium
Uso geral v2 Standard		 Outras operações
Contêiner de Concessão (quebra, alteração) 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

Autorizar solicitações para o Armazenamento do Azure
Status e códigos de erro
Códigos de erro do Armazenamento de Blobs
Concessão de blob