Udostępnij za pośrednictwem

Wyświetlanie listy kontenerów

  • Artykuł

Operacja List Containers zwraca listę kontenerów w ramach określonego konta magazynu.

Żądanie

Żądanie można skonstruować List Containers 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/?comp=list HTTP/1.1

Należy pamiętać, że identyfikator URI musi zawsze zawierać ukośnik (/), aby oddzielić nazwę hosta od ścieżki i fragmentów zapytania identyfikatora URI. W przypadku List Containers operacji część ścieżki identyfikatora URI jest pusta.

Żądanie 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?comp=list HTTP/1.1

Należy pamiętać, że emulowany magazyn obsługuje tylko rozmiary obiektów blob do 2 GiB.

Aby uzyskać więcej informacji, zobacz Use Azurite emulator for local Azure Storage development and Differences between the Storage emulator and Azure Storage services (Używanie emulatora usługi Azurite do lokalnego programowania w usłudze Azure Storage i różnic między emulatorem usługi Storage i usługami Azure Storage).

Parametry identyfikatora URI

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

Parametr Opis
prefix Opcjonalny. Filtruje wyniki, aby zwracać tylko kontenery o nazwie rozpoczynającej się od określonego prefiksu.
marker Opcjonalny. Wartość ciągu identyfikującą część listy kontenerów, które mają zostać zwrócone przy użyciu następnej operacji wyświetlania listy. Operacja zwraca NextMarker wartość w treści odpowiedzi, jeśli operacja wyświetlania listy nie zwróciła wszystkich kontenerów pozostałych do wyświetlenia na bieżącej stronie. Możesz użyć NextMarker wartości jako wartości parametru marker w kolejnym wywołaniu, aby zażądać następnej strony elementów listy.

Wartość znacznika jest nieprzezroczysta dla klienta.
maxresults Opcjonalny. Określa maksymalną liczbę kontenerów do zwrócenia. Jeśli żądanie nie określi maxresultswartości lub określa wartość większą niż 5000, serwer zwróci maksymalnie 5000 elementów.

Należy pamiętać, że jeśli operacja listy przekracza granicę partycji, usługa zwróci token kontynuacji na potrzeby pobierania pozostałych wyników. Z tego powodu istnieje możliwość, że usługa zwróci mniej wyników niż określona przez maxresults, lub wartość domyślną 5000.

Jeśli parametr jest ustawiony na wartość mniejszą lub równą zero, serwer zwraca kod stanu 400 (Nieprawidłowe żądanie).
include={metadata,deleted,system} Opcjonalny. Określa co najmniej jeden zestaw danych do uwzględnienia w odpowiedzi:

- metadata: Należy pamiętać, że metadane żądane za pomocą tego parametru muszą być przechowywane zgodnie z ograniczeniami nazewnictwa nałożonymi przez usługę 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#.
- deleted: wersja 2019-12-12 lub nowsza. Określa, że kontenery usunięte nietrwale powinny być uwzględnione w odpowiedzi.
- system: wersja 2020-10-02 lub nowsza. Określa, czy kontenery systemowe mają być uwzględnione w odpowiedzi. Uwzględnienie tej opcji spowoduje wyświetlenie listy kontenerów systemowych, takich jak $logs i $changefeed. Należy pamiętać, że zwrócone kontenery systemowe różnią się w zależności od tego, które funkcje usługi są włączone na koncie magazynu.
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ń. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji usług Azure Storage.
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.

Treść żądania

Brak.

Reakcja

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

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ź zawiera również dodatkowe, standardowe nagłówki HTTP. Wszystkie nagłówki standardowe są zgodne ze specyfikacją protokołu HTTP/1.1.

Nagłówek odpowiedzi Opis
Content-Type Standardowy nagłówek HTTP/1.1. 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 w wersji 2009-09-19 lub nowszej.
Date Wartość daty/godziny UTC wskazująca godzinę, w 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 x-ms-client-request-id nagłówka, jeśli jest obecna w żądaniu. Wartość wynosi co najwyżej 1024 widoczne znaki ASCII. x-ms-client-request-id Jeśli nagłówek nie znajduje się w żądaniu, ten nagłówek nie będzie obecny w odpowiedzi.

Treść odpowiedzi

Format treści odpowiedzi jest następujący.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.blob.core.windows.net">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Containers>  
    <Container>  
      <Name>container-name</Name>  
      <Version>container-version</Version>
      <Deleted>true</Deleted>
      <Properties>  
        <Last-Modified>date/time-value</Last-Modified>  
        <Etag>etag</Etag>  
        <LeaseStatus>locked | unlocked</LeaseStatus>  
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>  
        <LeaseDuration>infinite | fixed</LeaseDuration> 
        <PublicAccess>container | blob</PublicAccess>
        <HasImmutabilityPolicy>true | false</HasImmutabilityPolicy>
        <HasLegalHold>true | false</HasLegalHold>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
      </Properties>  
      <Metadata>  
        <metadata-name>value</metadata-name>  
      </Metadata>  
    </Container>  
  </Containers>  
  <NextMarker>marker-value</NextMarker>  
</EnumerationResults>

LeaseStatus, LeaseStatei LeaseDuration są wyświetlane tylko w wersji 2012-02-12 lub nowszej.

Począwszy od wersji 2013-08-15, AccountName zmieniono nazwę atrybutu EnumerationResults elementu na ServiceEndpoint. Element URL został również usunięty z Container elementu. W przypadku wersji wcześniejszych niż 2013-08-15 adres URL kontenera określony w polu nie zawiera parametru URLrestype=container . Jeśli ta wartość jest używana do wprowadzania kolejnych żądań względem wyliczonych kontenerów, pamiętaj o dołączeniu tego parametru, aby wskazać, że typ zasobu jest kontenerem.

PrefixElementy , Markeri MaxResults są obecne tylko w przypadku określenia ich identyfikatora URI. Element NextMarker ma wartość tylko wtedy, gdy wyniki listy nie zostaną ukończone.

Element Metadata jest obecny tylko wtedy, gdy określisz include=metadata parametr w identyfikatorze URI. Metadata W elemecie wartość każdej pary name-value jest wyświetlana w elemecie odpowiadającym nazwie pary.

Jeśli para nazwa-wartość metadanych narusza ograniczenia nazewnictwa wymuszone przez wersję 2009-09-19, 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>

Począwszy od wersji 2016-05-31, uprawnienia publiczne kontenera PublicAccess są udostępniane we właściwości . Wskazuje on, czy dane w kontenerze mogą być dostępne publicznie i poziom dostępu. Możliwe wartości to:

  • container: wskazuje pełny, publiczny dostęp do odczytu dla danych kontenera i obiektów blob. Klienci mogą wyliczać obiekty blob w kontenerze za pośrednictwem żądania anonimowego, ale nie mogą wyliczać kontenerów na koncie magazynu.
  • blob: wskazuje publiczny dostęp do odczytu dla obiektów blob. Dane obiektów blob w tym kontenerze można odczytywać za pośrednictwem żądania anonimowego, ale dane kontenera nie są dostępne. Klienci nie mogą wyliczać obiektów blob w kontenerze za pośrednictwem żądania anonimowego.

Jeśli ta właściwość nie zostanie określona w <properties> sekcji, kontener jest prywatny dla właściciela konta.

HasImmutabilityPolicy i HasLegalHold są wyświetlane tylko w wersji 2017-11-09 i nowszej. HasImmutabilityPolicy to, true jeśli kontener ma ustawione zasady niezmienności, a false w przeciwnym razie. HasLegalHold to, true jeśli kontener ma co najmniej jedną blokadę prawną, a false w przeciwnym razie.

Uwaga

Począwszy od wersji 2009-09-19, treść odpowiedzi dla List Containers zwraca czas ostatniej modyfikacji kontenera w elemecie o nazwie Last-Modified. W poprzednich wersjach ten element nosił nazwę LastModified.

VersionElementy , Deleted, DeletedTimei RemainingRetentiondays są wyświetlane tylko w wersji 2019-12-12 i nowszej, jeśli określisz deleted wartość parametru includezapytania . Te elementy są wyświetlane tylko wtedy, gdy kontener jest usuwany nietrwale i kwalifikuje się do przywrócenia. VersionElementy , Deleted, DeletedTimei RemainingRetentiondays są wyświetlane tylko w wersji 2019-12-12 i nowszej, jeśli usunięta wartość zostanie określona dla parametru include zapytania i jeśli kontener zostanie usunięty nietrwale i kwalifikuje się do przywrócenia.

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 Containers poniższym opisem.

Ważne

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

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

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

Uwagi

Jeśli określisz wartość parametru maxresults , a liczba kontenerów do zwrócenia przekroczy tę wartość lub przekroczy wartość domyślną dla maxresultsparametru , treść odpowiedzi będzie zawierać NextMarker element. (Jest to również nazywane tokenem kontynuacji).

NextMarker wskazuje następny kontener, który ma powrócić do kolejnego żądania. Aby zwrócić następny zestaw elementów, określ wartość NextMarker parametru marker w identyfikatorze URI dla kolejnego żądania. Należy pamiętać, że wartość NextMarker powinna być traktowana jako nieprzezroczyste.

Jeśli operacja wyświetlania listy przekroczy granicę partycji, usługa zwróci wartość elementu NextMarker pobierania pozostałych wyników z następnej partycji. Operacja wyświetlania listy, która obejmuje więcej niż jedną partycję, powoduje zwrócenie mniejszego zestawu elementów niż określono przez maxresultsparametr lub wartość domyślną 5000. Aplikacja powinna zawsze sprawdzać obecność NextMarker elementu podczas wykonywania operacji wyświetlania listy i odpowiednio go obsługiwać.

Kontenery są wymienione w kolejności alfabetycznej w treści odpowiedzi.

Operacja przekroczyła List Containers limit czasu po 30 sekundach.

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 Containers żądań na podstawie typu konta magazynu:

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

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

Przykładowe żądanie i odpowiedź

Poniższy przykładowy identyfikator URI żąda listy kontenerów dla konta, ustawiając maksymalne wyniki, które mają być zwracane dla początkowej operacji na trzy.

GET https://myaccount.blob.core.windows.net/?comp=list&maxresults=3 HTTP/1.1

Żądanie jest wysyłane z następującymi nagłówkami:

x-ms-version: 2016-05-31  
x-ms-date: Wed, 26 Oct 2016 22:08:44 GMT  
Authorization: SharedKey myaccount:CY1OP3O3jGFpYFbTCBimLn0Xov0vt0khH/D5Gy0fXvg=

Kod stanu i nagłówki odpowiedzi są zwracane w następujący sposób:

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Wed, 26 Oct 2016 22:08:54 GMT  
x-ms-version: 2016-05-31  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

Kod XML odpowiedzi dla tego żądania jest następujący. Należy pamiętać, że NextMarker element jest zgodny z zestawem kontenerów i zawiera nazwę następnego kontenera, który ma zostać zwrócony.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.blob.core.windows.net/">  
  <MaxResults>3</MaxResults>  
  <Containers>  
    <Container>  
      <Name>audio</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C6B1B2</Etag> 
        <PublicAccess>container</PublicAccess> 
      </Properties>  
    </Container>  
    <Container>  
      <Name>images</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C1EEEC</Etag>  
      </Properties>  
    </Container>  
    <Container>  
      <Name>textfiles</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7BACAC3</Etag>  
      </Properties>  
    </Container>  
  </Containers>  
  <NextMarker>video</NextMarker>  
</EnumerationResults>

Kolejna operacja listy określa znacznik identyfikatora URI żądania w następujący sposób. Zostanie zwrócony następny zestaw wyników, zaczynając od kontenera określonego przez znacznik.

https://myaccount.blob.core.windows.net/?comp=list&maxresults=3&marker=video

Zobacz też

Autoryzowanie żądań do usługi Azure Storage
Kody stanu i błędów
Kody błędów usługi Blob Storage
Wyliczanie zasobów obiektów blob
Korzystanie z emulatora usługi Azure Storage na potrzeby programowania i testowania
Ustawianie limitów czasu operacji usługi Blob Storage