Udostępnij za pośrednictwem

Plik dzierżawy

  • Artykuł

Operacja Lease File tworzy blokadę pliku i zarządza nim na potrzeby operacji zapisu i usuwania. program Lease File jest obsługiwany w wersji 2019-02-02 lub nowszej.

Operację Lease File można wywołać w jednym z następujących trybów:

  • Acquire, aby zażądać nowej dzierżawy.
  • Change, aby zmienić identyfikator istniejącej dzierżawy.
  • Release, aby zwolnić dzierżawę, jeśli nie jest już potrzebna, aby inny klient mógł natychmiast uzyskać dzierżawę względem pliku.
  • Break, aby przymusowo zakończyć dzierżawę, ale upewnij się, że inny klient nie może uzyskać nowej dzierżawy do czasu wygaśnięcia bieżącego okresu dzierżawy.

Dostępność protokołu

Włączony protokół udziału plików Dostępny
SMB Tak
NFS nie

Prosić

Żądanie Lease File jest konstruowane w następujący sposób. Zalecamy używanie protokołu HTTPS.

Metoda Identyfikator URI żądania Wersja PROTOKOŁU HTTP
KŁAŚĆ https://myaccount.file.core.windows.net/myshare/mydirectory/myfile?comp=lease HTTP/1.1

Zastąp składniki ścieżki wyświetlane we własnym identyfikatorze URI żądania, w następujący sposób:

Składnik ścieżki Opis
myaccount Nazwa konta magazynu.
myshare Nazwa udziału plików.
mydirectorypath Fakultatywny. Ścieżka do katalogu.
myfile Nazwa pliku.

Parametry identyfikatora URI

Dla identyfikatora URI żądania można określić następujący dodatkowy parametr.

Parametr Opis
timeout Fakultatywny. Parametr timeout jest wyrażony w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi Azure Files.

Nagłówki żądań

W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań.

Nagłówek żądania Opis
Authorization Wymagane. Określa schemat autoryzacji, nazwę konta i podpis. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
Date lub x-ms-date Wymagane. Określa uniwersalny czas koordynowany (UTC) dla żądania. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
x-ms-version Fakultatywny. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji dla usług Azure Storage.
x-ms-lease-id:<ID> Wymagane do odnowienia, zmiany lub zwolnienia dzierżawy.

Wartość x-ms-lease-id można określić w dowolnym prawidłowym formacie ciągu identyfikatora GUID. Zobacz Guid Constructor (String), aby uzyskać listę prawidłowych formatów.
x-ms-lease-action: <acquire ¦ change ¦ release ¦ break> acquire: żąda nowej dzierżawy. Jeśli plik nie ma aktywnej dzierżawy, usługa Azure Files tworzy dzierżawę w pliku i zwraca nowy identyfikator dzierżawy. Jeśli plik ma aktywną dzierżawę, możesz zażądać nowej dzierżawy tylko przy użyciu aktywnego identyfikatora dzierżawy.

change: zmienia identyfikator dzierżawy aktywnej dzierżawy. change musi zawierać bieżący identyfikator dzierżawy w x-ms-lease-idi nowy identyfikator dzierżawy w x-ms-proposed-lease-id.

release: zwalnia dzierżawę. Dzierżawę można zwolnić, jeśli identyfikator dzierżawy określony w żądaniu jest zgodny z tym plikiem. Zwolnienie dzierżawy umożliwia innemu klientowi natychmiastowe uzyskanie dzierżawy dla pliku, gdy tylko wydanie zostanie ukończone.

break: przerywa dzierżawę, jeśli plik ma aktywną dzierżawę. Każde autoryzowane żądanie może przerwać dzierżawę. Żądanie nie jest wymagane do określenia zgodnego identyfikatora dzierżawy. Nieskończona dzierżawa jest przerywana natychmiast.
x-ms-lease-duration: -1 Dozwolone i wymagane tylko w operacji acquire. Wymagane jest, aby -1, aby wskazać dzierżawę, która nigdy nie wygasa.
x-ms-proposed-lease-id: <ID> Opcjonalne dla acquirei wymagane dla change. Proponowany identyfikator dzierżawy w formacie ciągu identyfikatora GUID. Usługa Azure Files zwraca 400 (Invalid request), jeśli proponowany identyfikator dzierżawy nie ma poprawnego formatu. Zobacz Guid Constructor (String), aby uzyskać listę prawidłowych formatów.
x-ms-client-request-id Fakultatywny. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB), który jest rejestrowany w dziennikach podczas konfigurowania rejestrowania. Zdecydowanie zalecamy używanie tego nagłówka do korelowania działań po stronie klienta z żądaniami odbieranymi przez serwer. Aby uzyskać więcej informacji, zobacz Monitor Azure Files.
x-ms-file-request-intent Wymagane, jeśli nagłówek Authorization określa token OAuth. Akceptowalna wartość to backup. Ten nagłówek określa, że Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action lub Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action należy przyznać, jeśli są one uwzględnione w zasadach RBAC przypisanych do tożsamości autoryzowanej przy użyciu nagłówka Authorization. Dostępne dla wersji 2022-11-02 lub nowszej.
x-ms-allow-trailing-dot: { <Boolean> } Fakultatywny. Wersja 2022-11-02 lub nowsza. Wartość logiczna określa, czy końcowa kropka obecna w adresie URL żądania powinna zostać przycięta, czy nie. Aby uzyskać więcej informacji, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych.

Treść żądania

Żaden.

Przykładowe żądanie

Następujące przykładowe żądanie pokazuje, jak uzyskać dzierżawę:

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=

Odpowiedź

Odpowiedź zawiera kod stanu HTTP i zestaw nagłówków odpowiedzi.

Kod stanu

Kody stanu powodzenia zwrócone dla operacji dzierżawy są następujące:

  • Acquire: Operacja zakończona pomyślnie zwraca kod stanu 201 (Utworzono).
  • Change: Operacja zakończona powodzeniem zwraca kod stanu 200 (OK).
  • Release: Operacja zakończona powodzeniem zwraca kod stanu 200 (OK).
  • Break: Operacja zakończona pomyślnie zwraca kod stanu 202 (Zaakceptowane).

Aby uzyskać informacje o kodach stanu, zobacz Stan i kody błędów.

Nagłówki odpowiedzi

Odpowiedź dla tej operacji zawiera nagłówki w poniższej tabeli. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1 .

Nagłówek odpowiedzi Opis
ETag Zawiera wartość, której można użyć do warunkowego wykonywania operacji w cudzysłowie. Operacja Lease File nie modyfikuje tej właściwości.
Last-Modified Data/godzina ostatniej modyfikacji pliku. Aby uzyskać więcej informacji, zobacz Reprezentacja wartości daty i godziny w nagłówkach.

Każda operacja zapisu w pliku, w tym aktualizacje metadanych lub właściwości pliku, zmienia czas ostatniej modyfikacji pliku. Operacja Lease File nie modyfikuje tej właściwości.
x-ms-lease-id:<ID> Podczas żądania dzierżawy usługa Azure Files zwraca unikatowy identyfikator dzierżawy. Gdy dzierżawa jest aktywna, musisz dołączyć identyfikator dzierżawy z dowolnym żądaniem zapisu do pliku lub zmienić lub zwolnić dzierżawę.

Pomyślna operacja odnawiania zwraca również identyfikator dzierżawy dla aktywnej dzierżawy.
x-ms-lease-time: seconds Zwrócone tylko dla pomyślnego żądania przerwania dzierżawy. 0 jest zwracany w przypadku natychmiastowych przerw.
x-ms-request-id Jednoznacznie identyfikuje wykonane żądanie i może służyć do rozwiązywania problemów z żądaniem. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z operacjami interfejsu API.
x-ms-version Wskazuje wersję usługi Azure Files używaną do uruchomienia żądania.
Date Wartość daty/godziny UTC wskazująca godzinę, o której zainicjowano odpowiedź. Usługa generuje tę wartość.
x-ms-client-request-id Może służyć do rozwiązywania problemów z żądaniami i odpowiadającymi odpowiedziami. Wartość tego nagłówka jest równa wartości nagłówka x-ms-client-request-id, jeśli jest obecna w żądaniu. Wartość jest najwyżej 1024 widocznymi znakami ASCII. Jeśli nagłówek x-ms-client-request-id nie znajduje się w żądaniu, nie będzie on obecny w odpowiedzi.

Treść odpowiedzi

Żaden.

Przykładowa odpowiedź

Poniżej przedstawiono przykładową odpowiedź na żądanie uzyskania dzierżawy:

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>

Autoryzacja

Tylko właściciel konta może wywołać tę operację.

Uwagi

Dzierżawa pliku zapewnia wyłączny dostęp do zapisu i usuwania pliku. Aby zapisać w pliku z aktywną dzierżawą, klient musi uwzględnić aktywny identyfikator dzierżawy z żądaniem zapisu. Dzierżawa jest udzielana przez nieskończony czas trwania.

Gdy klient uzyskuje dzierżawę, zwracany jest identyfikator dzierżawy. Usługa Azure Files generuje identyfikator dzierżawy, jeśli nie został określony w żądaniu uzyskania. Klient może użyć tego identyfikatora dzierżawy, aby zmienić jego identyfikator dzierżawy lub zwolnić dzierżawę.

Gdy dzierżawa jest aktywna, identyfikator dzierżawy musi być uwzględniony w żądaniu dla dowolnej z następujących operacji:

Jeśli identyfikator dzierżawy nie jest uwzględniony, te operacje kończą się niepowodzeniem w pliku dzierżawionych z 412 – Precondition failed.

Następujące operacje kończą się powodzeniem w pliku dzierżawionych bez uwzględniania identyfikatora dzierżawy:

Nie jest konieczne uwzględnienie identyfikatora dzierżawy dla operacji GET w pliku, który ma aktywną dzierżawę. Jednak wszystkie operacje GET obsługują parametr dzierżawy warunkowej. W tym typie parametru operacja jest kontynuowana tylko wtedy, gdy identyfikator dzierżawy dołączony do żądania jest prawidłowy.

Wszystkie operacje udziału są dozwolone w udziale zawierającym pliki z aktywną dzierżawą, w tym Usuń udział. W związku z tym można usunąć udział, nawet jeśli pliki w nim mają aktywne dzierżawy.

Stany dzierżawy

Na poniższym diagramie przedstawiono trzy stany dzierżawy oraz polecenia lub zdarzenia, które powodują zmiany stanu dzierżawy.

Diagram przedstawiający stany dzierżawy plików i wyzwalacze zmiany stanu.

Dzierżawa może znajdować się w trzech stanach na podstawie tego, czy dzierżawa jest zablokowana, czy odblokowana, i czy dzierżawa jest odnawialna w tym stanie. Akcje dzierżawy pokazane na powyższym diagramie powodują przejścia stanu.

  • Available: dzierżawa jest odblokowana i może zostać uzyskana. Dozwolona akcja: acquire.
  • Leased: dzierżawa jest zablokowana. Dozwolone akcje: acquire (tylko ten sam identyfikator dzierżawy), change, releasei break.
  • Broken: Dzierżawa została przerwana. Dozwolone akcje: acquire, releasei break.

Należy pamiętać, że nie można udzielić dzierżawy dla pliku w migawki udziału, ponieważ migawki są tylko do odczytu. Żądanie dzierżawy dla pliku w migawce udziału powoduje wyświetlenie kodu stanu 400 (nieprawidłowe żądanie).

Jeśli dzierżawa pliku znajduje się w stanie Broken, a operacja Put Range zapisuje w pliku, stan dzierżawy zmieni się na Dostępne. Jeśli jednak plik ma ustawiony atrybut tylko do odczytu, serwer zwróci konflikt 409.

Właściwość Last-Modified-Time pliku nie jest aktualizowana przez wywołania do Lease File.

W poniższych tabelach przedstawiono wyniki akcji dotyczących plików z dzierżawami w różnych stanach dzierżawy. Litery (A), (B) i (C) reprezentują identyfikatory dzierżawy, a (X) reprezentuje identyfikator dzierżawy wygenerowany przez usługę Azure Files.

Wyniki prób użycia plików według stanu dzierżawy

Akcja Dostępny Dzierżawione (A) Przerwane (A)
Zapisywanie przy użyciu (A) Niepowodzenie (412) Dzierżawiony (A), zapis kończy się powodzeniem Niepowodzenie (412)
Zapisywanie przy użyciu (B) Niepowodzenie (412) Niepowodzenie (409) Niepowodzenie (412)
Zapis, brak określonej dzierżawy Dostępne, zapis kończy się powodzeniem Niepowodzenie (412) Dostępne, zapis kończy się powodzeniem
Odczyt przy użyciu (A) Niepowodzenie (412) Dzierżawione (A), odczyt kończy się powodzeniem Niepowodzenie (412)
Odczyt przy użyciu (B) Niepowodzenie (412) Niepowodzenie (409) Niepowodzenie (412)
Odczyt, brak określonej dzierżawy Dostępne, odczyt kończy się powodzeniem Dzierżawione (A), odczyt kończy się powodzeniem Przerwane (A), odczyt kończy się powodzeniem

Wyniki operacji dzierżawy na plikach według stanu dzierżawy

Akcja Dostępny Dzierżawione (A) Przerwane (A)
Acquire, brak proponowanego identyfikatora dzierżawy Dzierżawione (X) Niepowodzenie (409) Dzierżawione (X)
Acquire (A) Dzierżawione (A) Dzierżawione (A) Dzierżawione (A)
Acquire (B) Dzierżawione (B) Niepowodzenie (409) Dzierżawione (B)
Break Niepowodzenie (409) Przerwane (A) Przerwane (A)
Change, (A) do (B) Niepowodzenie (409) Dzierżawione (B) Niepowodzenie (409)
Change, (B) do (A) Niepowodzenie (409) Dzierżawione (A) Niepowodzenie (409)
Change, (B) do (C) Niepowodzenie (409) Niepowodzenie (409) Niepowodzenie (409)
Release (A) Niepowodzenie (409) Dostępny Dostępny
Release (B) Niepowodzenie (409) Niepowodzenie (409) Niepowodzenie (409)

Zobacz też