Udostępnij za pośrednictwem

Pobieranie zakresów stron

  • Artykuł

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 Twórca migawkę 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.

Ważne

Firma Microsoft zaleca używanie Tożsamość Microsoft Entra z tożsamościami zarządzanymi w celu autoryzowania żądań do usługi Azure Storage. Tożsamość Microsoft Entra zapewnia doskonałe zabezpieczenia i łatwość użycia w porównaniu z autoryzacją klucza wspólnego.

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ą dla użytkownika Microsoft Entra, grupy, tożsamości zarządzanej lub jednostki usługi w celu wywołania Get Page Ranges operacji oraz najmniej uprzywilejowanej wbudowanej roli RBAC platformy Azure, która obejmuje tę akcję:

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.

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