Lease File

L'operazione Lease File crea e gestisce un blocco su un file per le operazioni di scrittura ed eliminazione. Lease File è supportato per la versione 2019-02-02 e successive.

È possibile chiamare l'operazione Lease File in una delle modalità seguenti:

• Acquire, per richiedere un nuovo lease.
• Change, per modificare l'ID di un lease esistente.
• Release, per liberare il lease se non è più necessario, in modo che un altro client possa acquisire immediatamente un lease sul file.
• Break, per terminare forzatamente il lease, ma assicurarsi che un altro client non possa acquisire un nuovo lease fino alla scadenza del periodo di lease corrente.

Disponibilità del protocollo

Protocollo di condivisione file abilitato	Disponibile
SMB
NFS

Richiesta

È possibile costruire la Lease File richiesta come indicato di seguito. È consigliato il protocollo HTTPS.

Metodo	URI richiesta	Versione HTTP
Put	https://myaccount.file.core.windows.net/myshare/mydirectory/myfile?comp=lease	HTTP/1.1

Sostituire i componenti del percorso mostrati nell'URI di richiesta con valori personalizzati, come illustrato di seguito:

Componente percorso	Descrizione
myaccount	nome dell'account di archiviazione.
myshare	Nome della condivisione file.
mydirectorypath	facoltativo. Percorso della directory.
myfile	Nome del file.

Parametri URI

È possibile specificare il parametro aggiuntivo seguente nell'URI della richiesta.

Parametro	Descrizione
timeout	Facoltativa. Il parametro timeout viene espresso in secondi. Per altre informazioni, vedere Impostazione dei timeout per le operazioni di File di Azure.

Intestazioni della richiesta

Nella seguente tabella vengono descritte le intestazioni di richiesta obbligatorie e facoltative.

Intestazione della richiesta	Descrizione
Authorization	Obbligatorio. Specifica lo schema di autorizzazione, il nome dell'account e la firma. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
Date o x-ms-date	Obbligatorio. Specifica la data per la richiesta nel fuso orario UTC (Coordinated Universal Time). Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
x-ms-version	facoltativo. Specifica la versione dell'operazione da usare per questa richiesta. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.
x-ms-lease-id: <ID>	Obbligatoria per rinnovare, modificare o rilasciare il lease. È possibile specificare il valore di x-ms-lease-id in qualsiasi formato di stringa GUID valido. Per un elenco di formati validi, vedere Guid Constructor (String).
x-ms-lease-action: <acquire ¦ change ¦ release ¦ break>	acquire: richiede un nuovo lease. Se il file non ha un lease attivo, File di Azure crea un lease nel file e restituisce un nuovo ID lease. Se il file ha un lease attivo, è possibile richiedere un nuovo lease solo usando l'ID lease attivo. change: modifica l'ID lease di un lease attivo. Un change oggetto deve includere l'ID lease corrente in x-ms-lease-ide un nuovo ID lease in x-ms-proposed-lease-id. release: rilascia il lease. È possibile rilasciare il lease se l'ID lease specificato nella richiesta corrisponde a quello associato al file. Il rilascio del lease consente a un altro client di acquisire immediatamente il lease per il file, non appena la versione è stata completata. break: interrompe il lease, se il file ha un lease attivo. Qualsiasi richiesta autorizzata può interrompere il lease. La richiesta non è necessaria per specificare un ID lease corrispondente. Un lease infinito viene interrotto immediatamente.
x-ms-lease-duration: -1	Consentito e obbligatorio solo in un'operazione acquire . Deve essere -1, per indicare un lease che non scade mai.
x-ms-proposed-lease-id: <ID>	Facoltativo per acquiree obbligatorio per change. ID lease proposto, in un formato di stringa GUID. File di Azure restituisce 400 (Invalid request) se l'ID lease proposto non è nel formato corretto. Per un elenco di formati validi, vedere Guid Constructor (String).
x-ms-client-request-id	facoltativo. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log al momento della configurazione della registrazione. È consigliabile usare questa intestazione per correlare le attività lato client alle richieste ricevute dal server. Per altre informazioni, vedere Monitorare File di Azure.
x-ms-file-request-intent	Obbligatorio se Authorization l'intestazione specifica un token OAuth. Il valore accettabile è backup. Questa intestazione specifica che l'oggetto Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action o Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action deve essere concesso se sono inclusi nei criteri di controllo degli accessi in base al ruolo assegnati all'identità autorizzata tramite l'intestazione Authorization . Disponibile per la versione 2022-11-02 e successive.
x-ms-allow-trailing-dot: { <Boolean> }	facoltativo. Versione 2022-11-02 e successive. Il valore booleano specifica se un punto finale presente nell'URL della richiesta deve essere tagliato o meno. Per altre informazioni, vedere Denominazione e riferimento a condivisioni, directory, file e metadati.

Testo della richiesta

Nessuno.

Richiesta di esempio

Nella richiesta di esempio seguente mostra come acquisire un lease:

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=  

Risposta

Nella risposta sono inclusi un codice di stato HTTP e un set di intestazioni per la risposta.

Codice stato

I codici di stato per le operazioni completate correttamente restituiti per le operazioni di lease sono i seguenti:

• Acquire: un'operazione completata correttamente restituisce il codice di stato 201 (Creato).
• Change: un'operazione completata correttamente restituisce il codice di stato 200 (OK).
• Release: un'operazione completata correttamente restituisce il codice di stato 200 (OK).
• Break: un'operazione completata correttamente restituisce il codice di stato 202 (Accettato).

Per informazioni sui codici di stato, vedere Codici di stato e di errore.

Intestazioni di risposta

Nella risposta per questa operazione sono incluse le intestazioni riportate di seguito; La risposta può includere anche intestazioni HTTP aggiuntive e standard. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1.

Sintassi	Descrizione
ETag	Contiene un valore che è possibile usare per eseguire operazioni in modo condizionale, nelle virgolette. L'operazione Lease File non modifica questa proprietà.
Last-Modified	Data e ora dell'ultima modifica del file. Per altre informazioni, vedere Rappresentazione dei valori data-ora nelle intestazioni. Qualsiasi operazione di scrittura nel file, inclusi gli aggiornamenti sui metadati o sulle proprietà del file, modifica l'ora dell'ultima modifica del file. L'operazione Lease File non modifica questa proprietà.
x-ms-lease-id: <id>	Quando si richiede un lease, File di Azure restituisce un ID lease univoco. Mentre il lease è attivo, è necessario includere l'ID lease con qualsiasi richiesta di scrittura nel file o per modificare o rilasciare il lease. Un'operazione di rinnovo completata correttamente restituisce anche l'ID del lease attivo.
x-ms-lease-time: seconds	Restituito solo per una richiesta riuscita per interrompere il lease. 0 viene restituito per interruzioni immediate.
x-ms-request-id	Identifica in modo univoco la richiesta effettuata e può essere usata per la risoluzione dei problemi della richiesta. Per altre informazioni, vedere Risoluzione dei problemi relativi alle operazioni api.
x-ms-version	Indica la versione di File di Azure usata per eseguire la richiesta.
Date	Valore di data/ora UTC che indica l'ora in cui è stata avviata la risposta. Il servizio genera questo valore.
x-ms-client-request-id	Può essere usato per risolvere le richieste e le risposte corrispondenti. Il valore di questa intestazione è uguale al valore dell'intestazione x-ms-client-request-id , se presente nella richiesta. Il valore è al massimo 1.024 caratteri ASCII visibili. Se l'intestazione x-ms-client-request-id non è presente nella richiesta, non sarà presente nella risposta.

Corpo della risposta

Nessuno.

Risposta di esempio

Di seguito è riportata una risposta di esempio per una richiesta di acquisizione di un lease:

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>  

Autorizzazione

Il proprietario dell'account può chiamare questa operazione. Inoltre, qualsiasi client con una firma di accesso condiviso che dispone dell'autorizzazione per scrivere in questo file o la relativa condivisione può farlo.

Commenti

Un lease in un file fornisce l'accesso esclusivo in scrittura ed eliminazione al file. Per scrivere in un file con un lease attivo, un client deve includere l'ID lease attivo con la richiesta di scrittura. Il lease viene concesso per una durata infinita.

Quando un client acquisisce un lease, viene restituito un ID lease. File di Azure genera un ID lease se non è specificato nella richiesta di acquisizione. Il client può usare questo ID lease per modificare l'ID lease o rilasciare il lease.

Quando un lease è attivo, è necessario includere l'ID lease nella richiesta per le operazioni seguenti:

• Creare file
• Set File Metadata
• Imposta proprietà file
• Delete File
• Put Range
• Copia file (ID lease necessario per il file di destinazione).

Se l'ID lease non è incluso, queste operazioni non riescono in un file lease, con 412 – Precondition failed.

Le operazioni seguenti hanno esito positivo su un file lease, senza includere l'ID lease:

• Get File
• Recupera metadati di file
• Ottenere proprietà file
• List Ranges
• Elenca directory e file
• Copia file (nessun ID lease necessario per il file di origine).
• File di lease (API REST) ( Nessun ID lease necessario per x-ms-lease-action: break.)

Non è necessario includere l'ID lease per GET le operazioni in un file con un lease attivo. Tuttavia, tutte le GET operazioni supportano un parametro di lease condizionale. In questo tipo di parametro l'operazione procede solo se l'ID lease incluso nella richiesta è valido.

Tutte le operazioni di condivisione sono consentite in una condivisione che include file con un lease attivo, tra cui Elimina condivisione. Pertanto, è possibile eliminare una condivisione anche se i file all'interno hanno lease attivi.

Stati di lease

Il diagramma seguente illustra i tre stati di un lease e i comandi o gli eventi che causano modifiche dello stato di lease.

Un lease può essere in tre stati, in base al fatto che il lease sia bloccato o sbloccato e che il lease sia rinnovabile in tale stato. Le azioni di lease visualizzate nel diagramma precedente causano transizioni di stato.

• Available: il lease viene sbloccato e può essere acquisito. Azione consentita: acquire.
• Leased: il lease è bloccato. Azioni consentite: acquire (solo ID lease), change, releasee break.
• Broken: il lease è stato interrotto. Azioni consentite: acquire, release e break.

Si noti che non è possibile concedere un lease per un file in uno snapshot di condivisione, perché gli snapshot sono di sola lettura. La richiesta di un lease su un file in uno snapshot di condivisione genera il codice di stato 400 (richiesta non valida).

Se un lease di file si trova nello stato Interrotto e un'operazione Put Range scrive nel file, lo stato del lease verrà modificato in Disponibile. Tuttavia, se il file ha l'attributo di sola lettura, il server restituirà il conflitto 409.

La proprietà del Last-Modified-Time file non viene aggiornata dalle chiamate a Lease File.

Le tabelle seguenti mostrano i risultati delle azioni sui file con lease in vari stati di lease. Lettere (A), (B) e (C) rappresentano ID lease e (X) rappresenta un ID lease generato da File di Azure.

Risultati dei tentativi di utilizzo nei file in base allo stato del lease

Azione	Disponibile	Con lease (A)	Interrotto (A)
Scrivere usando (A)	Esito negativo (412)	Con lease (A), la scrittura ha esito positivo	Esito negativo (412)
Scrivere usando (B)	Esito negativo (412)	Errore (409)	Esito negativo (412)
Scrittura, nessun lease specificato	Disponibile, la scrittura ha esito positivo	Esito negativo (412)	Disponibile, la scrittura ha esito positivo
Lettura tramite (A)	Esito negativo (412)	Con lease (A), la lettura ha esito positivo	Esito negativo (412)
Lettura tramite (B)	Esito negativo (412)	Esito negativo (409)	Esito negativo (412)
Lettura, nessun lease specificato	Disponibile, la lettura ha esito positivo	Con lease (A), la lettura ha esito positivo	Interrotto (A), la lettura ha esito positivo

Risultati delle operazioni di lease sui file in base allo stato del lease

Azione	Disponibile	Con lease (A)	Interrotto (A)
Acquire, nessun ID lease proposto	Con lease (X)	Esito negativo (409)	Con lease (X)
Acquire (A)	Con lease (A)	Con lease (A)	Con lease (A)
Acquire (B)	Con lease (B)	Esito negativo (409)	Con lease (B)
Break	Esito negativo (409)	Interrotto (A)	Interrotto (A)
Change, (A) - (B)	Esito negativo (409)	Con lease (B)	Esito negativo (409)
Change, (B) - (A)	Esito negativo (409)	Con lease (A)	Esito negativo (409)
Change, (B) - (C)	Esito negativo (409)	Esito negativo (409)	Esito negativo (409)
Release (A)	Esito negativo (409)	Disponibile	Disponibile
Release (B)	Esito negativo (409)	Esito negativo (409)	Esito negativo (409)

Vedi anche

• Autorizzare le richieste ad Archiviazione di Azure
• Stato e codici errore
• codici di errore File di Azure