Pobieranie zakresów stron

Artykuł
02/07/2024

Operacja Pobierz zakresy stron zwraca listę prawidłowych zakresów stron dla stronicowego obiektu blob lub migawki stronicowego obiektu blob.

Żądanie

Żądanie Pobierz zakresy stron może być skonstruowane w następujący sposób. Zalecamy korzystanie z protokołu HTTPS. Zastąp ciąg myaccount nazwą konta magazynu:

Identyfikator URI żądania GET	Wersja PROTOKOŁU HTTP
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>&prevsnapshot=<DateTime>`	HTTP/1.1

Identyfikator URI usługi magazynu emulowanego

Gdy wysyłasz żądanie względem usługi magazynu emulowanego, określ nazwę hosta emulatora i port Azure Blob Storage jako 127.0.0.1:10000, a następnie nazwę emulowanego konta magazynu:

Identyfikator URI żądania GET	Wersja PROTOKOŁU HTTP
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=pagelist`	HTTP/1.1

Aby uzyskać więcej informacji, zobacz Use the Azure Storage Emulator for development and testing (Używanie emulatora usługi Azure Storage do programowania i testowania).

Parametry identyfikatora URI

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

Parametr	Opis
`marker`	Opcjonalnie, wersja 2020-10-02 lub nowsza. Identyfikuje część zakresów, które mają być zwracane przy użyciu następnej operacji GetPageRanges. Operacja zwraca wartość znacznika w treści odpowiedzi, jeśli zwrócone zakresy były niekompletne. Następnie można użyć wartości znacznika w kolejnym wywołaniu w celu zażądania następnego zestawu zakresów. Wartość znacznika jest nieprzezroczysta dla klienta.
`maxresults`	Opcjonalnie, wersja 2020-10-02 lub nowsza. Określa maksymalną liczbę zakresów stron do zwrócenia. Jeśli żądanie określa wartość większą niż 10 000, serwer zwraca maksymalnie 10 000 elementów. Jeśli zostaną zwrócone dodatkowe wyniki, usługa zwróci token kontynuacji w elemecie odpowiedzi NextMarker. Ustawienie `maxresults` wartości mniejszej lub równej zero powoduje wyświetlenie kodu odpowiedzi błędu 400 (Nieprawidłowe żądanie).
`snapshot`	Opcjonalny. Nieprzezroczysta wartość DateTime określająca migawkę obiektu blob, z którego mają być pobierane informacje. Aby uzyskać więcej informacji na temat pracy z migawkami obiektów blob, zobacz Tworzenie migawki obiektu blob.
`timeout`	Opcjonalny. Wyrażone w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi Blob Storage.
`prevsnapshot`	Opcjonalnie, wersja 2015-07-08 i nowsze. Wartość DateTime określająca, że odpowiedź będzie zawierać tylko strony, które zostały zmienione między docelowym obiektem blob a poprzednią migawką. Zmienione strony obejmują zarówno zaktualizowane, jak i wyczyszczone strony. Docelowy obiekt blob może być migawką, o ile migawka określona przez `prevsnapshot` jest starsza od tych dwóch. Uwaga: migawki przyrostowe są obecnie obsługiwane tylko w przypadku obiektów blob utworzonych w dniu 1 stycznia 2016 r. lub później.

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ń, opcjonalnie dla żądań anonimowych. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji dla usług Azure Storage.
`Range`	Opcjonalny. Określa zakres bajtów, których zakres ma zawierać zakresy, włącznie. Jeśli `Range` zostanie pominięty, zostaną zwrócone wszystkie zakresy dla obiektu blob.
`x-ms-range`	Opcjonalny. Określa zakres bajtów, których zakres ma zawierać zakresy, włącznie. Jeśli określono obie `Range` wartości 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 Blob Storage .
`x-ms-lease-id:<ID>`	Opcjonalny. Jeśli ten nagłówek jest określony, operacja jest wykonywana tylko wtedy, gdy zostaną spełnione oba z następujących warunków: — Dzierżawa obiektu blob jest obecnie aktywna. — Identyfikator dzierżawy określony w żądaniu jest zgodny z identyfikatorem dzierżawy obiektu blob. Jeśli ten nagłówek zostanie określony i którykolwiek warunek nie zostanie spełniony, żądanie zakończy się niepowodzeniem, a operacja zakończy się niepowodzeniem z kodem stanu 412 (Niepowodzenie warunku wstępnego).
`x-ms-previous-snapshot-url`	Opcjonalnie, wersja 2019-07-07 lub nowsza. Określa `previous-snapshot-url` , że odpowiedź będzie zawierać tylko strony, które zostały zmienione między docelowym obiektem blob i migawką, które znajdują się w określonym identyfikatorze URI. Zmienione strony obejmują zarówno zaktualizowane, jak i wyczyszczone strony. Docelowy obiekt blob może być migawką, o ile migawka określona przez ten nagłówek jest starsza od tych dwóch. Uwaga: migawki przyrostowe są obecnie obsługiwane tylko w przypadku obiektów blob utworzonych w dniu 1 stycznia 2016 r. i że ten nagłówek powinien być używany tylko w scenariuszach dysku zarządzanego. W przeciwnym razie użyj parametru `prevsnapshot` .
`x-ms-client-request-id`	Opcjonalny. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB), który jest rejestrowany w dziennikach analitycznych po włączeniu rejestrowania w usłudze Azure analityka magazynu. Zdecydowanie zalecamy używanie tego nagłówka podczas korelowania działań po stronie klienta z żądaniami odbieranymi przez serwer. Aby uzyskać więcej informacji, zobacz Informacje o rejestrowaniu analityka magazynu i rejestrowaniu platformy Azure: śledzenie żądań usługi Azure Storage przy użyciu dzienników.

Ta operacja obsługuje również używanie nagłówków warunkowych do pobierania zakresów stron tylko w przypadku spełnienia określonego warunku. Aby uzyskać więcej informacji, zobacz Określanie nagłówków warunkowych dla operacji usługi Blob Storage.

Treść żądania

Brak.

Reakcja

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

Kod stanu

Pomyślna operacja zwraca kod stanu 200 (OK).

Aby uzyskać więcej informacji na temat kodów 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
`Last-Modified`	Data/godzina ostatniej modyfikacji obiektu blob. Format daty jest zgodny z dokumentem RFC 1123. Każda operacja modyfikując obiekt blob, w tym aktualizację metadanych lub właściwości obiektu blob, zmienia czas ostatniej modyfikacji obiektu blob.
`ETag`	Zawiera wartość, która może być używana przez klienta do warunkowego wykonania operacji. Jeśli wersja żądania to 2011-08-18 lub nowsza, wartość elementu ETag jest ujęta w cudzysłów.
`x-ms-blob-content-length`	Rozmiar obiektu blob w bajtach.
`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ę usługi Blob Storage użytą do wykonania żądania. Ten nagłówek jest zwracany w przypadku żądań, które zostały wykonane w wersji 2009-09-19 lub nowszej. Ten nagłówek jest również zwracany dla żądań anonimowych bez określonej wersji, jeśli kontener został oznaczony do dostępu publicznego przy użyciu usługi Blob Storage w wersji 2009-09-19.
`Date`	Wartość daty/godziny UTC wygenerowana przez usługę, która wskazuje godzinę zainicjowania odpowiedzi.
`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 `x-ms-client-request-id` nagłówka, jeśli jest obecna w żądaniu, a wartość zawiera nie więcej niż 1024 widoczne znaki ASCII. `x-ms-client-request-id` Jeśli nagłówek nie znajduje się w żądaniu, nie będzie on obecny w odpowiedzi.

Treść odpowiedzi

Treść odpowiedzi zawiera listę nienakładających się, prawidłowych zakresów stron posortowanych przez zwiększenie zakresu stron adresowych. Format treści odpowiedzi jest następujący:

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

Jeśli cały zestaw stron obiektu blob został wyczyszczone, treść odpowiedzi nie zawiera żadnych zakresów stron.

prevsnapshot Jeśli określono parametr, odpowiedź zawiera tylko strony, które różnią się między migawką docelową lub obiektem blob a poprzednią migawką. Zwrócone strony zawierają obie strony, które zostały zaktualizowane lub wyczyszczone. Format tej treści odpowiedzi jest następujący:

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

Jeśli cały zestaw stron obiektu blob został wyczyszczone, a prevsnapshot parametr nie został określony, treść odpowiedzi nie zawiera żadnych zakresów stron.

maxresults Jeśli określono parametr, odpowiedź zawiera tylko określoną liczbę zakresów z tokenem kontynuacji w taguNextMarker. Token kontynuacji jest pusty, jeśli nie ma więcej oczekujących zakresów lub zawiera nieprzezroczystą wartość, która musi zostać wysłana jako marker parametr w następnym żądaniu. Format tej treści odpowiedzi jest następujący:

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <ClearRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </ClearRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>
   <NextMarker/>
</PageList>

Autoryzacja

Autoryzacja jest wymagana podczas wywoływania dowolnej operacji dostępu do danych w usłudze Azure Storage. Możesz autoryzować operację Get Page Ranges zgodnie z poniższym opisem.

Usługa Azure Storage obsługuje autoryzację żądań do danych obiektów blob przy użyciu Tożsamość Microsoft Entra. Dzięki Tożsamość Microsoft Entra możesz użyć kontroli dostępu opartej na rolach (RBAC) platformy Azure, aby udzielić uprawnień podmiotowi zabezpieczeń. Podmiot zabezpieczeń może być użytkownikiem, grupą, jednostką usługi aplikacji lub tożsamością zarządzaną platformy Azure. Podmiot zabezpieczeń jest uwierzytelniany przez Tożsamość Microsoft Entra w celu zwrócenia tokenu OAuth 2.0. Token może następnie służyć do autoryzowania żądania względem usługi Blob Service.

Aby dowiedzieć się więcej na temat autoryzacji przy użyciu Tożsamość Microsoft Entra, zobacz Autoryzowanie dostępu do obiektów blob przy użyciu Tożsamość Microsoft Entra.

Uprawnienia

Poniżej przedstawiono akcję RBAC niezbędną do wywołania Get Page Ranges operacji przez użytkownika, grupę lub jednostkę usługi Microsoft Entra oraz najmniej uprzywilejowaną wbudowaną rolę RBAC platformy Azure obejmującą tę akcję:

Akcja RBAC platformy Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Najmniej uprzywilejowana wbudowana rola:Czytelnik danych obiektu blob usługi Storage

Aby dowiedzieć się więcej na temat przypisywania ról przy użyciu kontroli dostępu opartej na rolach platformy Azure, zobacz Przypisywanie roli platformy Azure w celu uzyskania dostępu do danych obiektów blob.

Sygnatura dostępu współdzielonego (SAS) zapewnia bezpieczny delegowany dostęp do zasobów na koncie magazynu. Dzięki sygnaturze dostępu współdzielonego masz szczegółową kontrolę nad sposobem uzyskiwania dostępu do danych przez klienta. Możesz określić zasób, do którego zasobu może uzyskiwać dostęp klient, jakie uprawnienia mają do tych zasobów oraz jak długo sygnatura dostępu współdzielonego jest prawidłowa.

Operacja Get Page Ranges obsługuje trzy typy sygnatur dostępu współdzielonego: sygnatury dostępu współdzielonego delegowania użytkownika, sygnatury dostępu współdzielonego usługi i sygnatury dostępu współdzielonego konta.

Najlepszym rozwiązaniem w zakresie zabezpieczeń jest użycie poświadczeń Microsoft Entra zamiast klucza konta magazynu, co może być łatwiejsze w przypadku naruszenia zabezpieczeń. Jeśli projekt aplikacji wymaga sygnatur dostępu współdzielonego, użyj poświadczeń Microsoft Entra, aby utworzyć sygnaturę dostępu współdzielonego delegowania użytkownika, jeśli jest to możliwe.

Jeśli dostęp do klucza współużytkowanego jest niedozwolony dla konta magazynu, token SAS usługi lub token SAS konta nie będzie dozwolony na żądanie do usługi Blob Storage. Aby dowiedzieć się więcej, zobacz Understand how dis disallowing Shared Key affects SAS tokens (Informacje o tym, jak uniemożliwić korzystanie z klucza współużytkowanego wpływa na tokeny SAS).

Sygnatura dostępu współdzielonego delegowania użytkownika

Sygnatura dostępu współdzielonego delegowania użytkownika jest zabezpieczona przy użyciu Microsoft Entra poświadczeń, a także przez uprawnienia określone dla sygnatury dostępu współdzielonego.

Get Page Ranges Wywołanie operacji przy użyciu tokenu SAS delegowanego do kontenera lub zasobu obiektu blob wymaga uprawnienia Odczyt (r) w ramach tokenu SAS delegowania użytkownika.

Aby dowiedzieć się więcej na temat sygnatury dostępu współdzielonego delegowania użytkownika, zobacz Tworzenie sygnatury dostępu współdzielonego delegowania użytkownika.

Sygnatura dostępu współdzielonego usługi

Sygnatura dostępu współdzielonego usługi jest zabezpieczona przy użyciu klucza konta magazynu. Sygnatura dostępu współdzielonego usługi deleguje dostęp do zasobu w jednej usłudze Azure Storage, takiej jak magazyn obiektów blob.

Get Page Ranges Wywołanie operacji przy użyciu tokenu SAS delegowanego do kontenera lub zasobu obiektu blob wymaga uprawnienia Odczyt (r) w ramach tokenu SAS usługi.

Aby dowiedzieć się więcej na temat sygnatury dostępu współdzielonego usługi, zobacz Tworzenie sygnatury dostępu współdzielonego usługi.

Sygnatura dostępu współdzielonego konta

Sygnatura dostępu współdzielonego konta jest zabezpieczona za pomocą klucza konta magazynu. Sygnatura dostępu współdzielonego konta deleguje dostęp do zasobu w co najmniej jednej usłudze magazynu. Wszystkie operacje dostępne za pośrednictwem sygnatury dostępu współdzielonego delegowania usługi lub użytkownika są również dostępne za pośrednictwem sygnatury dostępu współdzielonego konta.

W poniższej tabeli przedstawiono typ podpisanego zasobu i podpisane uprawnienia do określania podczas delegowania dostępu:

Operacja	Podpisana usługa	Typ zasobu podpisanego	Podpisane uprawnienie
Pobieranie zakresów stron	Obiekt blob (b)	Obiekt (o)	Odczyt (r)

Aby dowiedzieć się więcej na temat sygnatury dostępu współdzielonego konta, zobacz Tworzenie sygnatury dostępu współdzielonego konta.

Operacja Get Page Ranges obsługuje autoryzację klucza wspólnego. Autoryzacja przy użyciu kluczy kont nie jest zalecana w przypadku większości scenariuszy, ponieważ jest mniej bezpieczna.

Firma Microsoft zaleca uniemożliwienie autoryzacji klucza współużytkowanego dla konta magazynu, jeśli jest to możliwe. Aby uzyskać więcej informacji, zobacz Zapobieganie autoryzacji za pomocą klucza wspólnego.

Uwagi

Przesunięcia początkowe i końcowe bajtów dla każdego zakresu stron są uwzględniane.

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

Począwszy od wersji 2015-07-08, można wywołać Get Page Ranges metodę z parametrem prevsnapshot , aby zwrócić strony, które różnią się między podstawowym obiektem blob i migawką, lub między dwoma migawkami obiektu blob. Korzystając z tych różnic między stronami, można zapisać przyrostową migawkę stronicowego obiektu blob. Migawki przyrostowe to ekonomiczny sposób tworzenia kopii zapasowych dysków maszyny wirtualnej, jeśli chcesz zaimplementować własne rozwiązanie do tworzenia kopii zapasowych.

Wywołanie Get Page Ranges za pomocą parametru prevsnapshot zwraca strony, które zostały zaktualizowane lub wyczyszczone od czasu wykonania migawki określonej przez prevsnapshot . Następnie możesz skopiować strony, które są zwracane do obiektu blob stronicowego kopii zapasowej na innym koncie magazynu, używając polecenia Umieść stronę.

Od wersji 2019-07-07 można użyć nagłówka x-ms-previous-snapshot-url , aby określić migawki na kontach dysków zarządzanych dla migawek przyrostowych. Jeśli nie używasz dysków zarządzanych, użyj parametru prevsnapshot zapytania.

Niektóre operacje na obiekcie blob powodują Get Page Ranges niepowodzenie, gdy jest wywoływana w celu zwrócenia migawki przyrostowej. Get Pages Ranges Kończy się niepowodzeniem z kodem błędu 409 (konflikt), jeśli jest wywoływany w obiekcie blob , który był obiektem docelowym żądania Put Blob lub Copy Blob po utworzeniu migawki określonej przez prevsnapshot . Jeśli obiektem docelowym Get Page Ranges operacji jest sama migawka, wywołanie zakończy się powodzeniem, o ile migawka określona przez prevsnapshot parametr jest starsza, a żadna operacja lub Copy Blob nie Put Blob została wywołana w interwale między dwoma migawkami.

Uwaga

Migawki przyrostowe są obecnie obsługiwane tylko w przypadku obiektów blob utworzonych w dniu 1 stycznia 2016 r. lub później. Próby użycia tej funkcji w starszym obiekcie blob spowodują BlobOverwritten błąd, który jest kodem błędu HTTP 409 (konflikt).

Zobacz też

Autoryzowanie żądań do usługi Azure Storage
Kody stanu i błędów
Ustawianie limitów czasu dla operacji usługi Blob Storage