Udział dzierżawy

Operacja Lease Share ustanawia blokadę udziału plików platformy Azure lub migawkę udziału i zarządza nią. Ten interfejs API jest w pełni obsługiwany, ale jest to starszy interfejs API zarządzania. Zamiast tego użyj udziałów plików — dzierżawa dostarczona przez dostawcę zasobów magazynu (Microsoft.Storage). Aby dowiedzieć się więcej o programowej interakcji z FileShare zasobami przy użyciu dostawcy zasobów magazynu, zobacz Operacje na udziałach plików.

Czas trwania blokady może wynosić od 15 do 60 sekund lub może być nieskończony. Operację Lease Share można wywołać w jednym z następujących trybów:

• Acquire: Aby zażądać nowej dzierżawy.
• Renew: Aby odnowić istniejącą dzierżawę.
• 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 udziału plików.
• Break: Aby 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.

Uwaga

Operacja Lease Share jest dostępna w wersji 2020-02-10 lub nowszej.

Dostępność protokołu

Włączony protokół udziału plików	Dostępne
SMB
NFS

Żądanie

Żądanie można skonstruować Lease Share 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?comp=lease&restype=share	HTTP/1.1
PUT	https://myaccount.file.core.windows.net/myshare?comp=lease&sharesnapshot=<DateTime>&restype=share	HTTP/1.1

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ć w dowolnym prawidłowym formacie ciągu identyfikatora x-ms-lease-id GUID. Aby uzyskać listę prawidłowych formatów, zobacz Konstruktor guid (ciąg).
x-ms-lease-action: <action>	acquire: żąda nowej dzierżawy. Jeśli udział plików nie ma aktywnej dzierżawy, Azure Files tworzy dzierżawę udziału plików i zwraca nowy identyfikator dzierżawy. Jeśli udział plików ma aktywną dzierżawę, możesz zażądać tylko nowej dzierżawy przy użyciu aktywnego identyfikatora dzierżawy. Można jednak określić nowy x-ms-lease durationelement , w tym ujemny (-1) dla dzierżawy, która nigdy nie wygasa. renew: odnawia dzierżawę. Dzierżawę można odnowić, jeśli identyfikator dzierżawy określony na żądaniu jest zgodny z udziałem plików skojarzonym z tym udziałem plików. Pamiętaj, że możesz odnowić dzierżawę, nawet jeśli wygasła, o ile udział plików nie został ponownie dzierżawiony od czasu wygaśnięcia tej dzierżawy. Po odnowieniu dzierżawy czas trwania dzierżawy zostanie zresetowany. change: zmień 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: zwolnij dzierżawę. Dzierżawę można zwolnić, jeśli identyfikator dzierżawy określony na żądaniu jest zgodny z udziałem plików skojarzonym z udziałem plików. Zwolnienie dzierżawy umożliwia innemu klientowi natychmiastowe uzyskanie dzierżawy udziału plików, gdy tylko wydanie zostanie ukończone. break: Przerwij dzierżawę, jeśli udział plików ma aktywną dzierżawę. Po przerwaniu dzierżawy nie można jej odnowić. Każde autoryzowane żądanie może przerwać dzierżawę. Żądanie nie jest wymagane do określenia zgodnego identyfikatora dzierżawy. Po przerwaniu dzierżawy okres przerwania dzierżawy może upłynąć i breakrelease są jedynymi operacjami, które można wykonać w udziale plików w tym czasie. Gdy dzierżawa zostanie pomyślnie przerwana, odpowiedź wskazuje interwał w sekundach do momentu uzyskania nowej dzierżawy. Można również zwolnić dzierżawę, która została przerwana. Klient może natychmiast uzyskać dzierżawę udziału plików, która została wydana.
x-ms-lease-break-period: N	Opcjonalny. break W przypadku operacji jest to proponowany czas trwania dzierżawy powinien być kontynuowany przed uszkodzeniem w sekundach od 0 do 60. Ten okres przerwania jest używany tylko wtedy, gdy jest krótszy niż czas pozostały w dzierżawie. Jeśli czas pozostały w dzierżawie jest dłuższy. Nowa dzierżawa nie jest dostępna przed wygaśnięciem okresu przerwania, ale dzierżawa może być przechowywana przez dłuższy niż okres przerwania. Jeśli ten nagłówek nie jest wyświetlany z operacją break , przerwy dzierżawy o stałym czasie trwania po upływie pozostałego okresu dzierżawy i nieskończone przerwy dzierżawy natychmiast.
x-ms-lease-duration: -1	Wymagane dla acquire. Określa czas trwania dzierżawy, w sekundach lub ujemny (-1) dla dzierżawy, która nigdy nie wygasa. Dzierżawa nieskończenie nieskończona może należeć do zakresu od 15 do 60 sekund. Nie można zmienić czasu trwania dzierżawy przy użyciu polecenia renew lub change.
x-ms-proposed-lease-id: <ID>	Opcjonalne dla acquireelementu , i wymagane dla changeelementu . Proponowany identyfikator dzierżawy w formacie ciągu GUID. Azure Blob Storage 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).
Origin	Opcjonalny. Określa pochodzenie, z którego jest wystawiane żądanie. Obecność tego nagłówka powoduje, że nagłówki współużytkowania zasobów między źródłami (CORS) w odpowiedzi. Aby uzyskać szczegółowe informacje , zobacz obsługa mechanizmu CORS dla usług Storage .
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.

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?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=  

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).
• Renew: Pomyślna operacja zwraca kod stanu 200 (OK).
• 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 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	Element ETag dla udziału plików.
Last-Modified	Zwraca datę i godzinę ostatniej modyfikacji udziału plików. Aby uzyskać więcej informacji, zobacz Reprezentacja wartości daty i godziny w nagłówkach. Każda operacja, która modyfikuje udział plików lub jego właściwości lub metadane, aktualizuje czas ostatniej modyfikacji. Obejmuje to ustawienie uprawnień udziału plików. Operacje na obiektach blob nie mają wpływu na czas ostatniej modyfikacji udziału plików.
x-ms-lease-id: <id>	Gdy zażądasz dzierżawy, Azure Files zwraca unikatowy identyfikator dzierżawy. Gdy dzierżawa jest aktywna, musisz dołączyć identyfikator dzierżawy z dowolnym żądaniem usunięcia udziału plików lub odnowić, zmienić lub zwolnić dzierżawę. Pomyślna operacja odnawiania zwraca również identyfikator dzierżawy dla aktywnej dzierżawy.
x-ms-lease-time: seconds	Przybliżony czas pozostały w okresie dzierżawy w sekundach. Ten nagłówek jest zwracany tylko w przypadku pomyślnego żądania przerwania dzierżawy. Jeśli przerwa jest natychmiastowa, 0 jest zwracana.
x-ms-request-id	Unikatowo identyfikuje żądanie, które zostało wykonane 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ę interfejsu API FileREST używanego do uruchamiania żądania.
Date	Wartość daty/godziny UTC wskazująca godzinę, o której zainicjowano odpowiedź. Usługa generuje tę wartość.
Access-Control-Allow-Origin	Zwracany, jeśli żądanie zawiera Origin nagłówek, a mechanizm CORS jest włączony z regułą dopasowania. Ten nagłówek zwraca wartość nagłówka żądania źródła w przypadku dopasowania.
Access-Control-Expose-Headers	Zwracany, jeśli żądanie zawiera Origin nagłówek, a mechanizm CORS jest włączony z regułą dopasowania. Zwraca listę nagłówków odpowiedzi, które mają być widoczne dla klienta lub wystawcy żądania.
Access-Control-Allow-Credentials	Zwracany, jeśli żądanie zawiera Origin nagłówek, a mechanizm CORS jest włączony z regułą dopasowania, która nie zezwala na wszystkie źródła. Ten nagłówek jest ustawiony na truewartość .
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. x-ms-client-request-id Jeśli nagłówek nie znajduje się 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: 2020-02-10  
x-ms-lease-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
Date: Thu, 26 Jan 2012 23:30:18 GMT  

Autoryzacja

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

Uwagi

Dzierżawa udziału plików zapewnia wyłączny dostęp do udziału plików. Operacje pobierania udziału plików zostaną wykonane pomyślnie w dzierżawionych udziałach plików bez uwzględniania identyfikatora dzierżawy. Ustaw operacje udziału plików będą wymagać identyfikatora dzierżawy udziału plików. Jeśli identyfikator dzierżawy nie jest uwzględniony w operacjach ustawiania udziału plików, operacja kończy się niepowodzeniem z błędem 412 (Warunek wstępny nie powiódł się). Dzierżawa jest udzielana przez czas określony podczas pozyskiwania dzierżawy, który może wynosić od 15 do 60 sekund lub 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 uzyskania. Klient może użyć tego identyfikatora dzierżawy do odnowienia dzierżawy, zmiany identyfikatora dzierżawy lub zwolnienia dzierżawy. Na poniższym diagramie przedstawiono pięć stanów dzierżawy oraz polecenia lub zdarzenia, które powodują zmiany stanu dzierżawy.

Dzierżawa może znajdować się w dowolnym z tych stanów 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.

Stan odnowienia	Zablokowana dzierżawa	Odblokowana dzierżawa
Odnawialna dzierżawa	Dzierżawionych	Wygasłe
Dzierżawa nieodnawiona	Kluczowa	Uszkodzone, dostępne

• Available, dzierżawa jest odblokowana i można uzyskać. Dozwolona akcja: acquire.
• Leased, dzierżawa jest zablokowana. Dozwolone akcje: acquire (ten sam identyfikator dzierżawy), renew, change, releasei break.
• Expired, czas trwania dzierżawy wygasł. Dozwolone akcje: acquire, renew, releasei break.
• Breaking, dzierżawa została przerwana, ale dzierżawa będzie nadal blokowana do momentu wygaśnięcia okresu przerwania. Dozwolone akcje: release i break.
• Broken, dzierżawa została przerwana, a okres przerwania wygasł. Dozwolone akcje: acquire, releasei break.

Azure Files zachowuje identyfikator dzierżawy po wygaśnięciu dzierżawy udziału plików. Klient może odnowić lub zwolnić dzierżawę przy użyciu wygasłego identyfikatora dzierżawy. Jeśli klient spróbuje odnowić lub zwolnić wygasłą dzierżawę przy użyciu poprzedniego identyfikatora dzierżawy, a żądanie zakończy się niepowodzeniem, oznacza to, że udział plików został ponownie dzierżawiony lub usunięty od czasu ostatniego uaktywnienia dzierżawy. Jeśli dzierżawa wygaśnie, a nie zostanie jawnie zwolniona, klient może zaczekać do jednej minuty, zanim zostanie uzyskana nowa dzierżawa dla udziału plików. Klient może jednak natychmiast odnowić dzierżawę przy użyciu wygasłego identyfikatora dzierżawy.

Właściwość udziału Last-Modified-Time plików nie jest aktualizowana przez wywołania funkcji Lease Share.

W poniższych tabelach przedstawiono wyniki akcji dla konteneró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 udziałów według stanu dzierżawy

Akcja	Dostępne	Dzierżawione (A)	Niezgodność (A)	Przerwane (A)	Wygasłe (A)
Usuń za pomocą (A)	Niepowodzenie (412)	Dzierżawione (A), usuwanie kończy się powodzeniem	Niezgodność (A), usuwanie powiedzie się	Niepowodzenie (412)	Niepowodzenie (412)
Usuń za pomocą (B)	Niepowodzenie (412)	Niepowodzenie (409)	Niepowodzenie (412)	Niepowodzenie (412)	Niepowodzenie (412)
Usuwanie, brak określonej dzierżawy	Dostępne, usuwanie kończy się powodzeniem	Niepowodzenie (412)	Niepowodzenie (412)	Dostępne, usuwanie kończy się powodzeniem	Dostępne, usuwanie kończy się powodzeniem
Inne operacje z (A)	Niepowodzenie (412)	Operacja dzierżawiona (A) kończy się powodzeniem	Przerywanie operacji (A) kończy się powodzeniem	Niepowodzenie (412)	Niepowodzenie (412)
Inne operacje z (B)	Niepowodzenie (412)	Niepowodzenie (409)	Niepowodzenie (409)	Niepowodzenie (412)	Niepowodzenie (412)
Operacje, bez określonej dzierżawy	Dostępne operacje kończą się powodzeniem	Operacja dzierżawiona (A) kończy się powodzeniem	Przerywanie operacji (A) kończy się powodzeniem	Przerwane (A), operacja kończy się powodzeniem	Wygasła (A), operacja kończy się powodzeniem

Wyniki operacji dzierżawy na udziałach według stanu dzierżawy

Akcja	Dostępne	Dzierżawione (A)	Niezgodność (A)	Przerwane (A)	Wygasłe (A)
Acquire, brak proponowanego identyfikatora dzierżawy	Dzierżawione (X)	Niepowodzenie (409)	Niepowodzenie (409)	Dzierżawione (X)	Dzierżawione (X)
Acquire (A)	Dzierżawione (A)	Dzierżawiony (A), nowy czas trwania	Niepowodzenie (409)	Dzierżawione (A)	Dzierżawione (A)
Acquire (B)	Dzierżawione (B)	Niepowodzenie (409)	Niepowodzenie (409)	Dzierżawione (B)	Dzierżawione (B)
Break, period=0	Niepowodzenie (409)	Przerwane (A)	Przerwane (A)	Przerwane (A)	Przerwane (A)
Break, okres>0	Niepowodzenie (409)	Niezgodność (A)	Niezgodność (A)	Przerwane (A)	Przerwane (A)
Change, (A) do (B)	Niepowodzenie (409)	Dzierżawione (B)	Niepowodzenie (409)	Niepowodzenie (409)	Niepowodzenie (409)
Change, (B) do (A)	Niepowodzenie (409)	Dzierżawione (A)	Niepowodzenie (409)	Niepowodzenie (409)	Niepowodzenie (409)
Change, (B) do (C)	Niepowodzenie (409)	Niepowodzenie (409)	Niepowodzenie (409)	Niepowodzenie (409)	Niepowodzenie (409)
Renew (A)	Niepowodzenie (409)	Dzierżawione (A), resetowanie zegara wygaśnięcia	Niepowodzenie (409)	Niepowodzenie (409)	Dzierżawione (A)
Renew (B)	Niepowodzenie (409)	Niepowodzenie (409)	Niepowodzenie (409)	Niepowodzenie (409)	Niepowodzenie (409)
Release (A)	Niepowodzenie (409)	Dostępne	Dostępne	Dostępne	Dostępne
Release (B)	Niepowodzenie (409)	Niepowodzenie (409)	Niepowodzenie (409)	Niepowodzenie (409)	Niepowodzenie (409)
Czas trwania wygasa	Dostępne	Wygasłe (A)	Przerwane (A)	Przerwane (A)	Wygasłe (A)