Ficheiro de Concessão

A Lease File operação cria e gere um bloqueio num ficheiro para operações de escrita e eliminação. Lease File é suportado para a versão 2019-02-02 e posterior.

Pode chamar a Lease File operação num dos seguintes modos:

• Acquire, para pedir uma nova concessão.
• Change, para alterar o ID de uma concessão existente.
• Release, para libertar a concessão se já não for necessária, para que outro cliente possa adquirir imediatamente uma concessão no ficheiro.
• Break, para terminar a concessão à força, mas certifique-se de que outro cliente não pode adquirir uma nova concessão até que o período de concessão atual expire.

Disponibilidade do protocolo

Protocolo de partilha de ficheiros ativado	Disponível
SMB
NFS

Pedir

Pode construir o pedido da Lease File seguinte forma. É recomendado HTTPS.

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

Substitua os componentes de caminho apresentados no URI do pedido pelo seu, da seguinte forma:

Componente caminho	Description
myaccount	O nome da sua conta de armazenamento.
myshare	O nome da partilha de ficheiros.
mydirectorypath	Opcional. O caminho para o diretório.
myfile	O nome do ficheiro.

Parâmetros URI

Pode especificar o seguinte parâmetro adicional no URI do pedido.

Parâmetro	Description
timeout	Opcional. O timeout parâmetro é expresso em segundos. Para obter mais informações, veja Setting timeouts for Ficheiros do Azure operations (Definir tempos limite para operações de Ficheiros do Azure).

Cabeçalhos do pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Cabeçalho do pedido	Description
Authorization	Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
Date ou x-ms-date	Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
x-ms-version	Opcional. Especifica a versão da operação a utilizar para este pedido. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure.
x-ms-lease-id: <ID>	Necessário para renovar, alterar ou libertar a concessão. Pode especificar o valor de x-ms-lease-id em qualquer formato de cadeia GUID válido. Consulte o Guid Constructor (Cadeia) para obter uma lista de formatos válidos.
x-ms-lease-action: <acquire ¦ change ¦ release ¦ break>	acquire: pede uma nova concessão. Se o ficheiro não tiver uma concessão ativa, Ficheiros do Azure cria uma concessão no ficheiro e devolve um novo ID de concessão. Se o ficheiro tiver uma concessão ativa, só pode pedir uma nova concessão com o ID de concessão ativo. change: altera o ID de concessão de uma concessão ativa. A change tem de incluir o ID de concessão atual no x-ms-lease-ide um novo ID de concessão em x-ms-proposed-lease-id. release: liberta a concessão. Pode libertar a concessão se o ID de concessão especificado no pedido corresponder ao associado ao ficheiro. A libertação da concessão permite que outro cliente adquira imediatamente a concessão do ficheiro, assim que a versão estiver concluída. break: interrompe a concessão, se o ficheiro tiver uma concessão ativa. Qualquer pedido autorizado pode interromper a concessão. O pedido não é necessário para especificar um ID de concessão correspondente. Uma concessão infinita é quebrada imediatamente.
x-ms-lease-duration: -1	Permitido e obrigatório apenas numa acquire operação. Tem de 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 proposto, num formato de cadeia GUID. Ficheiros do Azure devolve 400 (Invalid request) se o ID de concessão proposto não estiver no formato correto. Consulte o Guid Constructor (Cadeia) 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 carateres de 1 kibibyte (KiB) que é registado nos registos quando o registo é configurado. Recomendamos vivamente que utilize este cabeçalho para correlacionar as atividades do lado do cliente com os pedidos que o servidor recebe. Para obter mais informações, veja Monitorizar Ficheiros do Azure.
x-ms-file-request-intent	Necessário se o Authorization cabeçalho especificar um token OAuth. O valor aceitável é backup. Este cabeçalho especifica que o Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action ou Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action deve ser concedido se estiverem incluídos na política RBAC atribuída à identidade autorizada com 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 booleano especifica se um ponto à direita presente no URL do pedido deve ser cortado ou não. Para obter mais informações, veja Nomenclatura e referência de partilhas, diretórios, ficheiros e metadados.

Corpo do pedido

Nenhum.

Pedido de exemplo

O seguinte pedido de exemplo 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 estado HTTP e um conjunto de cabeçalhos de resposta.

Código de estado

Os códigos de estado de êxito devolvidos para as operações de concessão são os seguintes:

• Acquire: uma operação bem-sucedida devolve o código de estado 201 (Criado).
• Change: uma operação bem-sucedida devolve o código de estado 200 (OK).
• Release: uma operação bem-sucedida devolve o código de estado 200 (OK).
• Break: uma operação bem-sucedida devolve o código de estado 202 (Aceite).

Para obter informações sobre códigos de estado, veja Códigos de estado e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os seguintes cabeçalhos. 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.

Syntax	Descrição
ETag	Contém um valor que pode utilizar para efetuar operações condicionalmente, em aspas. A Lease File operação não modifica esta propriedade.
Last-Modified	A data/hora em que o ficheiro foi modificado pela última vez. Para obter mais informações, veja Representação dos valores de data/hora nos cabeçalhos. Qualquer operação de escrita no ficheiro, incluindo atualizações nos metadados ou propriedades do ficheiro, altera a hora da última modificação do ficheiro. A Lease File operação não modifica esta propriedade.
x-ms-lease-id: <id>	Quando pede uma concessão, Ficheiros do Azure devolve um ID de concessão exclusivo. Enquanto a concessão estiver ativa, tem de incluir o ID de concessão com qualquer pedido para escrever no ficheiro, alterar ou libertar a concessão. Uma operação de renovação bem-sucedida também devolve o ID de concessão da concessão ativa.
x-ms-lease-time: seconds	Devolvido apenas para um pedido bem-sucedido para interromper a concessão. 0 é devolvido para pausas imediatas.
x-ms-request-id	Identifica exclusivamente o pedido que foi feito e pode ser utilizado para resolver o pedido. Para obter mais informações, veja Resolver problemas de operações da API.
x-ms-version	Indica a versão do Ficheiros do Azure utilizada para executar o pedido.
Date	Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera este valor.
x-ms-client-request-id	Pode ser utilizado para resolver problemas de pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho, se estiver presente no pedido. O valor é, no máximo, 1024 carateres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente no pedido, não estará presente na resposta.

Corpo da resposta

Nenhum.

Resposta de amostra

Segue-se uma resposta de exemplo para um pedido de aquisição de 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 esta operação. Além disso, qualquer cliente com uma assinatura de acesso partilhado que tenha permissão para escrever neste ficheiro ou na respetiva partilha pode fazê-lo.

Observações

Uma concessão num ficheiro fornece acesso exclusivo de escrita e eliminação ao ficheiro. Para escrever num ficheiro com uma concessão ativa, um cliente tem de incluir o ID de concessão ativo com o pedido de escrita. A concessão é concedida por uma duração infinita.

Quando um cliente adquire uma concessão, é devolvido um ID de concessão. Ficheiros do Azure gera um ID de concessão se não for especificado no pedido de aquisição. O cliente pode utilizar este ID de concessão para alterar o respetivo ID de concessão ou libertar a concessão.

Quando uma concessão está ativa, o ID de concessão tem de ser incluído no pedido de qualquer uma das seguintes operações:

• Criar Ficheiro
• Definir Metadados de Ficheiro
• Definir Propriedades do Ficheiro
• Eliminar Ficheiro
• Colocar Intervalo
• Copiar Ficheiro (ID de Concessão necessário para o ficheiro de destino.)

Se o ID de concessão não estiver incluído, estas operações falham num ficheiro arrendado, com 412 – Precondition failed.

As seguintes operações são bem-sucedidas num ficheiro alugado, sem incluir o ID de concessão:

• Obter Ficheiro
• Obter Metadados de Ficheiro
• Obter Propriedades do Ficheiro
• Intervalos de Lista
• Listar Diretórios e Ficheiros
• Copiar Ficheiro (Não é necessário nenhum ID de concessão para o ficheiro de origem.)
• Ficheiro de Concessão (API REST) (Não é necessário nenhum ID de concessão para x-ms-lease-action: break.)

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

Todas as operações de partilha são permitidas numa partilha que inclui ficheiros com uma concessão ativa, incluindo Eliminar Partilha. Por conseguinte, pode eliminar uma partilha mesmo que os ficheiros no mesmo tenham concessões ativas.

Estados de concessão

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

Uma concessão pode ser em três estados, com base no facto de a concessão estar 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 está desbloqueada e pode ser adquirida. Ação permitida: acquire.
• Leased: A concessão está bloqueada. Ações permitidas: acquire (apenas o mesmo ID de concessão), change, releasee break.
• Broken: A concessão foi interrompida. Ações permitidas: acquire, releasee break.

Tenha em atenção que não é possível conceder uma concessão para um ficheiro num instantâneo de partilha, porque os instantâneos são só de leitura. Pedir uma concessão a um ficheiro num instantâneo de partilha resulta no código de estado 400 (Pedido Incorreto).

Se uma concessão de ficheiros estiver no estado Quebrado e uma operação Put Range escrever no ficheiro, o estado de concessão será alterado para Disponível. No entanto, se o ficheiro tiver o conjunto de atributos só de leitura, o servidor devolverá o conflito 409.

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

As tabelas seguintes mostram os resultados das ações em ficheiros com concessões em vários estados de concessão. As letras (A), (B) e (C) representam IDs de concessão e (X) representam um ID de concessão gerado por Ficheiros do Azure.

Resultados das tentativas de utilização em ficheiros por estado de concessão

Ação	Disponível	Arrendado (A)	Quebrado (A)
Escrever com (A)	Falha (412)	Leased (A), write succeeds (Leased (A), write succeeds (Leased (A), write succeeds	Falha (412)
Escrever com (B)	Falha (412)	Falha (409)	Falha (412)
Escrita, sem concessão especificada	Disponível, escrita com êxito	Falha (412)	Disponível, escrita com êxito
Ler com (A)	Falha (412)	Concessão (A), leitura com êxito	Falha (412)
Ler com (B)	Falha (412)	Falha (409)	Falha (412)
Leitura, sem concessão especificada	Disponível, leitura com êxito	Concessão (A), leitura com êxito	Broken (A), read succeeds (Broken (A), read succeeds (Broken (A), read succeeds

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

Ação	Disponível	Arrendado (A)	Quebrado (A)
Acquire, nenhum ID de concessão proposto	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) para (B)	Falha (409)	Arrendado (B)	Falha (409)
Change, (B) para (A)	Falha (409)	Arrendado (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)

Ver também

• Autorizar pedidos para o Armazenamento do Azure
• Códigos de estado e de erro
• Ficheiros do Azure códigos de erro