Freigeben über

List Containers

  • Artikel

Der List Containers Vorgang gibt eine Liste der Container unter dem angegebenen Speicherkonto zurück.

Anforderung

Sie können die List Containers Anforderung wie folgt erstellen. HTTPS wird empfohlen. Ersetzen Sie myaccount durch den Namen Ihres Speicherkontos.

Methode Anforderungs-URI HTTP-Version
GET https://myaccount.blob.core.windows.net/?comp=list HTTP/1.1

Beachten Sie, dass der URI immer einen Schrägstrich (/) enthalten muss, um den Hostnamen vom Pfad- und Abfrageteil des URIs zu trennen. Beim List Containers-Vorgang ist der Pfadteil des URIs leer.

Emulierte Speicherdienstanforderung

Wenn Sie eine Anforderung an den emulierten Speicherdienst stellen, geben Sie den Emulatorhostnamen und Azure Blob Storage Port als 127.0.0.1:10000an, gefolgt vom Namen des emulierten Speicherkontos.

Methode Anforderungs-URI HTTP-Version
GET http://127.0.0.1:10000/devstoreaccount1?comp=list HTTP/1.1

Beachten Sie, dass emulierter Speicher nur Blobgrößen von bis zu 2 GiB unterstützt.

Weitere Informationen finden Sie unter Verwenden des Azurite-Emulators für die lokale Azure Storage-Entwicklung und Unterschiede zwischen dem Speicheremulator und den Azure Storage-Diensten.

URI-Parameter

Sie können die folgenden zusätzlichen Parameter für den Anforderungs-URI angeben.

Parameter BESCHREIBUNG
prefix Optional. Filtert die Ergebnisse, um nur Container mit einem Namen zurückzugeben, der mit dem angegebenen Präfix beginnt.
marker Optional. Ein Zeichenfolgenwert, der den Teil der Liste der Container angibt, die beim nächsten Listenvorgang zurückgegeben werden sollen. Der Vorgang gibt den NextMarker Wert innerhalb des Antworttexts zurück, wenn der Auflistungsvorgang nicht alle Container zurückgegeben hat, die auf der aktuellen Seite aufgeführt werden sollen. Sie können den NextMarker Wert als Wert für den marker Parameter in einem nachfolgenden Aufruf verwenden, um die nächste Seite der Listenelemente anzufordern.

Der Markerwert ist für den Client nicht transparent.
maxresults Optional. Gibt die maximale Anzahl von Containern an, die zurückgegeben werden sollen. Wenn die Anforderung nicht angibt maxresultsoder einen Wert größer als 5000 angibt, gibt der Server bis zu 5.000 Elemente zurück.

Beachten Sie, dass der Dienst ein Fortsetzungstoken zum Abrufen der restlichen Ergebnisse zurückgibt, wenn der Auflistungsvorgang eine Partitionsgrenze überschreitet. Aus diesem Grund ist es möglich, dass der Dienst weniger Ergebnisse zurückgibt, als durch maxresultsangegeben oder als der Standardwert 5000 angegeben ist.

Wenn der Parameter auf einen Wert kleiner oder gleich 0 festgelegt ist, gibt der Server status Code 400 (Ungültige Anforderung) zurück.
include={metadata,deleted,system} Optional. Gibt ein oder mehrere Datasets an, die in der Antwort eingeschlossen werden sollen:

- metadata: Mit diesem Parameter angeforderte Metadaten müssen gemäß den Benennungseinschränkungen gespeichert werden, die von der Version 2009-09-19 von Blob Storage festgelegt wurden. Ab dieser Version müssen alle Metadatennamen den Namenskonventionen für C#-Bezeichner entsprechen.
- deleted: Version 2019-12-12 und höher. Gibt an, dass vorläufig gelöschte Container in die Antwort eingeschlossen werden sollen.
- system: Version 2020-10-02 und höher. Gibt an, ob Systemcontainer in die Antwort einbezogen werden sollen. Wenn Sie diese Option einschließen, werden Systemcontainer wie $logs und $changefeedaufgelistet. Beachten Sie, dass die zurückgegebenen spezifischen Systemcontainer variieren, je nachdem, welche Dienstfeatures für das Speicherkonto aktiviert sind.
timeout Optional. Der timeout-Parameter wird in Sekunden angegeben. Weitere Informationen finden Sie unter Festlegen von Timeouts für Blob Storage-Vorgänge.

Anforderungsheader

In der folgenden Tabelle werden erforderliche und optionale Anforderungsheader beschrieben.

Anforderungsheader BESCHREIBUNG
Authorization Erforderlich. Gibt das Autorisierungsschema, den Kontonamen und die Signatur an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
Date oder x-ms-date Erforderlich. Gibt die koordinierte Weltzeit (Coordinated Universal Time, UTC) für die Anforderung an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
x-ms-version Erforderlich für alle autorisierten Anforderungen. Gibt die Version des für die Anforderung zu verwendenden Vorgangs an. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure-Speicherdienste.
x-ms-client-request-id Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (KiB) bereit, der in den Protokollen aufgezeichnet wird, wenn die Protokollierung konfiguriert ist. Es wird dringend empfohlen, diesen Header zu verwenden, um clientseitige Aktivitäten mit Anforderungen zu korrelieren, die der Server empfängt. Weitere Informationen finden Sie unter Überwachen Azure Blob Storage.

Anforderungstext

Keine.

Antwort

Die Antwort enthält den HTTP-Statuscode, einen Satz von Antwortheadern und einen Antworttext im XML-Format.

Statuscode

Bei einem erfolgreichen Vorgang wird der Statuscode 200 (OK) zurückgegeben. Informationen zu status Codes finden Sie unter Status- und Fehlercodes.

Antwortheader

Die Antwort für diesen Vorgang umfasst die folgenden Header. Die Antwort enthält auch zusätzliche HTTP-Standardheader. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Antwortheader BESCHREIBUNG
Content-Type HTTP/1.1-Standardheader. Gibt das Format an, in dem die Ergebnisse zurückgegeben werden. Derzeit ist application/xmldieser Wert .
x-ms-request-id Dieser Header identifiziert die durchgeführte Anforderung eindeutig und kann für die Problembehandlung der Anforderung verwendet werden. Weitere Informationen finden Sie unter Problembehandlung für API-Vorgänge.
x-ms-version Gibt die Version von Blob Storage an, die zum Ausführen der Anforderung verwendet wird. Dieser Header wird für Anforderungen zurückgegeben, die für Version 2009-09-19 und höher erfolgen.
Date Ein UTC-Datums-/Uhrzeitwert, der den Zeitpunkt angibt, zu dem die Antwort initiiert wurde. Der Dienst generiert diesen Wert.
x-ms-client-request-id Sie können diesen Header verwenden, um Probleme mit Anforderungen und entsprechenden Antworten zu beheben. Der Wert dieses Headers ist gleich dem Wert des x-ms-client-request-id Headers, wenn er in der Anforderung vorhanden ist. Der Wert beträgt höchstens 1024 sichtbare ASCII-Zeichen. Wenn der x-ms-client-request-id Header in der Anforderung nicht vorhanden ist, ist dieser Header in der Antwort nicht vorhanden.

Antworttext

Das Format des Antworttexts sieht wie folgt aus.

<?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, LeaseState und LeaseDuration werden nur in Version 2012-02-12 und höher angegeben.

Ab Version 2013-08-15 wurde das AccountName-Attribut für das EnumerationResults-Element in ServiceEndpoint umbenannt. Darüber hinaus wurde das URL-Element aus dem Container-Element entfernt. Bei Versionen vor 2013-08-15 enthält restype=container die URL des Containers, wie im URL Feld angegeben, den Parameter nicht. Wenn Sie diesen Wert verwenden, um nachfolgende Anforderungen für die aufgezählten Container auszuführen, fügen Sie diesen Parameter an, um anzugeben, dass die Ressource ein Container ist.

Die PrefixElemente , Markerund MaxResults sind nur vorhanden, wenn Sie sie für den URI angeben. Das NextMarker -Element hat nur dann einen Wert, wenn die Listenergebnisse nicht vollständig sind.

Das Metadata Element ist nur vorhanden, wenn Sie den include=metadata Parameter für den URI angeben. Im Metadata-Element wird der Wert jedes Name-Wert-Paars in einem Element aufgelistet, das dem Namen des Paars entspricht.

Wenn ein Metadatennamen-Wert-Paar gegen die Benennungseinschränkungen verstößt, die von der Version 2009-09-19 erzwungen werden, gibt der Antworttext den problematischen Namen innerhalb eines x-ms-invalid-name Elements an. Das folgende XML-Fragment zeigt dies:

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

Ab Version 2016-05-31 werden die öffentlichen Containerberechtigungen in der PublicAccess -Eigenschaft bereitgestellt. Es gibt an, ob öffentlich auf Daten im Container zugegriffen werden kann, und die Zugriffsebene. Mögliche Werte sind:

  • container: Gibt den vollständigen öffentlichen Lesezugriff für Container- und Blobdaten an. Clients können Blobs innerhalb des Containers über eine anonyme Anforderung aufzählen, aber keine Container innerhalb des Speicherkontos auflisten.
  • blob: Gibt öffentlichen Lesezugriff für Blobs an. Blobdaten in diesem Container können über eine anonyme Anforderung gelesen werden, aber Containerdaten sind nicht verfügbar. Clients können Blobs innerhalb des Containers nicht über eine anonyme Anforderung aufzählen.

Wenn diese Eigenschaft nicht im <properties> Abschnitt angegeben ist, ist der Container für den Kontobesitzer privat.

HasImmutabilityPolicy und HasLegalHold werden nur in Version 2017-11-09 und höher angezeigt. HasImmutabilityPolicy ist, wenn für den Container eine Unveränderlichkeitsrichtlinie festgelegt ist true , andernfalls false . HasLegalHold ist true , wenn der Container über einen oder mehrere gesetzliche Haltebereiche verfügt und false andernfalls.

Hinweis

Ab Version 2009-09-19 gibt der Antworttext für List Containers den Zeitpunkt der letzten Änderung des Containers in einem Element namens Last-Modifiedzurück. In früheren Versionen lautete der Name dieses Elements LastModified.

Die VersionElemente , Deleted, DeletedTimeund RemainingRetentiondays werden nur in Version 2019-12-12 und höher angezeigt, wenn Sie den deleted Wert für den Abfrageparameter includeangeben. Diese Elemente werden nur angezeigt, wenn der Container vorläufig gelöscht wurde und wiederhergestellt werden kann. Die VersionElemente , Deleted, DeletedTimeund RemainingRetentiondays werden nur in Version 2019-12-12 und höher angezeigt, wenn der gelöschte Wert für den include Abfrageparameter angegeben ist und der Container vorläufig gelöscht und wiederhergestellt werden kann.

Authorization

Beim Aufrufen eines Datenzugriffsvorgangs in Azure Storage ist eine Autorisierung erforderlich. Sie können den List Containers Vorgang wie unten beschrieben autorisieren.

Wichtig

Microsoft empfiehlt die Verwendung von Microsoft Entra ID mit verwalteten Identitäten, um Anforderungen an Azure Storage zu autorisieren. Microsoft Entra ID bietet im Vergleich zur Autorisierung mit gemeinsam genutzten Schlüsseln eine höhere Sicherheit und Benutzerfreundlichkeit.

Azure Storage unterstützt die Verwendung von Microsoft Entra ID zum Autorisieren von Anforderungen für Blobdaten. Mit Microsoft Entra ID können Sie die rollenbasierte Zugriffssteuerung von Azure (Azure RBAC) verwenden, um einem Sicherheitsprinzipal Berechtigungen zu erteilen. Der Sicherheitsprinzipal kann ein Benutzer, eine Gruppe, ein Anwendungsdienstprinzipal oder eine verwaltete Azure-Identität sein. Der Sicherheitsprinzipal wird von Microsoft Entra ID authentifiziert, um ein OAuth 2.0-Token zurückzugeben. Das Token kann anschließend zum Autorisieren einer Anforderung an den Blob-Dienst verwendet werden.

Weitere Informationen zur Autorisierung mit Microsoft Entra ID finden Sie unter Autorisieren des Zugriffs auf Blobs mithilfe von Microsoft Entra ID.

Berechtigungen

Nachfolgend sind die RBAC-Aktion aufgeführt, die für einen Microsoft Entra Benutzer, eine Gruppe, eine verwaltete Identität oder einen Dienstprinzipal erforderlich ist, um den List Containers Vorgang aufzurufen, und die integrierte Azure RBAC-Rolle mit den geringsten Berechtigungen, die diese Aktion enthält:

Weitere Informationen zum Zuweisen von Rollen mithilfe von Azure RBAC finden Sie unter Zuweisen einer Azure-Rolle für den Zugriff auf Blobdaten.

Hinweise

Wenn Sie einen Wert für den maxresults Parameter angeben und die Anzahl der zurückzugebenden Container diesen Wert überschreitet oder den Standardwert für maxresultsüberschreitet, enthält der Antworttext das NextMarker -Element. (Dies wird auch als Fortsetzungstoken bezeichnet.

NextMarker gibt den nächsten Container an, der bei einer nachfolgenden Anforderung zurückgegeben werden soll. Um den nächsten Satz von Elementen zurückzugeben, geben Sie den Wert von NextMarker für den marker Parameter für den URI für die nachfolgende Anforderung an. Beachten Sie, dass der Wert von NextMarker als nicht transparent behandelt werden muss.

Wenn der Auflistungsvorgang eine Partitionsgrenze überschreitet, gibt der Dienst einen Wert für das NextMarker Element zurück, um den Rest der Ergebnisse aus der nächsten Partition abzurufen. Ein Auflistungsvorgang, der sich über mehrere Partitionen erstreckt, führt dazu, dass ein kleinerer Satz von Elementen zurückgegeben wird, als durch maxresultsoder als der Standardwert 5000 angegeben wird. Ihre Anwendung sollte immer überprüfen, ob das NextMarker Element vorhanden ist, wenn Sie einen Listenvorgang ausführen, und ihn entsprechend behandeln.

Container werden im Antworttext in alphabetischer Reihenfolge aufgeführt.

Das Timeout des List Containers-Vorgangs beträgt 30 Sekunden.

Abrechnung

Preisanforderungen können von Clients stammen, die Blob Storage-APIs verwenden, entweder direkt über die Blob Storage-REST-API oder aus einer Azure Storage-Clientbibliothek. Für diese Anforderungen fallen Gebühren pro Transaktion an. Die Art der Transaktion wirkt sich auf die Abrechnung des Kontos aus. Beispielsweise werden Lesetransaktionen einer anderen Abrechnungskategorie zugeordnet als Schreibtransaktionen. Die folgende Tabelle zeigt die Abrechnungskategorie für List Containers Anforderungen basierend auf dem Speicherkontotyp:

Vorgang Speicherkontotyp Abrechnungskategorie
List Containers Premium, Blockblob
Standard „Allgemein v2“
Standard „Allgemein v1“		 Auflisten und Create von Containervorgängen

Informationen zu den Preisen für die angegebene Abrechnungskategorie finden Sie unter Azure Blob Storage Preise.

Beispielanforderung und -antwort

Der folgende Beispiel-URI fordert die Liste der Container für ein Konto an, wobei die maximalen Ergebnisse festgelegt werden, die für den ersten Vorgang auf drei zurückgegeben werden sollen.

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

Die Anforderung wird mit den folgenden Headern gesendet:

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

Der Statuscode und die Antwortheader werden wie folgt zurückgegeben:

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

Das Antwort-XML für diese Anforderung lautet wie folgt. Beachten Sie, dass das NextMarker Element der Gruppe von Containern folgt und den Namen des nächsten zurückzugebenden Containers enthält.

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

Der folgende Auflistungsvorgang gibt den Marker im Anforderungs-URI wie folgt an. Der nächste Satz von Ergebnissen wird zurückgegeben, beginnend mit dem container, der vom Marker angegeben wird.

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

Weitere Informationen

Autorisieren von Anforderungen an Azure Storage
Status- und Fehlercodes
Blob Storage-Fehlercodes
Auflisten von Blobressourcen
Verwenden des Azure Storage-Emulators für Entwicklung und Tests
Festlegen von Timeouts für Blob Storage-Vorgänge