Arquivo de concessão

  • Artigo

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

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

  • Acquire, para solicitar uma nova concessão.
  • 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 arquivo.
  • Break, para encerrar a concessão à força, mas verifique se outro cliente não pode adquirir uma nova concessão até que o período de concessão atual tenha expirado.

Disponibilidade do protocolo

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

Solicitação

Você pode construir a solicitação da Lease File seguinte maneira. HTTPS é recomendado.

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

Substitua os componentes do caminho mostrados no URI da solicitação pelos seus próprios, como segue:

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

Parâmetros do URI

Você pode especificar o parâmetro adicional a seguir no URI da 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 Arquivos do Azure.

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 ¦ change ¦ release ¦ break> acquire: solicita uma nova concessão. Se o arquivo não tiver uma concessão ativa, Arquivos do Azure criará uma concessão no arquivo e retornará 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 a ID de concessão de uma concessão ativa. Um change deve incluir a ID de concessão atual em 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 arquivo. A liberação da concessão permite que outro cliente adquira imediatamente a concessão para o arquivo, assim que a versão for concluída.

break: interrompe a concessão, se o arquivo tiver uma concessão ativa. Qualquer solicitação autorizada pode interromper a concessão. A solicitação não é necessária para especificar uma ID de concessão correspondente. Uma concessão infinita é quebrada imediatamente.
x-ms-lease-duration: -1 Permitido e necessário somente em uma acquire operação. Necessário para ser -1, para indicar uma concessão que nunca expira.
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. Arquivos do Azure 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.
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 Arquivos do Azure.
x-ms-file-request-intent Obrigatório se Authorization o cabeçalho especificar um token OAuth. O valor aceitável é backup. Esse cabeçalho especifica que o Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action ou Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action deve ser concedido se eles forem incluídos na política RBAC atribuída à identidade autorizada usando o Authorization cabeçalho . 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 booliano especifica se um ponto à direita presente na URL de solicitação deve ser cortado ou não. Para obter mais informações, consulte Nomenclatura e referência de compartilhamentos, diretórios, arquivos e metadados.

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.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 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).
  • 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, entre aspas. A Lease File operação não modifica essa propriedade.
Last-Modified A data/hora que o arquivo 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 de gravação no arquivo, incluindo atualizações nos metadados ou propriedades do arquivo, altera a hora da última modificação do arquivo. A Lease File operação não modifica essa propriedade.
x-ms-lease-id: <id> Quando você solicita uma concessão, Arquivos do Azure retorna uma ID de concessão exclusiva. Embora a concessão esteja ativa, você deve incluir a ID de concessão com qualquer solicitação para gravar no arquivo, ou para 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 Retornado somente para uma solicitação bem-sucedida para interromper a concessão. 0 é retornado para quebras imediatas.
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 Solução de problemas de operações de API.
x-ms-version Indica a versão do 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 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-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

O proprietário da conta pode chamar essa operação. Além disso, qualquer cliente com uma assinatura de acesso compartilhado que tenha permissão para gravar nesse arquivo ou em seu compartilhamento pode fazer isso.

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. A concessão é concedida por uma duração infinita.

Quando um cliente adquire uma concessão, uma ID de concessão é retornada. Arquivos do Azure 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 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 arquivo concedido, com 412 – Precondition failed.

As seguintes operações têm êxito em um arquivo alugado, sem incluir a ID de concessão:

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

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 concessão

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

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

Uma concessão pode estar em três 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.

  • Available: a concessão é desbloqueada e pode ser adquirida. Ação permitida: acquire.
  • Leased: a concessão está bloqueada. Ações permitidas: acquire (somente a mesma ID de concessão), change, releasee break.
  • Broken: a concessão foi quebrada. Ações permitidas: acquire, release e break.

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

Se uma concessão de arquivo estiver no estado Quebrado e uma operação Put Range for gravada no arquivo, o estado de concessão será alterado para Disponível. No entanto, se o arquivo tiver o atributo somente leitura definido, o servidor retornará o conflito 409.

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

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

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

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

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

Ação Disponível Concedida (A) Interrompida (A)
Acquire, nenhuma ID de concessão proposta Concedida (X) Falha (409) Concedida (X)
Acquire (A) Concedida (A) Concedida (A) Concedida (A)
Acquire (B) Concedida (B) Falha (409) Concedida (B)
Break Falha (409) Interrompida (A) Interrompida (A)
Change, (A) a (B) Falha (409) Concedida (B) Falha (409)
Change, (B) a (A) Falha (409) Concedida (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)

Confira também