Zakresy list

Operacja List Ranges zwraca listę prawidłowych zakresów dla pliku. Ta operacja jest obsługiwana w wersji 2025-05-05 i nowszych dla udziałów plików z włączonym protokołem NFS. Począwszy od wersji 2026-10-06, operacja ta obsługuje tokeny kontynuacyjne za pomocą parametrów marker i maxresults

Dostępność protokołu

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

Prosić

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

Metoda Identyfikator URI żądania Wersja PROTOKOŁU HTTP
POBIERZ https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist HTTP/1.1
POBIERZ https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&maxresults=<int> HTTP/1.1
POBIERZ https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&marker=<string>&maxresults=<int> HTTP/1.1
POBIERZ https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&marker=<string> HTTP/1.1
POBIERZ https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist HTTP/1.1
POBIERZ https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime> HTTP/1.1
POBIERZ 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 Fakultatywny. Ś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

Możesz określić następujące dodatkowe parametry dla identyfikatora URI żądania.

Parametr Opis
sharesnapshot Fakultatywny. Wersja 2017-04-17 lub nowsza. Parametr sharesnapshot jest nieprzezroczystą wartością DateTime, która w chwili obecnej określa migawkę udziału, aby wykonać zapytanie dotyczące pliku.
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.
prevsharesnapshot Opcjonalnie w wersji 2020-02-10 lub nowszej. Parametr prevsharesnapshot jest nieprzezroczystą wartością DateTime, która w chwili 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. Gdy jest obecna tylko prevsharesnapshot, 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.
maxresults Fakultatywny. Wersja 2026-10-06 i nowsze. Określa maksymalną liczbę zakresów, które należy zwrócić na stronie odpowiedzi. Jeśli maxresults nie jest to określone, usługa próbuje zwrócić wszystkie pozostałe zakresy w jednej odpowiedzi, co może skutkować timeoutem dla bardzo dużych plików.

Jeśli maxresults jest większa niż 10 000, usługa traktuje ją jako 10 000. Ustawienie maxresults wartości mniejszej lub równej zero powoduje wyświetlenie kodu odpowiedzi błędu 400 (nieprawidłowe żądanie).
marker Fakultatywny. Wersja 2026-10-06 i nowsze. Wartość ciągu wskazuje część listy, którą kolejną operacją List Ranges zwróci. Gdy odpowiedź zawiera NextMarker, użyj tej wartości jak marker w kolejnym wywołaniu, aby kontynuować wyliczanie.

Jeśli marker jest określony bez maxresults, usługa nadal rozpoczyna enumerację od pozycji markera, ale nie emituje kolejnego NextMarker.

Wartość znacznika jest nieprzezroczysta dla klienta.

Nagłówki żądań

Wymagane i opcjonalne nagłówki żądań są opisane w następujących tabelach:

Typowe 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 Wymagane dla wszystkich autoryzowanych żądań. Określa wersję operacji do użycia dla tego żądania. Ta operacja jest obsługiwana w wersji 2025-05-05 i nowszych dla udziałów plików z włączonym protokołem NFS. Parametry tokena kontynuacyjnego (marker i maxresults) są dostępne dla wersji 2026-10-06 i nowszych.

Aby uzyskać więcej informacji, zobacz Przechowywanie wersji dla usług Azure Storage.
Range Fakultatywny. Określa zakres bajtów, dla których mają być uwzględniane zakresy. Jeśli pominięto, zwracane są wszystkie zakresy dla pliku.
x-ms-range Fakultatywny. Określa zakres bajtów, dla których mają być uwzględniane zakresy.

Jeśli określono zarówno nagłówki Range, jak 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 usługi Azure Files.
x-ms-lease-id:<ID> Fakultatywny. Wersja 2019-02-02 lub nowsza. Jeśli nagłówek zostanie określony, operacja będzie wykonywana 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).

Ten nagłówek jest ignorowany, jeśli plik znajduje się w udziale plików z włączonym protokołem NFS, który nie obsługuje dzierżaw plikó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.

Ten nagłówek jest ignorowany, jeśli element docelowy znajduje się w udziale plików z włączonym protokołem NFS, który domyślnie obsługuje kropkę końcową.

Aby uzyskać więcej informacji, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych.
x-ms-file-support-rename: { <Boolean> } Fakultatywny. Obsługiwane w wersji 2024-05-04 lub nowszej. Ten nagłówek jest dozwolony tylko wtedy, gdy prevsharesnapshot parametr zapytania jest obecny. Wartość logiczna określa, czy zmienione zakresy dla pliku powinny być wyświetlane, gdy lokalizacja pliku w poprzedniej migawki różni się od lokalizacji w identyfikatorze URI żądania w wyniku operacji zmiany nazwy lub przenoszenia. Jeśli wartość ma wartość true, zostaną zwrócone prawidłowe zmienione zakresy dla pliku. Jeśli wartość ma wartość false, operacja spowoduje niepowodzenie z odpowiedzią 409 (Konflikt). Wartość domyślna to false.

Tylko nagłówki żądań protokołu SMB

Żaden.

Nagłówki żądań NFS

Żaden.

Treść żądania

Żaden.

Odpowiedź

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

Kod stanu

Pomyślna operacja zwraca kod stanu 200 (OK). 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ższych tabelach. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1 .

Typowe nagłówki odpowiedzi

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 ETag zawiera 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 sharesnapshot (jeśli parametr zapytania sharesnapshot 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ę usługi 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 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, ten nagłówek nie będzie obecny w odpowiedzi.

Tylko nagłówki odpowiedzi protokołu SMB

Żaden.

Nagłówki odpowiedzi tylko systemu plików NFS

Żaden.

Treść odpowiedzi

Treść odpowiedzi zawiera listę nienakładających się prawidłowych zakresów posortowanych przez zwiększenie 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.

Gdy maxresults jest określone w żądaniu, a dodatkowe zakresy pozostają pozostające, ciało odpowiedzi zawiera element.NextMarker Format tej 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>
  <NextMarker>opaque-string</NextMarker>
</Ranges>

Element ten NextMarker jest pomijany, gdy nie pozostają już żadne zakresy lub maxresults gdy nie jest określony w żądaniu. Aby kontynuować wyliczanie, podaj NextMarker wartość jako marker parametr w następnym List Ranges żądaniu.

Jeśli określono prevsharesnapshot, odpowiedź zawiera tylko strony, które różnią się między migawką docelową (lub plikiem na żywo) a 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 parametr prevsharesnapshot 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 operacji aktualizacji zakresu i operacjami zakresów przykładami Put Range. W tych przykładach pokazano, jakie zakresy są zwracane w przypadku zapisania lub wyczyszczenia zakresu bajtów 512 z pliku.

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

Począwszy od wersji 2020-02-10, można wywołać List Ranges przy użyciu parametru prevsharesnapshot. Zwraca to zakresy, które różnią się między plikiem na żywo a migawką lub między dwiema 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.

Począwszy od wersji 2026-10-06, możesz wywołać List Ranges za pomocą parametru maxresults ograniczającego liczbę zakresów zwracanych w jednej odpowiedzi. Jeśli odpowiedź nie obejmuje wszystkich pozostałych zakresów, element NextMarker jest uwzględniany w ciele odpowiedzi. Następnie możesz użyć tej wartości jako parametru marker przy kolejnym List Ranges wywołaniu, aby kontynuować wyliczanie tam, gdzie poprzednia odpowiedź się zakończyła.

Używając tokenów kontynuacji, zwróć uwagę na następujące rzeczy:

  • Jeśli marker jest określony bez maxresults, zwroty serwisu rozciągają się od pozycji markera do końca pliku bez emisji kolejnego NextMarker.
  • Jeśli pierwotne żądanie zawierało nagłówek lub Range (or x-ms-range header), kolejne żądania kontynuacji powinny zawierać ten sam nagłówek zakresu. Wartość ta marker ma znaczenie tylko w kontekście oryginalnego zakresu.
  • Jeśli marker odwołuje się do pozycji poza końcem pliku, usługa zwraca 400 (Złe żądanie).

Niektóre operacje na pliku powodują niepowodzenie List Ranges, gdy jest wywoływana 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 nie określono sharesnapshot).
  • 409 (Konflikt) w przypadku wywołania pliku, który był elementem docelowym zastępowania Kopiowania pomigawki , określony 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

  • Last updated on