Partilhar via

Arquivo de concessão

  • Artigo

A operação Lease File cria e gerencia um bloqueio em um arquivo para operações de gravação e exclusão. Lease File é suportado para a versão 2019-02-02 e posterior.

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

  • Acquire, para solicitar um novo arrendamento.
  • Change, para alterar a ID de uma concessão existente.
  • Release, para liberar a locação se ela não for mais necessária, para que outro cliente possa adquirir imediatamente uma locação contra o arquivo.
  • Break, para terminar à força o arrendamento, mas garantir que outro cliente não pode adquirir um novo contrato de arrendamento até que o período de arrendamento atual tenha expirado.

Disponibilidade do protocolo

Protocolo de compartilhamento de arquivos habilitado Disponível
PME Sim
NFS Não

Solicitar

A solicitação Lease File é construída da seguinte forma. Recomendamos que você use HTTPS.

Método Solicitar URI Versão HTTP
COLOCAR https://myaccount.file.core.windows.net/myshare/mydirectory/myfile?comp=lease HTTP/1.1

Substitua os componentes de caminho mostrados no URI de solicitação pelo seu, da seguinte maneira:

Componente Caminho Descrição
myaccount O nome da sua conta de armazenamento.
myshare O nome do seu compartilhamento de arquivos.
mydirectorypath Opcional. O caminho para o diretório.
myfile O nome do arquivo.

Parâmetros de URI

Você pode especificar o seguinte parâmetro adicional no URI da solicitação.

Parâmetro Descrição
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Definindo tempos limite para operações do Azure Files.

Cabeçalhos de 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 Necessário. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
Date ou x-ms-date Necessário. Especifica o Tempo Universal Coordenado (UTC) para a solicitação. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
x-ms-version Opcional. Especifica a versão da operação a ser usada para essa 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 locação.

Você pode especificar o valor de x-ms-lease-id em qualquer formato de cadeia de caracteres GUID válido. Consulte Construtor Guid (String) para obter uma lista de formatos válidos.
x-ms-lease-action: <acquire ¦ change ¦ release ¦ break> acquire: Solicita um novo arrendamento. Se o arquivo não tiver uma concessão ativa, os Arquivos do Azure criarão uma concessão no arquivo e retornarão uma nova ID de concessão. Se o arquivo tiver uma concessão ativa, você só poderá solicitar uma nova concessão usando a ID de concessão ativa.

change: Altera o ID de concessão de uma concessão ativa. Um change deve incluir o ID de concessão atual em x-ms-lease-ide um novo ID de concessão em x-ms-proposed-lease-id.

release: Libera o contrato de locação. Você pode liberar a concessão se a ID da concessão especificada na solicitação corresponder à associada ao arquivo. A liberação da locação permite que outro cliente adquira imediatamente a locação para o arquivo, assim que a liberação for concluída.

break: Quebra a concessão, se o arquivo tiver uma concessão ativa. Qualquer pedido autorizado pode quebrar o contrato de arrendamento. A solicitação não é necessária para especificar um ID de concessão correspondente. Um contrato de arrendamento infinito é quebrado imediatamente.
x-ms-lease-duration: -1 Permitido e exigido apenas em uma operação acquire. Obrigatório estar -1, para indicar um contrato de arrendamento que nunca expira.
x-ms-proposed-lease-id: <ID> Opcional para acquiree obrigatório para change. ID de concessão proposta, em um formato de cadeia de caracteres GUID. Os Arquivos do Azure retornam 400 (Invalid request) se a ID de concessão proposta não estiver no formato correto. Consulte Construtor Guid (String) para obter uma lista de formatos válidos.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres de 1 kibibyte (KiB) que é registrado nos logs quando o log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações que o servidor recebe. Para obter mais informações, consulte Monitorar arquivos do Azure.
x-ms-file-request-intent Obrigatório se Authorization cabeçalho especificar um token OAuth. O valor aceitável é backup. Este cabeçalho especifica que os Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action ou Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action devem ser concedidos se forem incluídos na política RBAC atribuída à identidade autorizada usando o cabeçalho Authorization. Disponível para a versão 2022-11-02 e posterior.
x-ms-allow-trailing-dot: { <Boolean> } Opcional. Versão 2022-11-02 e posterior. O valor booleano especifica se um ponto à direita presente na url da solicitação deve ser cortado ou não. Para obter mais informações, consulte Nomeando e referenciando compartilhamentos, diretórios, arquivos e metadados.

Corpo do pedido

Nenhuma.

Pedido de amostra

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

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/mydirectory/myfile?comp=lease HTTP/1.1  
  
Request Headers:  
x-ms-version: 2019-07-07  
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 myaccount: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 sucesso retornados para operações de locação são os seguintes:

  • Acquire: Uma operação bem-sucedida retorna o código de status 201 (Criado).
  • 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 na tabela 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.

Cabeçalho da resposta Descrição
ETag Contém um valor que você pode usar para executar operações condicionalmente, entre aspas. A operação Lease File não modifica essa propriedade.
Last-Modified A data/hora em que o arquivo foi modificado pela última vez. Para obter mais informações, consulte Representação de valores de data-hora em cabeçalhos.

Qualquer operação de gravação no arquivo, incluindo atualizações nos metadados ou propriedades do arquivo, altera a hora da última modificação do arquivo. A operação Lease File não modifica essa propriedade.
x-ms-lease-id:<ID> Quando você solicita uma concessão, os Arquivos do Azure retornam uma ID de concessão exclusiva. Enquanto a concessão estiver ativa, você deve incluir a ID da concessão com qualquer solicitação para gravar no arquivo, alterar ou liberar a concessão.

Uma operação de renovação bem-sucedida também retorna o ID de concessão para a concessão ativa.
x-ms-lease-time: seconds Devolvido apenas para um pedido bem-sucedido para quebrar o contrato. 0 é devolvido para pausas imediatas.
x-ms-request-id Identifica exclusivamente a solicitação que foi feita e pode ser usada para solucionar a solicitação. Para obter mais informações, consulte Solução de problemas de operações de API.
x-ms-version Indica a versão dos Arquivos do Azure usada para executar a solicitação.
Date Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera esse valor.
x-ms-client-request-id Pode ser usado para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho é igual ao valor do cabeçalho x-ms-client-request-id, se ele estiver presente na solicitação. O valor é, no máximo, 1.024 caracteres ASCII visíveis. Se o cabeçalho x-ms-client-request-id não estiver presente na solicitação, ele não estará presente na resposta.

Corpo de resposta

Nenhuma.

Resposta da amostra

Segue-se um exemplo de resposta para um pedido de aquisição de um arrendamento:

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

Autorização

Apenas o proprietário da conta pode chamar esta operação.

Comentários

Uma concessão em um arquivo fornece acesso exclusivo de gravação e exclusão ao arquivo. Para gravar em um arquivo com uma concessão ativa, um cliente deve incluir a ID de concessão ativa com a solicitação de gravação. O contrato de arrendamento é concedido por uma duração infinita.

Quando um cliente adquire uma locação, uma ID de locação é retornada. Os Arquivos do Azure geram uma ID de concessão se uma não for especificada na solicitação de aquisição. O cliente pode usar esse ID de concessão para alterar seu ID de concessão ou liberar a concessão.

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

Se o ID de concessão não estiver incluído, essas operações falharão em um arquivo alugado, com 412 – Precondition failed.

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

Não é necessário incluir o ID de concessão para operações GET em um arquivo que tenha uma concessão ativa. No entanto, todas as operações GET suportam um parâmetro de concessão condicional. Neste tipo de parâmetro, a operação só prossegue se o ID de concessão incluído com a solicitação for válido.

Todas as operações de compartilhamento são permitidas em um compartilhamento que inclui arquivos com uma concessão ativa, incluindo Excluir compartilhamento. Portanto, você pode excluir um compartilhamento mesmo que os arquivos dentro dele tenham concessões ativas.

Estados de arrendamento

O diagrama a seguir mostra os três estados de uma concessão e os comandos ou eventos que causam alterações de estado de concessão.

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

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

  • Available: O contrato de arrendamento está desbloqueado e pode ser adquirido. Ação permitida: acquire.
  • Leased: O contrato de arrendamento está bloqueado. Ações permitidas: acquire (somente mesmo ID de concessão), change, releasee break.
  • Broken: O contrato de arrendamento foi quebrado. Ações permitidas: acquire, releasee break.

Observe que uma concessão não pode ser concedida para um arquivo em um instantâneo de compartilhamento, porque os instantâneos são somente leitura. Solicitar uma concessão em relação a um arquivo em um instantâneo de compartilhamento resulta no código de status 400 (Solicitação incorreta).

Se uma concessão de arquivo estiver no estado Broken e uma operação Put Range gravar no arquivo, o estado de concessão será alterado para Available. No entanto, se o arquivo tiver o atributo somente leitura definido, o servidor retornará o conflito 409.

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

As tabelas a seguir mostram os resultados de ações em arquivos com concessões em vários estados de concessão. As letras (A), (B) e (C) representam IDs de concessão e (X) representam uma ID de concessão gerada pelos Arquivos do Azure.

Resultados das tentativas de uso em arquivos por estado de concessão

Ação Disponível Arrendado (A) Quebrado (A)
Escrever usando (A) Falha (412) Alugado (A), a gravação é bem-sucedida Falha (412)
Escrever usando (B) Falha (412) Falha (409) Falha (412)
Gravação, sem concessão especificada Disponível, a escrita é bem-sucedida Falha (412) Disponível, a escrita é bem-sucedida
Ler utilizando (A) Falha (412) Alugado (A), a leitura é bem-sucedida Falha (412)
Ler utilizando (B) Falha (412) Falha (409) Falha (412)
Leia, nenhuma concessão especificada Disponível, a leitura é bem-sucedida Alugado (A), a leitura é bem-sucedida Quebrado (A), leitura bem-sucedida

Resultados das operações de locação em arquivos por estado de locação

Ação Disponível Arrendado (A) Quebrado (A)
Acquire, sem ID de concessão proposta Arrendado (X) Falha (409) Arrendado (X)
Acquire (A) Arrendado (A) Arrendado (A) Arrendado (A)
Acquire (B) Arrendado (B) Falha (409) Arrendado (B)
Break Falha (409) Quebrado (A) Quebrado (A)
Change, (A) a (B) Falha (409) Arrendado (B) Falha (409)
Change, b) a a) Falha (409) Arrendado (A) Falha (409)
Change, b) a c) Falha (409) Falha (409) Falha (409)
Release (A) Falha (409) Disponível Disponível
Release (B) Falha (409) Falha (409) Falha (409)

Ver também