Plik dzierżawy

Operacja Lease File tworzy blokadę w pliku i zarządza nią na potrzeby operacji zapisu i usuwania. Lease File Jest obsługiwany w wersjach 2019-02-02 i nowszych.

Operację Lease File można wywołać w jednym z czterech 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 wymuś 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ępne
SMB Yes
NFS No

Żądanie

Żądanie Lease File może być skonstruowane w następujący sposób. Zalecane jest użycie protokołu HTTPS. Zastąp ciąg myaccount nazwą konta magazynu:

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

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

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

Parametry identyfikatora URI

Dla identyfikatora URI żądania można określić następujące dodatkowe parametry.

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

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 dla żądania godzinę w formacie uniwersalnego czasu koordynowanego (UTC). Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
x-ms-version Opcjonalny. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji dla usług Azure Storage Services.
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. Aby uzyskać listę prawidłowych formatów ciągów identyfikatora GUID , zobacz Konstruktor GUID (Ciąg ) .
x-ms-lease-action: <acquire ¦ change ¦ release ¦ break> acquire: żąda nowej dzierżawy. Jeśli plik nie ma aktywnej dzierżawy, usługa Plików tworzy dzierżawę 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. Element change musi zawierać bieżący identyfikator dzierżawy w identyfikatorze x-ms-lease-id i nowy identyfikator dzierżawy w elemencie x-ms-proposed-lease-id.

release: zwalnia dzierżawę. Dzierżawa może zostać zwolniona, jeśli identyfikator dzierżawy określony w żądaniu jest zgodny z plikiem skojarzonym z plikiem. Zwolnienie dzierżawy umożliwia innemu klientowi natychmiastowe uzyskanie dzierżawy dla pliku zaraz po zakończeniu wydania.

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 natychmiast przerywana.
x-ms-lease-duration: -1 Tylko dozwolone i wymagane dla acquire operacji. Musi mieć wartość -1, aby wskazać dzierżawę, która nigdy nie wygasa.
x-ms-proposed-lease-id: <ID> Opcjonalne dla parametru acquire, wymagane dla elementu change. Proponowany identyfikator dzierżawy w formacie ciągu identyfikatora GUID. Usługa plików zwraca 400 (Invalid request) wartość, jeśli proponowany identyfikator dzierżawy nie ma poprawnego formatu. Aby uzyskać listę prawidłowych formatów ciągów identyfikatora GUID , zobacz Konstruktor GUID (Ciąg ) .
x-ms-client-request-id Opcjonalny. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem 1 znaków KiB rejestrowanym w dziennikach analitycznych po włączeniu rejestrowania analizy magazynu. Używanie tego nagłówka jest wysoce zalecane do korelowania działań po stronie klienta z żądaniami odebranymi przez serwer. Aby uzyskać więcej informacji, zobacz Monitorowanie usługi Azure Blob Storage.

Treść żądania

Brak.

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 testaccount1:esSKMOYdK4o+nGTuTyeOLBI+xqnqi6aBmiW4XI699+o=  

Reakcja

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

Kod stanu

Kody stanu powodzenia zwracane dla operacji dzierżawy są następujące:

  • Acquire: Operacja zakończona pomyślnie zwraca kod stanu 201 (Utworzony).
  • Change: Pomyślna operacja zwraca kod stanu 200 (OK).
  • Release: Pomyślna operacja zwraca kod stanu 200 (OK).
  • Break: Pomyślna operacja zwraca kod stanu 202 (Zaakceptowano).

Aby uzyskać informacje o kodach stanu, zobacz Status and Error Codes (Kody stanu i błędów).

Nagłówki odpowiedzi

Odpowiedź na tę operację zawiera następujące nagłówki. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1.

Składnia Opis
ETag Nagłówek 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. Format daty jest zgodny z dokumentem RFC 1123. Aby uzyskać więcej informacji, zobacz Reprezentacja wartości Date-Time 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> Po zażądaniu dzierżawy usługa plików zwraca unikatowy identyfikator dzierżawy. Podczas gdy dzierżawa jest aktywna, należy dołączyć identyfikator dzierżawy z dowolnym żądaniem do zapisu w 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 Ten nagłówek jest zwracany tylko dla pomyślnego żądania przerwania dzierżawy. Wartość 0 jest zwracana w przypadku natychmiastowych przerw.
x-ms-request-id Ten nagłówek 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 plików używaną do wykonania żądania.
Date Wartość daty/godziny UTC wygenerowana przez usługę, która wskazuje godzinę, w której zainicjowano odpowiedź.
x-ms-client-request-id Ten nagłówek może służyć do rozwiązywania problemów z żądaniami i odpowiadającymi im odpowiedziami. Wartość tego nagłówka jest równa wartości x-ms-client-request-id nagłówka, jeśli znajduje się w żądaniu, a wartość wynosi co najwyżej 1024 widoczne znaki ASCII. x-ms-client-request-id Jeśli nagłówek nie znajduje się w żądaniu, ten nagłówek nie będzie obecny w odpowiedzi.
x-ms-client-request-id Ten nagłówek może służyć do rozwiązywania problemów z żądaniami i odpowiadającymi im odpowiedziami. Wartość tego nagłówka jest równa wartości x-ms-client-request-id nagłówka, jeśli znajduje się w żądaniu, a wartość wynosi co najwyżej 1024 widoczne znaki ASCII. x-ms-client-request-id Jeśli nagłówek nie znajduje się w żądaniu, ten nagłówek nie będzie obecny w odpowiedzi.

Treść odpowiedzi

Brak.

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

Ta operacja może być wywoływana przez właściciela konta i przez dowolnego klienta z sygnaturą dostępu współdzielonego, która ma uprawnienia do zapisu w tym pliku lub jego udziale.

Uwagi

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

Gdy klient uzyskuje dzierżawę, zwracany jest identyfikator dzierżawy. Usługa plików wygeneruje identyfikator dzierżawy, jeśli nie zostanie 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 programem 412 – Precondition failed.

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

Nie trzeba uwzględniać identyfikatora dzierżawy dla operacji GET w pliku, który ma aktywną dzierżawę. Jednak wszystkie operacje GET obsługują parametr dzierżawy warunkowej, gdzie 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 udział może zostać usunięty, nawet jeśli pliki w nim mają aktywne dzierżawy.

Na poniższym diagramie przedstawiono trzy stany dzierżawy oraz polecenia lub zdarzenia powodujące zmiany stanu dzierżawy.

File lease states and state change triggers

Stany dzierżawy

Dzierżawa może znajdować się w 3 stanach, na podstawie tego, czy dzierżawa jest zablokowana, czy odblokowana, oraz czy dzierżawa jest odnawialna w tym stanie. Powyższe akcje dzierżawy 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 względem pliku w migawki udziału powoduje wyświetlenie kodu stanu 400 (nieprawidłowe żądanie).

Właściwość pliku Last-Modified-Time 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ę plików.

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

Akcja Dostępne Dzierżawione (A) Przerwane (A)
Pisanie przy użyciu (A) Niepowodzenie (412) Wydzierżawione (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ępne 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ępne Dostępne
Release (B) Niepowodzenie (409) Niepowodzenie (409) Niepowodzenie (409)

Zobacz też