Pobieranie listy bloków

  • Artykuł

Operacja Get Block List pobiera listę bloków, które zostały przekazane w ramach blokowego obiektu blob.

Istnieją dwie listy blokowe obsługiwane dla obiektu blob:

  • Zatwierdzona lista bloków: lista bloków, które zostały pomyślnie zatwierdzone do określonego obiektu blob przy użyciu funkcji Umieść listę bloków.

  • Niezatwierdzona lista bloków: lista bloków przekazanych dla obiektu blob przy użyciu funkcji Put Block, ale nie została jeszcze zatwierdzona. Te bloki są przechowywane na platformie Azure w skojarzeniu z obiektem blob, ale nie stanowią jeszcze części obiektu blob.

Możesz wywołać metodę Get Block List , aby zwrócić zatwierdzoną listę bloków, niezatwierdzone listy bloków lub obie listy. Możesz również wywołać tę operację, aby pobrać zatwierdzoną listę bloków dla migawki.

Żądanie

Żądanie Get Block List można skonstruować w następujący sposób. Zalecamy używanie 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=blocklist

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&snapshot=<DateTime>

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&versionid=<DateTime>		 HTTP/1.1

Żądanie usługi magazynu emulowanego

Podczas wysyłania żądania względem emulowanej usługi magazynu określ nazwę hosta emulatora i port usługi Blob Service 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=blocklist HTTP/1.1

Aby uzyskać więcej informacji, zobacz Use the Azurite emulator for local Azure Storage development (Używanie emulatora Azurite do lokalnego programowania w usłudze Azure Storage).

Parametry identyfikatora URI

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

Parametr identyfikatora URI Opis
snapshot Opcjonalny. Parametr migawki jest nieprzezroczystą DateTime wartością określającą listę obiektów blob do pobrania. Aby uzyskać więcej informacji na temat pracy z migawkami obiektów blob, zobacz Tworzenie migawki obiektu blob.
versionid Opcjonalnie dla wersji 2019-12-12 i nowszych. Parametr versionid jest nieprzezroczystą DateTime wartością określającą wersję obiektu blob do pobrania.
blocklisttype Określa, czy należy zwrócić listę zatwierdzonych bloków, listę niezatwierdzonych bloków, czy obie listy razem. Prawidłowe wartości to committed, uncommittedlub all. Jeśli pominięto ten parametr, Get Block List zwraca listę zatwierdzonych bloków.
timeout Opcjonalny. Parametr jest wyrażony timeout w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi Blob Storage.

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 usług Azure Storage.
x-ms-lease-id:<ID> Opcjonalny. Jeśli ten nagłówek zostanie określony, operacja zostanie wykonana tylko wtedy, gdy zostaną spełnione oba następujące warunki:

— Dzierżawa obiektu blob jest obecnie aktywna.
— Identyfikator dzierżawy określony w żądaniu jest zgodny z identyfikatorem obiektu blob.

Jeśli ten nagłówek jest określony i któryś z warunków nie zostanie spełniony, żądanie zakończy się niepowodzeniem, a operacja zakończy się niepowodzeniem z kodem stanu 412 (Warunek wstępny nie powiodło się).
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 Blob Storage.

Ta operacja obsługuje również używanie nagłówków warunkowych do wykonywania operacji tylko wtedy, gdy zostanie spełniony określony warunek. Aby uzyskać więcej informacji, zobacz Określanie nagłówków warunkowych dla operacji usługi Blob Storage.

Treść żądania

Brak.

Przykładowe żądanie

Następujący przykładowy identyfikator URI żądania zwraca zatwierdzoną listę bloków dla obiektu blob o nazwie MOV1.avi:

GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=committed HTTP/1.1

Następujący przykładowy identyfikator URI żądania zwraca zarówno zatwierdzone, jak i niezatwierdzone listy bloków:

GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=all HTTP/1.1

Poniższy przykładowy identyfikator URI żądania zwraca zatwierdzoną listę bloków dla migawki. Migawka składa się tylko z zatwierdzonych bloków, więc nie ma skojarzonych z nim niezatwierdzonych bloków.

GET http://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&snapshot=2009-09-30T20%3a11%3a15.2735974Z

Reakcja

Odpowiedź zawiera kod stanu HTTP, zestaw nagłówków odpowiedzi oraz treść odpowiedzi zawierającą listę bloków.

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 obiektu blob. Format daty jest zgodny z RFC 1123. Aby uzyskać więcej informacji, zobacz Reprezentacja wartości daty/godziny w nagłówkach. Zwracane tylko wtedy, gdy obiekt blob ma zatwierdzone bloki.

Każda operacja modyfikując obiekt blob, w tym aktualizacje metadanych lub właściwości obiektu blob, zmienia czas ostatniej modyfikacji obiektu blob.
ETag Element ETag dla obiektu blob. Zwracane tylko wtedy, gdy obiekt blob ma zatwierdzone bloki.
Content-Type Typ zawartości MIME obiektu blob. Wartość domyślna to application/xml.
x-ms-blob-content-length Rozmiar obiektu blob w bajtach.
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, która została użyta do wykonania żądania. Ten nagłówek jest zwracany dla żądań wysyłanych 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. Uwaga: tylko zatwierdzona lista bloków może być zwracana za pośrednictwem żądania anonimowego.
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 im odpowiedziami. Wartość tego nagłówka jest równa wartości x-ms-client-request-id nagłówka, jeśli znajduje się w żądaniu, a wartość nie zawiera więcej niż 1024 widocznych znaków ASCII. x-ms-client-request-id Jeśli nagłówek nie znajduje się w żądaniu, nie jest obecny w odpowiedzi.

Ta operacja obsługuje również używanie nagłówków warunkowych do pobierania listy bloków tylko wtedy, gdy zostanie spełniony określony warunek. Aby uzyskać więcej informacji, zobacz Określanie nagłówków warunkowych dla operacji usługi Blob Storage.

Treść odpowiedzi

Format treści odpowiedzi dla żądania zwracającego tylko zatwierdzone bloki jest następujący:

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>base64-encoded-block-id</Name>
      <Size>size-in-bytes</Size>
    </Block>
  <CommittedBlocks>
</BlockList>

Format treści odpowiedzi dla żądania zwracającego zarówno zatwierdzone, jak i niezatwierdzone bloki jest następujący:


<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
     <Block>
        <Name>base64-encoded-block-id</Name>
        <Size>size-in-bytes</Size>
     </Block>
  </CommittedBlocks>
  <UncommittedBlocks>
    <Block>
      <Name>base64-encoded-block-id</Name>
      <Size>size-in-bytes</Size>
    </Block>
  </UncommittedBlocks>
 </BlockList>

Przykładowa odpowiedź

W poniższym przykładzie blocklisttype parametr został ustawiony na committedwartość , więc w odpowiedzi są zwracane tylko zatwierdzone bloki obiektu blob.

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Sun, 25 Sep 2011 00:33:19 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>4194304</Size>
    </Block>
  </CommittedBlocks>
</BlockList>

W tym przykładzie blocklisttype parametr został ustawiony na allwartość , a zarówno zatwierdzone, jak i niezatwierdzone bloki obiektu blob są zwracane w odpowiedzi.

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Sun, 25 Sep 2011 00:35:56 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>4194304</Size>
    </Block>
  </CommittedBlocks>
  <UncommittedBlocks>
    <Block>
      <Name>BlockId003</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId004</Name>
      <Size>1024000</Size>
    </Block>
  </UncommittedBlocks>
</BlockList>

W następnym przykładzie blocklisttype parametr został ustawiony na allwartość , ale obiekt blob nie został jeszcze zatwierdzony, więc CommittedBlocks element jest pusty.

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Wed, 14 Sep 2011 00:40:22 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks />
  <UncommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId003</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId004</Name>
      <Size>1024</Size>
    </Block>
  </UncommittedBlocks>
</BlockList>

Autoryzacja

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

Usługa Azure Storage obsługuje używanie Tożsamość Microsoft Entra do autoryzacji żądań do danych obiektów blob. Za pomocą 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 wymieniono akcję RBAC niezbędną do wywołania Get Block List operacji przez użytkownika, grupę lub jednostkę usługi Microsoft Entra oraz najmniej uprzywilejowaną wbudowaną rolę 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

Wywołaj metodę Get Block List , aby zwrócić listę blokowych bloków, które zostały zatwierdzone do blokowego obiektu blob, listę bloków, które jeszcze nie zostały zatwierdzone, lub obie listy. Użyj parametru , blocklisttype aby określić listę bloków do zwrócenia. Lista zatwierdzonych bloków jest zwracana w tej samej kolejności, w której zostały zatwierdzone przez operację Umieszczanie listy bloków .

Możesz użyć niezatwierdzonej listy bloków, aby określić, które bloki brakuje w obiekcie blob w przypadkach, w których wywołania do Put Block lub Put Block List zakończyły się niepowodzeniem. Lista niezatwierdzonych bloków jest zwracana w kolejności alfabetycznej. Jeśli identyfikator bloku został przekazany więcej niż raz, na liście pojawi się tylko ostatnio przekazany blok.

Uwaga

Gdy obiekt blob nie został jeszcze zatwierdzony, wywołanie polecenia Get Block List z blocklisttype=all zwraca niezatwierdzonymi blokami, a CommittedBlocks element jest pusty.

Get Block List nie obsługuje współbieżności, gdy odczytuje listę niezatwierdzonych bloków. Wywołania do Get Block List lokalizacji blocklisttype=uncommitted lub blocklisttype=all mają niższą maksymalną szybkość żądań niż inne operacje odczytu. Aby uzyskać szczegółowe informacje na temat docelowej przepływności dla operacji odczytu, zobacz Azure Storage scalability and performance targets (Cele dotyczące skalowalności i wydajności usługi Azure Storage).

Od wersji 2019-12-12 blokowy obiekt blob może zawierać bloki do 4000 mebibajtów (MiB). Aby chronić aplikacje używające podpisanej liczby całkowitej 32-bitowej do reprezentowania rozmiaru bloku, wywołując Get Block List blokowy obiekt blob zawierający blok większy niż 100 MiB z wersją REST starszą niż 2019-12-12 powoduje wyświetlenie kodu stanu 409 (konflikt).

Get Block List dotyczy tylko blokowych obiektów blob. Wywoływanie Get Block List stronicowego obiektu blob powoduje wyświetlenie kodu stanu 400 (nieprawidłowe żądanie).

Get Block List w zarchiwizowanym obiekcie blob blokowym zakończy się niepowodzeniem.

Rozliczenia

Żądania cenowe mogą pochodzić od klientów korzystających z interfejsów API usługi Blob Storage bezpośrednio za pośrednictwem interfejsu API REST usługi Blob Storage lub biblioteki klienta usługi Azure Storage. Te żądania naliczają opłaty za transakcję. Typ transakcji wpływa na sposób naliczania opłat za konto. Na przykład transakcje odczytu są naliczane do innej kategorii rozliczeniowej niż transakcje zapisu. W poniższej tabeli przedstawiono kategorię rozliczeń dla Get Block List żądań na podstawie typu konta magazynu:

Operacja Typ konta magazynu Kategoria rozliczeń
Pobieranie listy bloków Blokowy obiekt blob w warstwie Premium
Standardowa ogólnego przeznaczenia, wersja 2		 Inne operacje
Pobieranie listy bloków Standardowa ogólnego przeznaczenia, wersja 1 Operacje odczytu

Aby dowiedzieć się więcej o cenach dla określonej kategorii rozliczeń, zobacz Azure Blob Storage Cennik.

Zobacz też

Autoryzowanie żądań do stanu usługi Azure Storagei kodów błędów usługi Blob Storage — ustawianie limitów czasu dla operacji usługi Blob Storage