Udostępnij za pośrednictwem

Wyświetlanie listy obiektów blob

  • Artykuł

Operacja List Blobs zwraca listę obiektów blob w określonym kontenerze.

Prosić

Żądanie List Blobs można skonstruować w następujący sposób. Zalecany jest protokół HTTPS. Zastąp wartość myaccount nazwą konta magazynu.

Metoda Identyfikator URI żądania Wersja PROTOKOŁU HTTP
GET https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list HTTP/1.1

Identyfikator URI usługi magazynu emulowanego

Po wysłaniu żądania względem emulowanej usługi magazynu określ nazwę hosta emulatora i port usługi Azure Blob Storage jako 127.0.0.1:10000, a następnie nazwę emulowanego konta magazynu.

Metoda Identyfikator URI żądania Wersja PROTOKOŁU HTTP
GET http://127.0.0.1:10000/devstoreaccount1/mycontainer?restype=container&comp=list HTTP/1.1

Aby uzyskać więcej informacji, zobacz Use Azurite emulator for local Azure Storage development.

Parametry identyfikatora URI

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

Parametr Opis
prefix Fakultatywny. Filtruje wyniki, aby zwracać tylko obiekty blob z nazwami rozpoczynającymi się od określonego prefiksu. W przypadku kont, które mają hierarchiczną przestrzeń nazw, wystąpi błąd w przypadkach, gdy nazwa pliku pojawia się w środku ścieżki prefiksu. Na przykład możesz spróbować znaleźć obiekty blob o nazwie readmefile.txt przy użyciu ścieżki prefiksu folder1/folder2/readme/readmefile.txt. Zostanie wyświetlony błąd, jeśli jakikolwiek podfolder zawiera plik o nazwie readme.
delimiter Fakultatywny. Gdy żądanie zawiera ten parametr, operacja zwraca element BlobPrefix w treści odpowiedzi. Ten element działa jako symbol zastępczy dla wszystkich obiektów blob z nazwami rozpoczynającymi się od tego samego podciągu, aż do wyglądu znaku ogranicznika. Ogranicznik może być pojedynczym znakiem lub ciągiem.
marker Fakultatywny. Wartość ciągu identyfikującą część listy, która ma zostać zwrócona przy użyciu następnej operacji listy. Operacja zwraca wartość znacznika w treści odpowiedzi, jeśli zwrócona lista nie została ukończona. Następnie możesz użyć wartości znacznika w kolejnym wywołaniu, aby zażądać następnego zestawu elementów listy.

Wartość znacznika jest nieprzezroczysta dla klienta.
maxresults Fakultatywny. Określa maksymalną liczbę obiektów blob do zwrócenia, łącznie ze wszystkimi elementami BlobPrefix. Jeśli żądanie nie określi maxresultslub określa wartość większą niż 5000, serwer zwróci do 5000 elementów. Jeśli istnieją dodatkowe wyniki do zwrócenia, usługa zwraca token kontynuacji w elemecie odpowiedzi NextMarker. W niektórych przypadkach usługa może zwrócić mniej wyników niż określone przez maxresults, a także zwrócić token kontynuacji.

Ustawienie maxresults wartości mniejszej lub równej zero powoduje wyświetlenie kodu odpowiedzi błędu 400 (nieprawidłowe żądanie).
include={snapshots,metadata,uncommittedblobs,copy,deleted,tags,versions,
deletedwithversions,immutabilitypolicy,legalhold,permissions}		 Fakultatywny. Określa co najmniej jeden zestaw danych do uwzględnienia w odpowiedzi:

- snapshots: określa, że migawki powinny być uwzględnione w wyliczenie. Migawki są wyświetlane od najstarszych do najnowszych w odpowiedzi.
- metadata: określa, że metadane obiektu blob są zwracane w odpowiedzi.
- uncommittedblobs: określa, że obiekty blob, dla których zostały przekazane bloki, ale które nie zostały zatwierdzone przy użyciu Umieść listę bloków, należy uwzględnić w odpowiedzi.
- copy: wersja 2012-02-12 lub nowsza. Określa, że metadane powiązane z dowolną bieżącą lub poprzednią operacją Copy Blob powinny być uwzględnione w odpowiedzi.
- deleted: wersja 2017-07-29 lub nowsza. Określa, że w odpowiedzi powinny zostać uwzględnione obiekty blob usunięte nietrwało.
- tags: wersja 2019-12-12 lub nowsza. Określa, że tagi indeksu obiektów blob zdefiniowane przez użytkownika powinny być uwzględnione w odpowiedzi.
- versions: wersja 2019-12-12 lub nowsza. Określa, że wersje obiektów blob powinny być uwzględnione w wyliczenie.
- deletedwithversions: wersja 2020-10-02 lub nowsza. Określa, że usunięte obiekty blob z dowolnymi wersjami (aktywne lub usunięte) powinny być uwzględnione w odpowiedzi. Elementy, które zostały trwale usunięte, są wyświetlane w odpowiedzi do momentu przetworzenia ich przez odzyskiwanie pamięci. Użyj \<HasVersionsOnly\>tagu i wartości true.
- immutabilitypolicy: wersja 2020-06-12 lub nowsza. Określa, że wyliczenie powinno zawierać zasady niezmienności do daty i tryb zasad niezmienności obiektów blob.
- legalhold: wersja 2020-06-12 lub nowsza. Określa, że wyliczenie powinno zawierać archiwizację prawną obiektów blob.
- permissions: wersja 2020-06-12 lub nowsza. Obsługiwane tylko dla kont z włączoną hierarchiczną przestrzenią nazw. Jeśli żądanie zawiera ten parametr, właściciel, grupa, uprawnienia i lista kontroli dostępu dla wymienionych obiektów blob lub katalogów zostanie uwzględniona w wyliczenie.

Aby określić więcej niż jedną z tych opcji w identyfikatorze URI, należy oddzielić każdą opcję przecinkiem zakodowanym pod adresem URL ("%82").
showonly={deleted,files,directories} Fakultatywny. Określa jeden z tych zestawów danych, które mają być zwracane w odpowiedzi:

- deleted: opcjonalne. Wersja 2020-08-04 lub nowsza. Tylko dla kont z włączoną hierarchiczną przestrzenią nazw. Gdy żądanie zawiera ten parametr, lista zawiera tylko obiekty blob usunięte nietrwale. Należy pamiętać, że rezerwowa autoryzacja listy ACL poSIX nie jest obsługiwana w przypadku wyświetlania listy nietrwałych usuniętych obiektów blob. Jeśli określono również include=deleted, żądanie zakończy się niepowodzeniem z nieprawidłowym żądaniem (400).
- files: opcjonalne. Wersja 2020-12-06 lub nowsza. Tylko dla kont z włączoną hierarchiczną przestrzenią nazw. Jeśli żądanie zawiera ten parametr, lista zawiera tylko pliki.
- directories: opcjonalne. Wersja 2020-12-06 lub nowsza. Tylko dla kont z włączoną hierarchiczną przestrzenią nazw. Jeśli żądanie zawiera ten parametr, lista zawiera tylko katalogi.
timeout Fakultatywny. Parametr timeout jest wyrażony 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 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ń i opcjonalne 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.
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 Blob Storage.
x-ms-upn Fakultatywny. Prawidłowe tylko wtedy, gdy dla konta jest włączona hierarchiczna przestrzeń nazw, a include=permissions jest podana w żądaniu. Jeśli true, wartości tożsamości użytkownika zwrócone w>właściciel <, <grupy>i <pola listy Acl> są przekształcane z identyfikatorów obiektów Entra firmy Microsoft na główne nazwy użytkowników. Jeśli false, wartości są zwracane jako identyfikatory obiektów Entra firmy Microsoft. Domyślna wartość to false. Należy pamiętać, że identyfikatory obiektów grup i aplikacji nie są tłumaczone, ponieważ nie mają unikatowych przyjaznych nazw.

Treść żądania

Żaden.

Przykładowe żądanie

Aby uzyskać przykładowe żądanie, zobacz Wyliczanie zasobów obiektów blob.

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 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 .

Nagłówek odpowiedzi Opis
Content-Type Określa format, w którym są zwracane wyniki. Obecnie ta wartość jest application/xml.
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 Blob Storage używaną do uruchamiania żądania. Ten nagłówek jest zwracany dla żądań wysyłanych przy użyciu wersji 2009-09-19 lub nowszej.

Ten nagłówek jest również zwracany w przypadku żądań anonimowych bez określonej wersji, jeśli kontener został oznaczony do dostępu publicznego przy użyciu wersji 2009-09-19 usługi Blob Storage.
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.

Treść odpowiedzi

Format odpowiedzi XML jest następujący.

Należy pamiętać, że elementy Prefix, Marker, MaxResultsi Delimiter są obecne tylko wtedy, gdy zostały określone na identyfikatorze URI żądania. Jeśli NextMarker jest pusta, wyniki listy zostaną ukończone. Jeśli NextMarker nie jest pusta, wyniki listy mogą być lub nie zostaną ukończone. Jeśli chcesz wyświetlić listę wszystkich obiektów blob, kontynuuj wywoływanie List Blobs z kolejnymi wartościami znaczników, dopóki NextMarker nie będą puste.

Migawki, metadane obiektów blob i niezatwierdzone obiekty blob są uwzględniane w odpowiedzi tylko wtedy, gdy są określone za pomocą parametru include dla identyfikatora URI żądania.

W wersji 2009-09-19 i nowszych właściwości obiektu blob są hermetyzowane w ramach elementu Properties.

Począwszy od wersji 2009-09-19, List Blobs zwraca następujące elementy zmienione nazwy w treści odpowiedzi:

  • Last-Modified (wcześniej LastModified)

  • Content-Length (wcześniej Size)

  • Content-Type (wcześniej ContentType)

  • Content-Encoding (wcześniej ContentEncoding)

  • Content-Language (wcześniej ContentLanguage)

Element Content-MD5 jest wyświetlany dla obiektów blob utworzonych w wersji 2009-09-19 lub nowszej. W wersji 2012-02-12 lub nowszej usługa Blob Storage oblicza wartość Content-MD5 podczas przekazywania obiektu blob przy użyciu Put Blob. Usługa Blob Storage nie oblicza tego podczas tworzenia obiektu blob przy użyciu umieść listę bloków. Wartość można jawnie ustawić podczas tworzenia obiektu blob lub wywołując operacje umieszczania listy bloków lub ustaw właściwości obiektu blob.

W przypadku wersji z wersji 2009-09-19 i nowszych, ale przed wersją 2015-02-21 nie można wywołać List Blobs w kontenerze zawierającym uzupełnialne obiekty blob. Usługa zwraca kod stanu 409 (konflikt), jeśli wynik listy zawiera uzupełnialne obiekty blob.

LeaseState i LeaseDuration są wyświetlane tylko w wersji 2012-02-12 lub nowszej.

CopyId, CopyStatus, CopySource, CopyProgress, CopyCompletionTimei CopyStatusDescription są wyświetlane tylko w wersji 2012-02-12 lub nowszej, gdy ta operacja zawiera parametr include={copy}. Te elementy nie są wyświetlane, jeśli ten obiekt blob nigdy nie był miejscem docelowym w operacji Copy Blob. Elementy nie są wyświetlane, jeśli ten obiekt blob został zmodyfikowany po zakończeniu operacji Copy Blob przy użyciu Set Blob Properties, Put Bloblub Put Block List. Te elementy nie są również wyświetlane z obiektem blob utworzonym przez copy blob, przed wersją 2012-02-12.

W wersji 2013-08-15 lub nowszej element EnumerationResults zawiera atrybut ServiceEndpoint określający punkt końcowy obiektu blob. Ten element zawiera również pole ContainerName, które określa nazwę kontenera. W poprzednich wersjach te dwa atrybuty zostały połączone razem w polu ContainerName. Ponadto w wersji 2013-08-15 lub nowszej element Url w obszarze Blob został usunięty.

W przypadku wersji 2015-02-21 lub nowszej List Blobs zwraca obiekty blob wszystkich typów (blokowe, stronicowe i uzupełnialne obiekty blob).

W przypadku wersji 2015-12-11 lub nowszej List Blobs zwraca element ServerEncrypted. Ten element jest ustawiony na true, jeśli metadane obiektu blob i aplikacji są całkowicie zaszyfrowane, a false w przeciwnym razie.

W przypadku wersji 2016-05-31 lub nowszej program List Blobs zwraca element IncrementalCopy dla przyrostowych kopii obiektów blob i migawek z wartością ustawioną na true.

W przypadku wersji 2017-04-17 lub nowszej List Blobs zwraca element AccessTier, jeśli warstwa dostępu została jawnie ustawiona. Aby uzyskać listę dozwolonych warstw stronicowych obiektów blob w warstwie Premium, zobacz Magazyn Premium o wysokiej wydajności i dyski zarządzane dla maszyn wirtualnych. W przypadku kont usługi Blob Storage lub ogólnego przeznaczenia w wersji 2 prawidłowe wartości to Hot, Cooli Archive. Jeśli obiekt blob znajduje się w stanie oczekiwania na ponowne wypełnianie, element ArchiveStatus jest zwracany z jedną z prawidłowych wartości (rehydrate-pending-to-hot, rehydrate-pending-to-coollub rehydrate-pending-to-cold). Aby uzyskać szczegółowe informacje na temat warstw blokowych obiektów blob, zobacz Warstwy magazynowania Gorąca, Chłodna i Archiwum.

W przypadku wersji 2017-04-17 lub nowszej program List Blobs zwraca element AccessTierInferred na kontach usługi Blob Storage lub konta ogólnego przeznaczenia w wersji 2. Jeśli blokowy obiekt blob nie ma ustawionej warstwy dostępu, informacje o warstwie są wnioskowane z właściwości konta magazynu, a ta wartość jest ustawiona na wartość true. Ten nagłówek jest obecny tylko wtedy, gdy warstwa jest wnioskowana z właściwości konta.

W przypadku wersji 2017-04-17 lub nowszej program List Blobs zwraca element AccessTierChangeTime na kontach usługi Blob Storage lub konta ogólnego przeznaczenia w wersji 2. Jest to zwracane tylko wtedy, gdy warstwa blokowego obiektu blob kiedykolwiek została ustawiona. Aby uzyskać więcej informacji, zobacz Reprezentacja wartości daty i godziny w nagłówkach.

W przypadku wersji 2017-07-29 lub nowszej Deleted, DeletedTimei RemainingRetentionDays są wyświetlane, gdy ta operacja zawiera parametr include={deleted}. Te elementy nie są wyświetlane, jeśli ten obiekt blob nie został usunięty. Te elementy są wyświetlane dla obiektów blob lub migawek usuniętych za pomocą operacji DELETE po włączeniu funkcji usuwania nietrwałego. Element Deleted jest ustawiony na true dla obiektów blob i migawek, które są usuwane nietrwale. Deleted-Time odpowiada czasowi usunięcia obiektu blob. RemainingRetentionDays wskazuje liczbę dni, po których obiekt blob usunięty nietrwale zostanie trwale usunięty.

W przypadku wersji 2017-11-09 lub nowszej Creation-Time zwraca czas utworzenia tego obiektu blob.

W przypadku wersji 2019-02-02 i nowszych List Blobs zwraca element CustomerProvidedKeySha256, jeśli obiekt blob jest zaszyfrowany przy użyciu klucza dostarczonego przez klienta. Wartość zostanie ustawiona na skrót SHA-256 klucza używanego do szyfrowania obiektu blob. Ponadto jeśli operacja zawiera parametr include={metadata}, a metadane aplikacji znajdują się w obiekcie blob zaszyfrowanym przy użyciu klucza dostarczonego przez klienta, element Metadata będzie miał atrybut Encrypted="true". Ten atrybut wskazuje, że obiekt blob ma metadane, których nie można odszyfrować w ramach operacji List Blobs. Aby uzyskać dostęp do metadanych tych obiektów blob, wywołaj metodę Pobierz właściwości obiektu blob lub pobierz metadane obiektów blob za pomocą klucza dostarczonego przez klienta.

W przypadku wersji 2019-02-02 i nowszych List Blobs zwraca element EncryptionScope, jeśli obiekt blob jest zaszyfrowany z zakresem szyfrowania. Wartość zostanie ustawiona na nazwę zakresu szyfrowania używanego do szyfrowania obiektu blob. Jeśli operacja zawiera parametr include={metadata}, metadane aplikacji w obiekcie blob są niewidocznie odszyfrowywane i dostępne w elemecie Metadata.

W przypadku wersji 2019-12-12 i nowszych List Blobs zwraca element RehydratePriority na kontach usługi Blob Storage lub ogólnego przeznaczenia w wersji 2, jeśli obiekt jest w stanie rehydrate pending. Prawidłowe wartości to High i Standard.

W przypadku wersji 2019-12-12 i nowszych List Blobs zwraca element VersionId dla obiektów blob i wygenerowanych wersji obiektów blob, gdy przechowywanie wersji jest włączone na koncie.

W przypadku wersji 2019-12-12 i nowszych List Blobs zwraca element IsCurrentVersion dla bieżącej wersji obiektu blob. Wartość jest ustawiona na wartość true. Ten element umożliwia odróżnienie bieżącej wersji od wersji tylko do odczytu, automatycznie generowanych wersji.

W przypadku wersji 2019-12-12 i nowszych List Blobs zwraca element TagCount dla obiektów blob z dowolnymi tagami. Element Tags jest wyświetlany tylko wtedy, gdy ta operacja zawiera parametr include={tags}. Te elementy nie są wyświetlane, jeśli w obiekcie blob nie ma tagów.

W przypadku wersji 2019-12-12 i nowszych List Blobs zwraca element Sealed dla uzupełnialnych obiektów blob. Element Sealed jest wyświetlany tylko wtedy, gdy dołączany obiekt blob został zapieczętowany. Te elementy nie są wyświetlane, jeśli uzupełnialne obiekty blob nie są zapieczętowane.

W przypadku wersji 2020-02-10 lub nowszej List Blobs zwraca element LastAccessTime. Element pokazuje, kiedy dane obiektu blob były ostatnio używane, zgodnie z zasadami śledzenia czasu ostatniego dostępu konta magazynu. Element nie jest zwracany, jeśli konto magazynu nie ma tych zasad lub zasady są wyłączone. Aby uzyskać informacje o ustawianiu zasad śledzenia czasu ostatniego dostępu konta, zobacz Interfejs API usługi Blob Service. Element LastAccessTime nie śledzi ostatniego czasu uzyskiwania dostępu do metadanych obiektu blob.

W przypadku wersji 2020-06-12 lub nowszej List Blobs zwraca elementy ImmutabilityPolicyUntilDate i ImmutabilityPolicyMode, gdy ta operacja zawiera parametr include={immutabilitypolicy}.

W przypadku wersji 2020-06-12 lub nowszej List Blobs zwraca element LegalHold, gdy ta operacja zawiera parametr include={legalhold}.

W przypadku wersji 2020-06-12 i nowszych dla kont z włączoną hierarchiczną przestrzenią nazw program List Blobs zwraca elementy Owner, Group, Permissionsi Acl. Żądanie musi zawierać parametr include={permissions}. Należy pamiętać, że element Acl jest połączoną listą dostępu i domyślnych list kontroli dostępu, które zostały ustawione w pliku lub katalogu.

W przypadku wersji 2020-06-12 i nowszych dla kont z włączoną hierarchiczną przestrzenią nazw List Blobs z ogranicznikiem zwraca element Properties w elemecie BlobPrefix. Odpowiada to właściwościom w katalogu.

W przypadku wersji 2020-08-04 i nowszych dla kont z włączoną hierarchiczną przestrzenią nazw List Blobs zwraca element DeletionId dla usuniętych obiektów blob. DeletionId jest niepodpisanym, 64-bitowym identyfikatorem. Element jednoznacznie identyfikuje ścieżkę nietrwałą, aby odróżnić ją od innych usuniętych obiektów blob przy użyciu tej samej ścieżki.

W przypadku wersji 2020-10-02 lub nowszej dla kont z włączoną hierarchiczną przestrzenią nazw List Blobs zwraca element właściwości ResourceType dla ścieżki. Może to być file lub directory.

W przypadku wersji 2021-02-12 lub nowszej List Blobs będą kodowane procentowo (na RFC 2396) wszystkie wartości elementów BlobName lub BlobPrefixName. W szczególności zrobi to dla tych wartości, które zawierają znaki, które nie są prawidłowe w formacie XML (U+FFFE lub U+FFFF). W przypadku kodowania element Name będzie zawierać atrybut Encoded=true. Należy pamiętać, że dotyczy to tylko wartości elementu Name zawierającego znaki nieprawidłowe w kodzie XML, a nie pozostałych elementów Name w odpowiedzi.

W przypadku wersji 2021-06-08 lub nowszej dla kont z włączoną hierarchiczną przestrzenią nazw List Blobs zwraca element właściwości Placeholder. Zwraca ten element w elemecie BlobPrefix dla katalogów zastępczych podczas wyświetlania listy usuniętych obiektów blob z ogranicznikiem. Te katalogi zastępcze istnieją, aby ułatwić nawigację do nietrwałych obiektów blob.

W przypadku wersji 2021-06-08 lub nowszej dla kont z włączoną hierarchiczną przestrzenią nazw List Blobs zwraca element EncryptionContext. Jeśli wartość właściwości kontekstu szyfrowania zostanie ustawiona, zwróci ustawioną wartość.

W przypadku wersji 2020-02-10 i nowszych dla kont z włączoną hierarchiczną przestrzenią nazw List Blobs zwraca element Expiry-Time dla usuniętych obiektów blob. Expiry-Time to czas wygaśnięcia pliku i jest zwracany dla pliku, jeśli wygaśnięcie jest ustawione na tym samym.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="http://myaccount.blob.core.windows.net/"  ContainerName="mycontainer">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Delimiter>string-value</Delimiter>  
  <Blobs>  
    <Blob>  
      <Name>blob-name</Name>  
      <Snapshot>date-time-value</Snapshot>  
      <VersionId>date-time-vlue</VersionId>
      <IsCurrentVersion>true</IsCurrentVersion>
      <Deleted>true</Deleted>
      <Properties> 
        <Creation-Time>date-time-value</Creation-Time>
        <Last-Modified>date-time-value</Last-Modified>  
        <Etag>etag</Etag>
        <Owner>owner user id</Owner>
        <Group>owning group id</Group>
        <Permissions>permission string</Permissions>
        <Acl>access control list</Acl>
        <ResourceType>file | directory</ResourceType>
        <Placeholder>true</Placeholder>
        <Content-Length>size-in-bytes</Content-Length>  
        <Content-Type>blob-content-type</Content-Type>  
        <Content-Encoding />  
        <Content-Language />  
        <Content-MD5 />  
        <Cache-Control />  
        <x-ms-blob-sequence-number>sequence-number</x-ms-blob-sequence-number>  
        <BlobType>BlockBlob|PageBlob|AppendBlob</BlobType>  
        <AccessTier>tier</AccessTier>  
        <LeaseStatus>locked|unlocked</LeaseStatus>  
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>  
        <LeaseDuration>infinite | fixed</LeaseDuration>  
        <CopyId>id</CopyId>  
        <CopyStatus>pending | success | aborted | failed </CopyStatus>  
        <CopySource>source url</CopySource>  
        <CopyProgress>bytes copied/bytes total</CopyProgress>  
        <CopyCompletionTime>datetime</CopyCompletionTime>  
        <CopyStatusDescription>error string</CopyStatusDescription>  
        <ServerEncrypted>true</ServerEncrypted> 
        <CustomerProvidedKeySha256>encryption-key-sha256</CustomerProvidedKeySha256>
        <EncryptionContext>encryption-context</EncryptionContext>
        <EncryptionScope>encryption-scope-name</EncryptionScope>
        <IncrementalCopy>true</IncrementalCopy>
        <AccessTierInferred>true</AccessTierInferred>
        <AccessTierChangeTime>datetime</AccessTierChangeTime>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
        <TagCount>number of tags between 1 to 10</TagCount>
        <RehydratePriority>rehydrate priority</RehydratePriority>
        <Expiry-Time>date-time-value</Expiry-Time>
      </Properties>  
      <Metadata>     
        <Name>value</Name>  
      </Metadata>  
      <Tags>
          <TagSet>
              <Tag>
                  <Key>TagName</Key>
                  <Value>TagValue</Value>
              </Tag>
          </TagSet>
      </Tags>
      <OrMetadata />
    </Blob>  
    <BlobPrefix>  
      <Name>blob-prefix</Name>  
    </BlobPrefix>  
  </Blobs>  
  <NextMarker />  
</EnumerationResults>

Przykładowa odpowiedź

Zobacz Wyliczanie zasobów obiektów blob, aby uzyskać przykładową odpowiedź.

Autoryzacja

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

Ważny

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

Usługa Azure Storage obsługuje używanie identyfikatora Entra firmy Microsoft do autoryzowania żądań do danych obiektów blob. Za pomocą identyfikatora Entra firmy Microsoft 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 identyfikator entra firmy Microsoft 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 o autoryzacji przy użyciu identyfikatora Entra firmy Microsoft, zobacz Autoryzowanie dostępu do obiektów blob przy użyciu identyfikatora Entra firmy Microsoft.

Uprawnienia

Poniżej wymieniono akcję RBAC niezbędną dla użytkownika microsoft Entra, grupy, tożsamości zarządzanej lub jednostki usługi w celu wywołania operacji List Blobs oraz najmniej uprzywilejowanej wbudowanej roli RBAC platformy Azure, która obejmuje tę akcję:

W przypadku określania include=tags:

Aby dowiedzieć się więcej na temat przypisywania ról przy użyciu kontroli dostępu opartej na rolach platformy Azure, zobacz Assign an Azure role for access to blob data.

Uwagi

Właściwości obiektu blob w odpowiedzi

Jeśli zażądano, aby niezatwierdzone obiekty blob zostały uwzględnione w wyliczenie, pamiętaj, że niektóre właściwości nie są ustawione do momentu zatwierdzenia obiektu blob. Niektóre właściwości mogą nie zostać zwrócone w odpowiedzi.

Element x-ms-blob-sequence-number jest zwracany tylko dla stronicowych obiektów blob.

Element OrMetadata jest zwracany tylko dla blokowych obiektów blob.

W przypadku stronicowych obiektów blob wartość zwrócona w elemektorze Content-Length odpowiada wartości nagłówka x-ms-blob-content-length obiektu blob.

Element Content-MD5 pojawia się w treści odpowiedzi, tylko wtedy, gdy został on ustawiony w obiekcie blob przy użyciu wersji 2009-09-19 lub nowszej. Właściwość Content-MD5 można ustawić podczas tworzenia obiektu blob lub wywołując polecenie Ustaw właściwości obiektu blob. W wersji 2012-02-12 lub nowszej Put Blob ustawia wartość MD5 blokowego obiektu blob, nawet jeśli żądanie Put Blob nie zawiera nagłówka MD5.

Metadane w odpowiedzi

Element Metadata jest obecny tylko wtedy, gdy parametr include=metadata został określony w identyfikatorze URI. W ramach elementu Metadata wartość każdej pary nazwa-wartość jest wyświetlana w elemecie odpowiadającym nazwie pary.

Należy pamiętać, że metadane żądane za pomocą tego parametru muszą być przechowywane zgodnie z ograniczeniami nazewnictwa narzuconymi przez 2009-09-19 usługi Blob Storage. Począwszy od tej wersji, wszystkie nazwy metadanych muszą być zgodne z konwencjami nazewnictwa identyfikatorów języka C#.

Jeśli para nazwa-wartość metadanych narusza te ograniczenia nazewnictwa, treść odpowiedzi wskazuje problematyczną nazwę w elemecie x-ms-invalid-name. Poniższy fragment XML przedstawia następujący kod:

  
…  
<Metadata>  
  <MyMetadata1>first value</MyMetadata1>  
  <MyMetadata2>second value</MyMetadata2>  
  <x-ms-invalid-name>invalid-metadata-name</x-ms-invalid-name>  
</Metadata>  
…

Tagi w odpowiedzi

Element Tags jest obecny tylko wtedy, gdy parametr include=tags został określony w identyfikatorze URI i jeśli istnieją tagi w obiekcie blob. W elemecie TagSet jest zwracanych maksymalnie 10 Tag elementów, z których każdy zawiera key i value tagów indeksu obiektów blob zdefiniowanych przez użytkownika. Kolejność tagów nie jest gwarantowana w odpowiedzi.

Elementy Tags i TagCount nie są zwracane, jeśli w obiekcie blob nie ma tagów.

Usługa magazynu utrzymuje silną spójność między obiektem blob a jego tagami, ale indeks pomocniczy jest ostatecznie spójny. Tagi mogą być widoczne w odpowiedzi na List Blobs, zanim będą widoczne dla Find Blobs by Tags operacji.

Migawki w odpowiedzi

Migawki są wyświetlane w odpowiedzi tylko wtedy, gdy parametr include=snapshots został określony w identyfikatorze URI. Migawki wymienione w odpowiedzi nie zawierają elementu LeaseStatus, ponieważ migawki nie mogą mieć aktywnych dzierżaw.

Korzystając z usługi w wersji 2021-06-08 lub nowszej, możesz wywołać List Blobs z ogranicznikiem i dołączyć migawki do wyliczenia. W przypadku wersji usług wcześniejszych niż 2021-06-08 żądanie, które zawiera oba, zwraca błąd InvalidQueryParameter (kod stanu HTTP 400 — nieprawidłowe żądanie).

Niezatwierdzone obiekty blob w odpowiedzi

Niezatwierdzone obiekty blob są wyświetlane w odpowiedzi tylko wtedy, gdy parametr include=uncommittedblobs został określony w identyfikatorze URI. Niezatwierdzone obiekty blob wymienione w odpowiedzi nie zawierają żadnego z następujących elementów:

  • Last-Modified

  • Etag

  • Content-Type

  • Content-Encoding

  • Content-Language

  • Content-MD5

  • Cache-Control

  • Metadata

Usunięte obiekty blob w odpowiedzi

Usunięte obiekty blob są wyświetlane w odpowiedzi tylko wtedy, gdy parametr include=deleted został określony w identyfikatorze URI. Usunięte obiekty blob wymienione w odpowiedzi nie zawierają elementów Dzierżawa, ponieważ usunięte obiekty blob nie mogą mieć aktywnych dzierżaw.

Usunięte migawki są uwzględniane w odpowiedzi na listę, jeśli include=deleted,snapshot został określony w identyfikatorze URI.

Metadane replikacji obiektów w odpowiedzi

Element OrMetadata jest obecny, gdy zasady replikacji obiektu zostały ocenione w obiekcie blob, a wywołanie List Blobs zostało wykonane przy użyciu wersji 2019-12-12 lub nowszej. W ramach elementu OrMetadata wartość każdej pary nazwa-wartość jest wyświetlana w elemecie odpowiadającym nazwie pary. Format nazwy to or-{policy-id}_{rule-id}, gdzie {policy-id} jest identyfikatorem GUID reprezentującym identyfikator zasad replikacji obiektu na koncie magazynu. {rule-id} to identyfikator GUID reprezentujący identyfikator reguły w kontenerze magazynu. Prawidłowe wartości to complete i failed.

  
…  
<OrMetadata>  
  <or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>complete</or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>  
  <or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>failed</or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>  
</OrMetadata>  
…

Zasady niezmienności w odpowiedzi

Elementy ImmutabilityPolicyUntilDate i ImmutabilityPolicyMode są obecne tylko wtedy, gdy parametr include=immutabilitypolicy został określony w identyfikatorze URI.

<Properties> 
   <ImmutabilityPolicyUntilDate>date-time-value</ImmutabilityPolicyUntilDate>   
   <ImmutabilityPolicyMode>unlocked | locked </ImmutabilityPolicyMode>  
</Properties>

Element LegalHold jest obecny tylko wtedy, gdy parametr include=legalhold został określony w identyfikatorze URI.

<Properties> 
  <LegalHold>true | false </LegalHold>  
</Properties>

Zwracanie zestawów wyników przy użyciu wartości znacznika

Jeśli określisz wartość parametru maxresults, a liczba obiektów blob do zwrócenia przekroczy tę wartość lub przekroczy wartość domyślną dla maxresults, treść odpowiedzi zawiera element NextMarker. Ten element wskazuje następny obiekt blob do zwrócenia na kolejne żądanie. W niektórych przypadkach usługa może zwrócić element NextMarker, mimo że liczba zwróconych wyników jest mniejsza niż wartość maxresults.

Aby zwrócić następny zestaw elementów, określ wartość NextMarker jako parametr znacznika w identyfikatorze URI dla kolejnego żądania. Należy pamiętać, że wartość NextMarker powinna być traktowana jako nieprzezroczyste.

Używanie ogranicznika do przechodzenia przez przestrzeń nazw obiektów blob

Parametr delimiter umożliwia obiektowi wywołującym przechodzenie przez przestrzeń nazw obiektów blob przy użyciu ogranicznika skonfigurowanego przez użytkownika. W ten sposób można przejść przez wirtualną hierarchię obiektów blob tak, jakby był to system plików. Ogranicznik może być pojedynczym znakiem lub ciągiem.

Gdy żądanie zawiera ten parametr, operacja zwraca element BlobPrefix. Element BlobPrefix jest zwracany zamiast wszystkich obiektów blob z nazwami rozpoczynającymi się od tego samego podciągu, aż do wyglądu znaku ogranicznika. Wartość elementu BlobPrefix to podciąg i ogranicznik, gdzie podciąg jest typowym podciągem rozpoczynającym co najmniej jedną nazwę obiektu blob, a ogranicznik jest wartością parametru delimiter.

Możesz użyć wartości BlobPrefix, aby wykonać kolejne wywołanie, aby wyświetlić listę obiektów blob rozpoczynających się od tego prefiksu. W tym celu należy określić wartość BlobPrefix parametru prefix w identyfikatorze URI żądania.

Należy pamiętać, że każdy element BlobPrefix zwracany jest zliczany do maksymalnego wyniku, podobnie jak każdy element Blob.

Obiekty blob są wymienione w kolejności alfabetycznej w treści odpowiedzi, z wielkimi literami wymienionymi najpierw.

Błędy kopiowania w opisie stanu kopiowania

CopyStatusDescription zawiera więcej informacji na temat błędu Copy Blob.

  • Gdy próba kopiowania nie powiedzie się, CopyStatus jest ustawiona na pending, jeśli usługa Blob Storage nadal ponawia próbę wykonania operacji. Tekst CopyStatusDescription opisuje błąd, który mógł wystąpić podczas ostatniej próby kopiowania.

  • Gdy CopyStatus jest ustawiona na failed, tekst CopyStatusDescription opisuje błąd, który spowodował niepowodzenie operacji kopiowania.

W poniższej tabeli opisano pola każdej wartości CopyStatusDescription.

Składnik Opis
Kod stanu HTTP Standardowa trzycyfrowa liczba całkowita określająca błąd.
Kod błędu Słowo kluczowe opisujące błąd. Jest on udostępniany przez platformę Azure w elemecie <ErrorCode>. Jeśli nie zostanie wyświetlony element <ErrorCode>, usługa zwraca słowo kluczowe zawierające standardowy tekst błędu skojarzony z trzycyfrowym kodem stanu HTTP w specyfikacji HTTP. Aby uzyskać więcej informacji, zobacz typowe kody błędów interfejsu API REST.
Informacja Szczegółowy opis błędu w cudzysłowie.

W poniższej tabeli opisano wartości CopyStatus i CopyStatusDescription typowych scenariuszy awarii.

Ważny

Tekst opisu przedstawiony tutaj może ulec zmianie bez ostrzeżenia, nawet bez zmiany wersji. Nie polegaj na dopasowywaniu tego dokładnego tekstu.

Scenariusz Kopiuj wartość stanu Kopiuj wartość opis stanu
Operacja kopiowania została ukończona pomyślnie. sukces pusty
Użytkownik przerwał operację kopiowania przed jej ukończeniem. Przerwane pusty
Wystąpił błąd podczas odczytu ze źródłowego obiektu blob podczas operacji kopiowania. Operacja zostanie ponowiona. Oczekujące 502 BadGateway "Napotkano błąd z możliwością ponawiania próby podczas odczytywania źródła. Ponów próbę. Czas niepowodzenia: <czas>"
Wystąpił błąd podczas zapisywania docelowego obiektu blob operacji kopiowania. Operacja zostanie ponowiona. Oczekujące 500 InternalServerError "Napotkano błąd z możliwością ponowienia próby. Ponów próbę. Czas niepowodzenia: <czas>"
Wystąpił nieodwracalny błąd podczas odczytywania ze źródłowego obiektu blob operacji kopiowania. Nie powiodło się 404 ResourceNotFound "Kopiowanie nie powiodło się podczas odczytywania źródła". Gdy usługa zgłasza ten błąd źródłowy, zwraca ResourceNotFound w elemecie <ErrorCode>. Jeśli w odpowiedzi nie pojawi się żaden element <ErrorCode>, zostanie wyświetlony standardowy ciąg reprezentujący stan HTTP, taki jak NotFound.
Limit czasu ograniczający wszystkie operacje kopiowania upłynął. (Obecnie okres przekroczenia limitu czasu wynosi dwa tygodnie). Nie powiodło się 500 OperationCancelled "Kopia przekroczyła maksymalny dozwolony czas".
Operacja kopiowania zbyt często nie powiodła się podczas odczytywania ze źródła i nie spełniała minimalnego współczynnika prób powodzenia. (Ten limit czasu uniemożliwia ponowienie próby bardzo słabego źródła w ciągu dwóch tygodni przed niepowodzeniem). Nie powiodło się 500 OperationCancelled "Kopiowanie nie powiodło się podczas odczytywania źródła".

Rozliczeń

Żądania cen 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 z 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 żądań List Blobs na podstawie typu konta magazynu:

Operacja Typ konta magazynu Kategoria rozliczeń
Wyświetlanie listy obiektów blob Blokowy obiekt blob w warstwie Premium
Standardowa ogólnego przeznaczenia, wersja 2
Standardowa ogólnego przeznaczenia, wersja 1		 Wyświetlanie listy i tworzenie operacji kontenera

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

Zobacz też

Kody stanu i błędów
kody błędów usługi Blob Storage