Compartilhar 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 tem suporte 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 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 Sem

Pedir

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

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

Substitua os componentes de caminho mostrados no URI da solicitação por seus próprios, da seguinte maneira:

Componente path Descrição
myaccount O nome da sua conta de armazenamento.
myshare O nome do 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 Definir tempos limite para operações de Arquivos do Azure.

Cabeçalhos de solicitação

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

Cabeçalho de 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 UTC (Tempo Universal Coordenado) 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 concessão.

Você pode especificar o valor de x-ms-lease-id em qualquer formato de cadeia de 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, 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 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 em 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 do 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 é interrompida imediatamente.
x-ms-lease-duration: -1 Permitido e necessário somente em uma operação de acquire. 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 de concessão proposta, em um formato de cadeia de caracteres GUID. Os Arquivos do Azure retornarão 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 Necessário se Authorization cabeçalho especificar um token OAuth. O valor aceitável é backup. Esse 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 booliano especifica se um ponto à direita presente na URL da solicitação deve ser cortado ou não. Para obter mais informações, consulte Nomenclatura e referência a 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 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 ê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 Status e códigos de erro.

Cabeçalhos de resposta

A resposta dessa 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 de protocolo HTTP/1.1 .

Cabeçalho de 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 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 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. 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 de concessão da concessão ativa.
x-ms-lease-time: seconds Retornado apenas para uma solicitação bem-sucedida para interromper a concessão. 0 é retornado para pausas 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 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 da resposta

Nenhum.

Resposta de exemplo

Veja a seguir uma resposta de exemplo para 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

Somente o proprietário da conta pode chamar essa operação.

Observações

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. 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 essa ID de concessão para alterar sua ID de concessão ou liberar a concessão.

Quando uma concessão está ativa, a ID de concessão 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 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 a ID de concessão para operações GET em um arquivo que tenha uma concessão ativa. No entanto, todas as operações GET 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 de estado de concessão.

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

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 interrompida. 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, pois os instantâneos são somente leitura. Solicitar uma concessão em 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 Desfeito 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 Last-Modified-Time do 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 pelos Arquivos do Azure.

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

Ação Disponível Alugado (A) Quebrado (A)
Gravar usando (A) Falha (412) Arrendado (A), a gravação é bem-sucedida Falha (412)
Gravar usando (B) Falha (412) Falha (409) Falha (412)
Gravação, sem concessão especificada Disponível, a gravação é bem-sucedida Falha (412) Disponível, a gravação é bem-sucedida
Ler usando (A) Falha (412) Concedido (A), leitura bem-sucedida Falha (412)
Leitura usando (B) Falha (412) Falha (409) Falha (412)
Leitura, sem concessão especificada Disponível, a leitura é bem-sucedida Concedido (A), leitura bem-sucedida Quebrado (A), leitura bem-sucedida

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

Ação Disponível Alugado (A) Quebrado (A)
Acquire, nenhuma ID de concessão proposta Alugado (X) Falha (409) Alugado (X)
Acquire (A) Alugado (A) Alugado (A) Alugado (A)
Acquire (B) Alugado (B) Falha (409) Alugado (B)
Break Falha (409) Quebrado (A) Quebrado (A)
Change, (A) para (B) Falha (409) Alugado (B) Falha (409)
Change, (B) para (A) Falha (409) Alugado (A) Falha (409)
Change, (B) para (C) Falha (409) Falha (409) Falha (409)
Release (A) Falha (409) Disponível Disponível
Release (B) Falha (409) Falha (409) Falha (409)

Consulte também