Plik dzierżawy

  • Artykuł

Operacja Lease File tworzy blokadę w pliku i zarządza nią na potrzeby operacji zapisu i usuwania. Lease File program 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ępne
SMB Tak
NFS Nie

Żądanie

Żądanie można skonstruować Lease File w następujący sposób. Zalecane jest użycie protokołu HTTPS.

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 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 Opcjonalny. Ścieżka do katalogu.
myfile Nazwa pliku.

Parametry identyfikatora URI

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

Parametr Opis
timeout Opcjonalny. Parametr jest wyrażony timeout w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji 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 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 usług Azure Storage.
x-ms-lease-id: <ID> Wymagane do odnowienia, zmiany lub zwolnienia dzierżawy.

Wartość można określić x-ms-lease-id w dowolnym prawidłowym formacie ciągu IDENTYFIKATORa GUID. Aby uzyskać listę prawidłowych formatów, 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, Azure Files utworzy dzierżawę pliku i zwróci nowy identyfikator dzierżawy. Jeśli plik ma aktywną dzierżawę, możesz zażądać tylko nowej dzierżawy 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 x-ms-lease-idelemencie i nowy identyfikator dzierżawy w pliku x-ms-proposed-lease-id.

release: zwalnia dzierżawę. Dzierżawę można zwolnić, jeśli identyfikator dzierżawy określony na żądaniu jest zgodny z plikiem skojarzonym z 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 natychmiast przerwana.
x-ms-lease-duration: -1 Dozwolone i wymagane tylko w acquire przypadku operacji. Wymagane jest , -1aby wskazać dzierżawę, która nigdy nie wygasa.
x-ms-proposed-lease-id: <ID> Opcjonalne dla acquireelementu , i wymagane dla changeelementu . Proponowany identyfikator dzierżawy w formacie ciągu GUID. Azure Files zwraca wartość400 (Invalid request), jeśli proponowany identyfikator dzierżawy nie jest w poprawnym formacie. Aby uzyskać listę prawidłowych formatów, zobacz Konstruktor guid (ciąg).
x-ms-client-request-id Opcjonalny. Udostępnia 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 Monitorowanie Azure Files.
x-ms-file-request-intent Wymagane, jeśli Authorization nagłówek określa token OAuth. Akceptowalna wartość to backup. Ten nagłówek określa, że wartość Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action lub Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action powinna zostać udzielona, jeśli zostaną one uwzględnione w zasadach RBAC przypisanych do tożsamości, która jest autoryzowana przy użyciu nagłówka Authorization . Dostępne dla wersji 2022-11-02 lub nowszej.
x-ms-allow-trailing-dot: { <Boolean> } Opcjonalny. Wersja 2022-11-02 lub nowsza. Wartość logiczna określa, czy końcowa kropka obecna w adresie URL żądania powinna być przycinana, czy nie. Aby uzyskać więcej informacji, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych.

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 zwrócone dla operacji dzierżawy są następujące:

  • Acquire: Operacja zakończona powodzeniem 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 powodzeniem zwraca kod stanu 202 (Zaakceptowano).

Aby uzyskać informacje o kodach stanu, zobacz Stan i kody 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 nagłówki standardowe są zgodne ze specyfikacją protokołu HTTP/1.1.

Składnia 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> W przypadku żądania dzierżawy Azure Files 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 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ę Azure Files użytą do uruchomienia żądania.
Date Wartość daty/godziny UTC wskazująca godzinę, w 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 im odpowiedziami. Wartość tego nagłówka jest równa wartości x-ms-client-request-id nagłówka, jeśli jest obecna w żądaniu. Wartość wynosi co najwyżej 1024 widoczne znaki ASCII. x-ms-client-request-id Jeśli nagłówek nie jest obecny w żądaniu, nie będzie on 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

Właściciel konta może wywołać tę operację. Ponadto każdy klient z sygnaturą dostępu współdzielonego, który ma uprawnienia do zapisu w tym pliku lub jego udziale, może to zrobić.

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. Azure Files generuje identyfikator dzierżawy, jeśli nie został określony w żądaniu pozyskiwania. 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 wartością 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 GET operacji w pliku, który ma aktywną dzierżawę. Jednak wszystkie GET operacje obsługują parametr dzierżawy warunkowej. W tym typie parametru operacja jest wykonywana 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 powodujące 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 poprzednim 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 dzierżawa nie może zostać udzielona 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).

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

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 Azure Files.

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)
Pisanie 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 dla plików 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ż