Wyświetlanie listy obiektów blob

Artykuł
02/03/2024

Operacja List Blobs zwraca listę obiektów blob w ramach określonego kontenera.

Żądanie

Żądanie można skonstruować List Blobs w następujący sposób. Zalecane jest użycie protokołu HTTPS. Zastąp ciąg 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 Azure Blob Storage port 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 (Używanie emulatora Azurite do lokalnego programowania w usłudze Azure Storage).

Parametry identyfikatora URI

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

Parametr	Opis
`prefix`	Opcjonalny. 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żna spróbować znaleźć obiekty blob o nazwie `readmefile.txt` przy użyciu ścieżki `folder1/folder2/readme/readmefile.txt`prefiksu . Jeśli którykolwiek podfolder zawiera plik o nazwie `readme`, zostanie wyświetlony błąd.
`delimiter`	Opcjonalny. Gdy żądanie zawiera ten parametr, operacja zwraca `BlobPrefix` element 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`	Opcjonalny. 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`	Opcjonalny. Określa maksymalną liczbę obiektów blob do zwrócenia, łącznie ze wszystkimi `BlobPrefix` elementami. Jeśli żądanie nie określi `maxresults`wartości lub określa wartość większą niż 5000, serwer zwróci do 5000 elementów. Jeśli zostaną zwrócone dodatkowe wyniki, usługa zwróci token kontynuacji w elemecie `NextMarker` odpowiedzi. 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}`	Opcjonalny. 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 mają być 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 funkcji Umieść listę zablokowanych, należy uwzględnić w odpowiedzi. - `copy`: Wersja 2012-02-12 lub nowsza. Określa, że metadane związane z dowolną bieżącą lub poprzednią `Copy Blob` operacją powinny być uwzględnione w odpowiedzi. -`deleted`: wersja 2017-07-29 lub nowsza. Określa, że obiekty blob usunięte nietrwale powinny być uwzględnione w odpowiedzi. -`tags`: wersja 2019-12-12 lub nowsza. Określa, że tagi indeksu obiektów blob zdefiniowane przez użytkownika powinny być uwzględniane 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, dopóki nie zostaną przetworzone przez odzyskiwanie pamięci. Użyj tagu `\<HasVersionsOnly\>`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ę ze względów prawnych obiektów blob. -`permissions`: wersja 2020-06-12 lub nowsza. Obsługiwane tylko w przypadku 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 zostaną uwzględnione 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}`	Opcjonalny. 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 obiektów blob usuniętych nietrwale. Jeśli `include=deleted` zostanie również określony, żądanie zakończy się niepowodzeniem z błędem Nieprawidłowe żądanie (400). -`files`:Opcjonalne. Wersja 2020-12-06 lub nowsza. Tylko dla kont z włączoną hierarchiczną przestrzenią nazw. Gdy żą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. Gdy żądanie zawiera ten parametr, lista zawiera tylko katalogi.
`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ń 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`	Opcjonalny. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB) rejestrowanym 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.
`x-ms-upn`	Opcjonalny. Prawidłowe tylko wtedy, gdy hierarchiczna przestrzeń nazw jest włączona dla konta i `include=permissions` jest podana w żądaniu. Jeśli `true`wartości tożsamości użytkownika zwrócone w <polach Właściciel>, <Grupa> i <Lista Acl> zostaną przekształcone z identyfikatorów obiektów Microsoft Entra na główne nazwy użytkowników. Jeśli `false`wartość jest zwracana jako Microsoft Entra identyfikatory obiektów. Wartość domyślna 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

Brak.

Przykładowe żądanie

Zobacz Wyliczanie zasobów obiektów blob dla przykładowego żądania.

Reakcja

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

Nagłówek odpowiedzi	Opis
`Content-Type`	Określa format, w którym są zwracane wyniki. Obecnie ta wartość to `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 uruchomienia żą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 dla żą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 im 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. `x-ms-client-request-id` Jeśli nagłówek nie istnieje 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 Prefixelementy , Marker, MaxResultsi Delimiter są obecne tylko wtedy, gdy zostały określone na identyfikatorze URI żądania. Element NextMarker ma wartość tylko wtedy, gdy wyniki listy nie zostaną ukończone.

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

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

Począwszy od wersji 2009-09-19, List Blobs zwraca następujące zmienione nazwy elementów 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 zostanie wyświetlony dla obiektów blob utworzonych w wersji 2009-09-19 lub nowszej. W wersji 2012-02-12 lub nowszej usługa Blob Storage oblicza Content-MD5 wartość podczas przekazywania obiektu blob przy użyciu polecenia Put Blob. Usługa Blob Storage nie oblicza tego podczas tworzenia obiektu blob przy użyciu funkcji Umieść listę bloków. Można jawnie ustawić Content-MD5 wartość podczas tworzenia obiektu blob lub wywołując operacje Umieść listę 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 kontenera zawierającego 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 i nowszych.

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

W wersji 2013-08-15 lub nowszej EnumerationResults element zawiera ServiceEndpoint atrybut określający punkt końcowy obiektu blob. Ten element zawiera ContainerName również pole określające nazwę kontenera. W poprzednich wersjach te dwa atrybuty zostały połączone razem w ContainerName polu. Ponadto w wersji 2013-08-15 lub nowszej element w Url 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 BlobsServerEncrypted zwraca element . Ten element jest ustawiany na true wartość , jeśli metadane obiektu blob i aplikacji są całkowicie szyfrowane i false w inny sposób.

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

W przypadku wersji 2017-04-17 lub nowszej AccessTier zwraca element, List Blobs jeśli jawnie ustawiono warstwę dostępu. 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, ArchiveStatus element 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 List BlobsAccessTierInferred zwraca element na kontach usługi Blob Storage lub 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 truewartość . 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 List BlobsAccessTierChangeTime zwraca element na kontach usługi Blob Storage lub 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, , DeletedTimei RemainingRetentionDays są wyświetlane, Deletedgdy ta operacja zawiera include={deleted} parametr . 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, które są usuwane z operacją DELETE , gdy funkcja usuwania nietrwałego została włączona. 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 lub nowszej CustomerProvidedKeySha256 zwraca element, List Blobs 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 include={metadata} parametr i istnieją metadane aplikacji obecne w obiekcie blob zaszyfrowanym kluczem dostarczonym przez klienta, Metadata element będzie miał Encrypted="true" atrybut . Ten atrybut wskazuje, że obiekt blob ma metadane, których nie można odszyfrować w ramach List Blobs operacji. Aby uzyskać dostęp do metadanych tych obiektów blob, wywołaj metodę Pobierz właściwości obiektu blob lub Pobierz metadane obiektu blob za pomocą klucza dostarczonego przez klienta.

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

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

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

W przypadku wersji 2019-12-12 lub nowszej List BlobsIsCurrentVersion zwraca element dla bieżącej wersji obiektu blob. Wartość jest ustawiona na truewartość . Ten element umożliwia odróżnienie bieżącej wersji od wersji tylko do odczytu, automatycznie generowanych wersji.

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

W przypadku wersji 2019-12-12 lub nowszej List BlobsSealed zwraca element dla uzupełnialnych obiektów blob. Element Sealed jest wyświetlany tylko wtedy, gdy uzupełniony 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 BlobsLastAccessTime zwraca element. 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 na temat ustawiania zasad śledzenia czasu ostatniego dostępu konta, zobacz interfejs API usługi Blob Service. Element LastAccessTime nie śledzi czasu ostatniego uzyskania dostępu do metadanych obiektu blob.

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

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

W przypadku wersji 2020-06-12 lub nowszej dla kont z włączoną List Blobs hierarchiczną przestrzenią nazw zwraca Ownerelementy , Group, Permissionsi Acl . Żądanie musi zawierać include={permissions} parametr. Należy pamiętać, że Acl element jest połączoną listą dostępu i domyślnymi listami kontroli dostępu ustawionymi w pliku lub katalogu.

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

W przypadku wersji 2020-08-04 i nowszej dla kont z włączoną List Blobs hierarchiczną przestrzenią nazw zwraca DeletionId element usuniętych obiektów blob. DeletionId jest niepodpisanym, 64-bitowym identyfikatorem. Element jednoznacznie identyfikuje ścieżkę usuwaną nietrwale, 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ą List Blobs hierarchiczną przestrzenią nazw zwraca ResourceType element właściwości ścieżki. Może to być wartość file lub directory.

W przypadku wersji 2021-02-12 lub nowszej List Blobs koduje procent (na RFC 2396) wszystkie BlobName wartości lub BlobPrefixName element. 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 Name element będzie zawierać Encoded=true atrybut. Należy pamiętać, że dzieje się tak tylko w przypadku Name wartości elementów zawierających znaki nieprawidłowe w formacie XML, a nie pozostałych Name elementów w odpowiedzi.

W przypadku wersji 2021-06-08 lub nowszej dla kont z włączoną List Blobs hierarchiczną przestrzenią nazw zwraca Placeholder element properties. Zwraca ten element w BlobPrefix elemecie 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 i nowszej dla kont z włączoną List Blobs hierarchiczną przestrzenią nazw zwraca EncryptionContext element. Jeśli wartość właściwości kontekstu szyfrowania zostanie ustawiona, zwróci ustawioną wartość.

W przypadku wersji 2020-02-10 lub nowszej dla kont z włączoną List Blobs hierarchiczną przestrzenią nazw zwraca Expiry-Time element 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ę zgodnie z List Blobs 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 List Blobs operacji przez użytkownika, grupę lub jednostkę usługi Microsoft Entra oraz najmniej uprzywilejowaną wbudowaną rolę RBAC platformy Azure, która obejmuje tę akcję:

Akcja RBAC platformy Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Rola wbudowana z najmniejszymi uprawnieniami:Czytelnik danych obiektów 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 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 List Blobs obsługuje trzy typy sygnatur dostępu współdzielonego: sygnatury dostępu współdzielonego delegowania użytkowników, 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 zabezpieczeniach. Jeśli projekt aplikacji wymaga sygnatur dostępu współdzielonego, użyj Microsoft Entra poświadczeń, aby utworzyć sygnaturę dostępu współdzielonego delegowania użytkownika, jeśli to możliwe.

Jeśli dostęp do klucza współdzielonego 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 Omówienie sposobu, w jaki zezwalanie na klucz udostępniony 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.

List Blobs Wywołanie operacji przy użyciu tokenu SYGNATURy dostępu współdzielonego delegowanego do zasobu kontenera wymaga uprawnienia Lista (l) w ramach tokenu sygnatury dostępu współdzielonego 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 za pomocą 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.

List Blobs Wywołanie operacji przy użyciu tokenu sygnatury dostępu współdzielonego delegowanego do zasobu kontenera wymaga uprawnienia Lista (l) w ramach tokenu sygnatury dostępu współdzielonego 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 użytkownika lub usługi są również dostępne za pośrednictwem sygnatury dostępu współdzielonego konta.

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

Operacja	Podpisana usługa	Podpisany typ zasobu	Podpisane uprawnienie
Wyświetlanie listy obiektów blob	Obiekt blob (b)	Kontener (c)	Lista (l)

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

Operacja List Blobs obsługuje autoryzację klucza współdzielonego. Autoryzowanie przy użyciu kluczy konta nie jest zalecane w przypadku większości scenariuszy, ponieważ jest mniej bezpieczne.

Firma Microsoft zaleca, aby zezwalać na autoryzację klucza współdzielonego dla konta magazynu, jeśli jest to możliwe. Aby uzyskać więcej informacji, zobacz Zapobieganie autoryzacji za pomocą klucza współdzielonego.

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, dopóki obiekt blob nie zostanie zatwierdzony. 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 Content-Length elemecie odpowiada wartości nagłówka x-ms-blob-content-length obiektu blob.

Element Content-MD5 jest wyświetlany w treści odpowiedzi tylko wtedy, gdy został ustawiony na obiekcie blob przy użyciu wersji 2009-09-19 lub nowszej. Właściwość można ustawić Content-MD5 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 Put Blob żądanie nie zawiera nagłówka MD5.

Metadane w odpowiedzi

Element Metadata jest obecny tylko wtedy, gdy include=metadata parametr został określony w identyfikatorze URI. Metadata W elemecie wartość każdej pary name-value 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 nałożonymi przez wersję usługi Blob Storage w wersji 2009-09-19. 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ę elementu x-ms-invalid-name . Poniższy fragment XML przedstawia następujące elementy:

  
…  
<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 include=tags parametr został określony w identyfikatorze URI i jeśli istnieją tagi w obiekcie blob. TagSet W elemecie jest zwracanych maksymalnie 10 Tag elementów, z których każdy zawiera key tagi i value indeksu obiektów blob zdefiniowanych przez użytkownika. Kolejność tagów nie jest gwarantowana w odpowiedzi.

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

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

Migawki w odpowiedzi

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

Korzystając z usługi w wersji 2021-06-08 i nowszej, można wywołać List Blobs z ogranicznikiem i dołączyć migawki do wyliczenia. W przypadku wersji usług wcześniejszych niż 2021-06-08 żądanie zawierające 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 include=uncommittedblobs parametr 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 include=deleted parametr został określony w identyfikatorze URI. Usunięte obiekty blob wymienione w odpowiedzi nie zawierają elementów dzierżawy , 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 określono identyfikator URI.

Metadane replikacji obiektów w odpowiedzi

Element OrMetadata jest obecny, gdy zasady replikacji obiektów zostały ocenione na obiekcie blob, a List Blobs wywołanie zostało wykonane przy użyciu wersji 2019-12-12 lub nowszej. OrMetadata W elemecie wartość każdej pary name-value 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 obiektów na koncie magazynu. {rule-id} to identyfikator GUID reprezentujący identyfikator reguły w kontenerze magazynu. Prawidłowe wartości to complete lub 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

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

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

Blokada prawna w odpowiedzi

Element LegalHold jest obecny tylko wtedy, gdy include=legalhold parametr 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ść parametrumaxresults, a liczba obiektów blob, które mają być zwracane, przekroczy tę wartość lub przekroczy wartość domyślną NextMarker parametru maxresults, treść odpowiedzi zawiera element. Ten element wskazuje następny obiekt blob, który ma powrócić do kolejnego żądania. W niektórych przypadkach usługa może zwrócić NextMarker element, mimo że liczba zwróconych wyników jest mniejsza niż wartość maxresults.

Aby zwrócić następny zestaw elementów, określ wartość NextMarker parametru 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ącego 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 BlobPrefix element. 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ść BlobPrefix elementu to podciąg i ogranicznik, gdzie podciąg jest typowym podciągem rozpoczynającym się co najmniej jedną nazwę obiektu blob, a ogranicznik jest wartością parametru delimiter .

Możesz użyć wartości , BlobPrefix aby utworzyć 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 dla identyfikatora prefix URI żądania.

Należy pamiętać, że każdy BlobPrefix zwrócony element liczy się w kierunku maksymalnego wyniku, tak jak każdy Blob element.

Obiekty blob są wymienione w kolejności alfabetycznej w treści odpowiedzi, z wielkie litery wymienione jako pierwsze.

Błędy kopiowania w opisie stanu kopiowania

CopyStatusDescription zawiera więcej informacji o Copy Blob niepowodzeniu.

Gdy próba kopiowania nie powiedzie się, jest ustawiona na pending wartość , CopyStatus jeśli usługa Blob Storage nadal ponawia próbę wykonania operacji. W CopyStatusDescription tekście opisano błąd, który mógł wystąpić podczas ostatniej próby kopiowania.
Po CopyStatus ustawieniu wartości failedCopyStatusDescription tekst opisuje błąd, który spowodował niepowodzenie operacji kopiowania.

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

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 dostarczany przez platformę <Azure w elemecie ErrorCode> . Jeśli nie <zostanie wyświetlony element ErrorCode> , usługa zwróci 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.
Informacje	Szczegółowy opis błędu w cudzysłowie.

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

Ważne

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

Scenariusz	Wartość stanu kopiowania	Wartość opisu stanu kopiowania
Operacja kopiowania została zakończona pomyślnie.	powodzenie	puste
Użytkownik przerwał operację kopiowania przed jej ukończeniem.	Przerwane	puste
Wystąpił błąd podczas odczytywania źródłowego obiektu blob podczas operacji kopiowania. Zostanie podjęta ponowna próba wykonania operacji.	Oczekiwanie	502 BadGateway "Napotkano błąd możliwy do ponawiania podczas odczytywania źródła. Ponów próbę. Czas niepowodzenia: <czas>"
Wystąpił błąd podczas zapisywania do docelowego obiektu blob operacji kopiowania. Zostanie podjęta ponowna próba wykonania operacji.	Oczekiwanie	500 InternalServerError "Napotkano błąd z możliwością ponawiania prób. Ponów próbę. Czas niepowodzenia: <czas>"
Wystąpił nieodwracalny błąd podczas odczytywania ze źródłowego obiektu blob operacji kopiowania.	niepowodzenie	404 ResourceNotFound "Kopiowanie nie powiodło się podczas odczytywania źródła". Gdy usługa zgłasza ten podstawowy błąd, zwraca wartość `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`, .
Upłynął limit czasu ograniczający wszystkie operacje kopiowania. (Obecnie okres przekroczenia limitu czasu wynosi dwa tygodnie).	niepowodzenie	500 OperationCancelled "Kopia przekroczyła maksymalny dozwolony czas".
Operacja kopiowania nie powiodła się zbyt często podczas odczytywania ze źródła i nie spełniała minimalnego stosunku prób do sukcesów. (Ten limit czasu uniemożliwia ponowienie próby bardzo słabego źródła w ciągu dwóch tygodni przed niepowodzeniem).	niepowodzenie	500 OperationCancelled "Kopiowanie nie powiodło się podczas odczytywania źródła".

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 List Blobs żądań 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 Azure Blob Storage Cennik.

Zobacz też

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