Compartilhamento de Concessão

A Lease Share operação estabelece e gerencia um bloqueio em um compartilhamento de arquivos do Azure ou um instantâneo de compartilhamento. Essa API tem suporte total, mas é uma API de gerenciamento herdada. Em vez disso, use Compartilhamentos de Arquivos – Concessão, fornecidos pelo provedor de recursos de armazenamento (Microsoft.Storage). Para saber mais sobre como interagir programaticamente com FileShare recursos usando o provedor de recursos de armazenamento, consulte Operações em FileShares.

A duração do bloqueio pode ser de 15 a 60 segundos, ou pode ser infinita. Você pode chamar a Lease Share operação em um dos seguintes modos:

• Acquire: para solicitar uma nova concessão.
• Renew: para 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 compartilhamento de arquivos.
• 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 tenha expirado.

Observação

A Lease Share operação está disponível na versão 2020-02-10 e posterior.

Disponibilidade do protocolo

Protocolo de compartilhamento de arquivos habilitado	Disponível
SMB
NFS

Solicitação

Você pode construir a solicitação da Lease Share 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.file.core.windows.net/myshare?comp=lease&restype=share	HTTP/1.1
PUT	https://myaccount.file.core.windows.net/myshare?comp=lease&sharesnapshot=<DateTime>&restype=share	HTTP/1.1

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 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: <action>	acquire: solicita uma nova concessão. Se o compartilhamento de arquivos não tiver uma concessão ativa, Arquivos do Azure criará uma concessão no compartilhamento de arquivos e retornará uma nova ID de concessão. Se o compartilhamento de arquivos 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 compartilhamento de arquivos. Observe que você pode renovar a concessão mesmo que ela tenha expirado, desde que o compartilhamento de arquivos não tenha sido concedido 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 compartilhamento de arquivos. A liberação da concessão permite que outro cliente adquira imediatamente a concessão para o compartilhamento de arquivos, assim que a versão for concluída. break: interrompa a concessão, se o compartilhamento de arquivos 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 é interrompida, o período de interrupção de concessão tem permissão para decorrido e break são release as únicas operações que você pode executar no compartilhamento de arquivos 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 compartilhamento de arquivos que foi lançada.
x-ms-lease-break-period: N	Opcional. Para uma break operação, essa é a duração proposta que a concessão deve continuar antes de ser quebrada, em segundos, entre 0 e 60. 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 está 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	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. Armazenamento de Blobs 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.
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 Arquivos do Azure.

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?restype=share&comp=lease HTTP/1.1  
  
Request Headers:  
x-ms-version: 2020-02-10  
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 compartilhamento de arquivos.
Last-Modified	Retorna a data e a hora em que o compartilhamento de arquivos 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 compartilhamento de arquivos, ou suas propriedades ou metadados, atualiza a hora da última modificação. Isso inclui a definição das permissões do compartilhamento de arquivos. As operações em blobs não afetam a hora da última modificação do compartilhamento de arquivos.
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 excluir o compartilhamento de arquivos 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	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 da API FileREST 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.
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 é definido como true.
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: 2020-02-10  
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
Date: Thu, 26 Jan 2012 23:30:18 GMT  

Autorização

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

Comentários

Uma concessão em um compartilhamento de arquivos fornece acesso exclusivo de exclusão ao compartilhamento de arquivos. Obter operações de compartilhamento de arquivos terá êxito em um compartilhamento de arquivos concedido, sem incluir a ID de concessão. Definir operações de compartilhamento de arquivos exigirá a ID de concessão do compartilhamento de arquivos. Se a ID de concessão não estiver incluída em operações de compartilhamento de arquivos definidas, a operação falhará com 412 (falha na pré-condição). A concessão é concedida pela duração especificada quando a concessão é adquirida, que pode ser de 15 a 60 segundos ou 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 renovar a concessão, alterar sua ID de concessão ou liberar a concessão. O diagrama a seguir mostra os cinco estados de uma concessão, bem como os comandos ou os eventos que causam alterações no estado da concessão.

Uma concessão pode estar em qualquer um desses 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.

Arquivos do Azure mantém a ID de concessão depois que uma concessão de compartilhamento de arquivos expirou. 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, isso significa que o compartilhamento de arquivos foi concedido novamente ou excluído desde que sua concessão foi 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 compartilhamento de arquivos. No entanto, o cliente pode renovar a concessão com a ID expirada imediatamente.

A propriedade do compartilhamento de Last-Modified-Time arquivos não é atualizada por chamadas para Lease Share.

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 por Arquivos do Azure.

Resultados de tentativas de uso em compartilhamentos por estado de 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, nenhuma 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 compartilhamentos por estado de 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)