Zakresy listy

Artykuł
03/29/2023

Operacja List Ranges zwraca listę prawidłowych zakresów dla pliku.

Dostępność protokołu

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

Żądanie

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

Metoda	Identyfikator URI żądania	Wersja PROTOKOŁU HTTP
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime>`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&prevsharesnapshot=<DateTime>`	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 nadrzędnego.
`myfile`	Nazwa pliku.

Aby uzyskać szczegółowe informacje na temat ograniczeń nazewnictwa ścieżek, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych.

Parametry identyfikatora URI

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

Parametr	Opis
`sharesnapshot`	Opcjonalny. Wersja 2017-04-17 lub nowsza. Parametr `sharesnapshot` jest nieprzezroczystą `DateTime` wartością, która w przypadku obecnej określa migawkę udziału do wykonywania zapytań dotyczących pliku.
`timeout`	Opcjonalny. Parametr jest wyrażony `timeout` w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji Azure Files.
`prevsharesnapshot`	Opcjonalnie w wersji 2020-02-10 lub nowszej. Parametr `prevsharesnapshot` jest nieprzezroczystą `DateTime` wartością, która w przypadku obecnej określa poprzednią migawkę. Gdy ten parametr i `sharesnapshot` są obecne, odpowiedź będzie zawierać tylko zakresy stron, które zostały zmienione między dwiema migawkami. `prevsharesnapshot` Gdy tylko jest obecny, odpowiedź będzie zawierać tylko zakresy stron, które zostały zmienione między tą migawką a udziałem na żywo. Zmienione strony obejmują zarówno zaktualizowane, jak i wyczyszczone strony.

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`	Wymagane dla wszystkich autoryzowanych żądań. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji usług Azure Storage.
`Range`	Opcjonalny. Określa zakres bajtów, dla których mają być listowane zakresy, włącznie. Jeśli pominięto, zwracane są wszystkie zakresy dla pliku.
`x-ms-range`	Opcjonalny. Określa zakres bajtów, dla których mają być listowane zakresy, włącznie. Jeśli określono zarówno nagłówki, jak `Range` i `x-ms-range` usługa używa wartości `x-ms-range`. Aby uzyskać więcej informacji, zobacz Określanie nagłówka zakresu dla operacji Azure Files.
`x-ms-lease-id:<ID>`	Opcjonalny. Wersja 2019-02-02 lub nowsza. Jeśli nagłówek zostanie określony, operacja zostanie wykonana tylko wtedy, gdy dzierżawa pliku jest obecnie aktywna, a identyfikator dzierżawy określony w żądaniu jest zgodny z tym plikiem. W przeciwnym razie operacja kończy się niepowodzeniem z kodem stanu 412 (Niepowodzenie warunku wstępnego).
`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.

Reakcja

Odpowiedź zawiera kod stanu HTTP, zestaw nagłówków odpowiedzi i treść odpowiedzi w formacie XML.

Kod stanu

Operacja zakończona powodzeniem zwraca kod stanu 200 (OK). 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.

Nagłówek odpowiedzi	Opis
`Last-Modified`	Data/godzina ostatniej modyfikacji pliku. Każda operacja modyfikując plik, w tym aktualizację metadanych lub właściwości pliku, zmienia czas ostatniej modyfikacji pliku.
`ETag`	Zawiera `ETag` wartość reprezentującą wersję pliku w cudzysłowie.
`x-ms-content-length`	Rozmiar pliku w bajtach. Gdy `prevsharesnapshot` jest obecny, wartość opisuje rozmiar pliku w obiekcie `sharesnapshot` (jeśli `sharesnapshot` parametr zapytania jest obecny). W przeciwnym razie opisuje rozmiar pliku dynamicznego.
`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ę Azure Files używaną do uruchomienia żądania.
`Date` lub `x-ms-date`	Wartość daty/godziny UTC wskazująca godzinę, o której zainicjowano odpowiedź. Usługa generuje tę wartość.
`x-ms-client-request-id`	Ten nagłówek służy do rozwiązywania problemów z żądaniami i odpowiadającymi im 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 istnieje w żądaniu, ten nagłówek nie będzie obecny w odpowiedzi.

Treść odpowiedzi

Treść odpowiedzi zawiera listę nieprawidłowych zakresów, które nie nakładają się, posortowane według rosnącego zakresu adresów. Format treści odpowiedzi jest następujący.

<?xml version="1.0" encoding="utf-8"?>  
<Ranges>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
</Ranges>

Jeśli cały zestaw zakresów pliku został wyczyszczone, treść odpowiedzi nie będzie zawierać żadnych zakresów.

Jeśli prevsharesnapshot zostanie określona, odpowiedź zawiera tylko strony, które różnią się między migawką docelową (lub plikiem na żywo) i poprzednią migawką. Zwrócone zakresy obejmują oba zakresy, które zostały zaktualizowane lub które zostały wyczyszczone. Format tej odpowiedzi jest następujący:

<?xml version="1.0" encoding="utf-8"?> 
<Ranges> 
  <Range> 
    <Start>Start Byte</Start> 
    <End>End Byte</Start> 
  </Range> 
  <ClearRange> 
    <Start>Start Byte</Start>
    <End>End Byte</Start> 
  </ClearRange> 
  <Range> 
    <Start>Start Byte</Start> 
    <End>End Byte</Start> 
  </Range> 
</Ranges>

Jeśli cały zestaw stron pliku został wyczyszczone, a prevsharesnapshot parametr nie zostanie określony, treść odpowiedzi nie będzie zawierać żadnych zakresów.

Autoryzacja

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

Uwagi

Przesunięcia początkowych i końcowych bajtów dla każdego zakresu są uwzględniane. Zapoznaj się z przykładami Operacje aktualizacji zakresu i Operacje czyszczenia zakresu dla operacji Put Range. Te przykłady pokazują, jakie zakresy są zwracane w przypadku zapisania lub wyczyszczenia zakresu bajtów 512 z pliku.

W wysoce rozdrobnionym pliku z dużą liczbą zapisów List Ranges żądanie może zakończyć się niepowodzeniem z powodu wewnętrznego limitu czasu serwera. Aplikacje pobierające zakresy pliku z dużą liczbą operacji zapisu powinny pobierać jednocześnie podzbiór zakresów.

Począwszy od wersji 2020-02-10, można wywołać List Ranges parametr za pomocą parametru prevsharesnapshot . Zwraca to zakresy, które różnią się między plikiem na żywo a migawką lub między dwoma migawkami pliku w migawkach. Korzystając z tych różnic w zakresie, można pobrać przyrostową migawkę pliku. Migawki przyrostowe to ekonomiczny sposób tworzenia kopii zapasowych plików, jeśli chcesz zaimplementować własne rozwiązanie do tworzenia kopii zapasowych.

Niektóre operacje na pliku powodują List Ranges niepowodzenie, gdy jest wywoływany w celu pobrania migawki przyrostowej. Usługa zwraca następujące jednostki:

404 (Nie znaleziono), jeśli wywołasz plik, który nie istnieje w jednej z migawek (lub na żywo, jeśli sharesnapshot nie zostanie określony).
409 (Konflikt) w przypadku wywołania pliku, który był elementem docelowym zastępowania kopii po migawce określonej przez prevsharesnapshot.
409 (Konflikt) w przypadku wywołania pliku, który został usunięty i utworzony ponownie o tej samej nazwie i lokalizacji, po utworzeniu migawki określonej przez prevsharesnapshot .

Zobacz też

Operacje na plikach