Zum Auflisten der Objekte in einem Bucket senden Sie eine GET-Anfrage, die für einen Bucket gilt. Sie können auch Abfragestringparameter verwenden, um die Anfrage weiter einzugrenzen. Die Anfrage gibt die Liste der Objekte in einem XML-Dokument im Antworttext zurück. Objekte in der Liste werden lexikografisch nach Name geordnet.
Zum Auflisten der Objekte, die sich in einem Bucket befinden, benötigen Sie die Berechtigung READ
für den Bucket. Zum Auflisten der ACLs oder zum CORS eines Buckets benötigen Sie die Berechtigung FULL_CONTROL
.
Sie können die Liste der Objekte, die in einer GET-Bucket-Anfrage zurückgegeben werden, einschränken und organisieren. Verwenden Sie dazu den Abfragestringparameter delimiter
, marker
, max-keys
und prefix
.
Die XML API gibt keine Listen mit mehr als 1.000 Objekten zurück.
Abfragestringparameter
Parameter | Beschreibung | Erforderlich |
---|---|---|
delimiter |
Ein Zeichen oder mehrere Zeichen, das verwendet werden kann, um eine Liste von Objekten zu vereinfachen, die ein verzeichnisähnliches Benennungsschema verwenden. Kann in Verbindung mit prefix verwendet werden. |
Nein |
encoding-type |
Wenn die Einstellung auf url gesetzt ist, werden Objektnamen in der Antwort URL-codiert. |
Nein |
generation-marker |
Die Objektgenerierung, nach der Sie mit dem Auflisten von Objekten beginnen möchten. Wenn Sie das Generierungslabel verwenden, müssen Sie auch eine Markierung verwenden. | Nein |
marker |
Der Objektname, nach dem Sie mit dem Auflisten von Objekten beginnen möchten. Objekte, deren Namen lexikografisch größer als marker sind, werden in der Objektliste zurückgegeben. |
Nein |
max-keys |
Die maximale Anzahl der Objekte, die bei einer Listenobjektanfrage zurückgegeben werden. | Nein |
prefix |
Ein String, mit dem die Anzahl der Objekte, die in einer GET-Bucket-Anfrage zurückgegeben werden, auf Nutzer beschränkt werden kann, deren Namen mit dem angegebenen Wert beginnen. Kann in Verbindung mit einem delimiter verwendet werden. |
Nein |
versions |
Bei Angabe in einem versionierten Bucket wird die Liste aller Objektversionen zurückgegeben. Ohne Angabe werden nur aktuelle Versionen aufgelistet. | Nein |
Informationen zu den Parametern, die Sie beim Erstellen und Verwenden signierter URLs angeben müssen, finden Sie unter Stringparameter für signierte URLs.
Anfrageheader
Siehe Allgemeine Anfrageheader.
Anfragetextelemente
Die Anfrage enthält kein XML-Dokument im Anfragetext.
Anfragesyntax
Die folgende Syntax gilt für GET-Bucket-Anfragen, die entweder keine oder einen oder mehrere der folgenden Elemente enthalten: delimiter
, generation-marker
, marker
, max-keys
, prefix
und versions
den Abfragestringparameter fest.
GET /?prefix=a_prefix&marker=a_marker&max-keys=max_number_of_keys&delimiter=a_delimiter HTTP/1.1 Host: BUCKET_NAME.storage.googleapis.com Date: DATE Content-Length: 0 Authorization: AUTHENTICATION_STRING
Antwortheader
Die Anfrage kann je nach verwendetem Anfrage-Header eine Vielzahl von Antwort-Headern zurückgeben.
Antworttextelemente
Die folgenden Antworttexttexte sind nur anwendbar, wenn Sie keinen Parameter oder mindestens eines derdelimiter
,generation-marker
,marker
,
max-keys
,prefix
oder aufversions
Abfragestringparameter zum Auflisten von Objekten in einem Bucket.
Element | Beschreibung |
---|---|
ListBucketResult |
Container für die angeforderten Objektinformationen |
Name |
Der Bucket-Name. |
CommonPrefixes |
Container für Präfixe, die die Einschränkungen von prefix und delimiter erfüllen Dieser Container wird nur verwendet, wenn Sie in der Anfrage eine delimiter angeben. Doppelte Einträge werden weggelassen. |
Delimiter |
Der delimiter , den Sie in der Anfrage angegeben haben. |
MaxKeys |
Der max-keys , den Sie in der Anfrage angegeben haben. |
Prefix |
Der prefix , den Sie in der Anfrage angegeben haben. |
GenerationMarker |
Der generation-marker , den Sie in der Anfrage angegeben haben. |
NextGenerationMarker |
Wenn die Liste der zurückgegebenen Objekte unvollständig ist und der Parameter versions verwendet wurde, stellt NextGenerationMarker die Generation des letzten Objekts bereit, das zurückgegeben wurde. Wenn die Liste bereits vollständig ist, wird NextGenerationMarker nicht zurückgegeben. |
Marker |
Der marker , den Sie in der Anfrage angegeben haben. |
NextMarker |
NextMarker gibt den Namen des letzten Objekts an, das zurückgegeben wurde. Der Wert von NextMarker kann im Abfragestringparameter marker in einem zukünftigen GET-Bucket-Aufruf angegeben werden, um den Bucket nach diesen Ergebnissen weiterhin aufzulisten. Wenn der Bucket, der dem letzten Objekt in der Liste folgt, keine weiteren Objekte enthält, wird NextMarker nicht zurückgegeben. |
IsTruncated |
Gibt an, ob alle Objekte in einem Bucket in der Liste angezeigt werden. Wenn max-keys kleiner als die Anzahl der Objekte in einem Bucket ist, lautet dieses Element "True". |
Contents |
Container für Objektinformationen, wenn der Abfrageparameter versions nicht verwendet wird. |
Version |
Container für Objektinformationen, wenn der Abfrageparameter versions verwendet wird. |
Key |
Der Name eines Objekts. |
Generation |
Die Generierung des Objekts. |
MetaGeneration |
Generierung der Metadaten des Objekts. |
IsLatest |
Wenn der Abfrageparameter versions angegeben ist, wird dieser Wert auf "true" gesetzt, wenn das Objekt derzeit online ist. Live bedeutet, dass dieses Objekt zurückgegeben wird, wenn das Objekt ohne Generierung angefordert wird. |
LastModified |
Datum und Uhrzeit der letzten Änderung der Objektmetadaten. |
DeletedTime |
Wenn der Abfrageparameter versions angegeben wurde, enthält das Datum und die Uhrzeit, zu der ein Objekt für nicht aktuelle Objekte ersetzt oder gelöscht wurde, sofern die Versionsverwaltung des Buckets aktiviert ist. |
ETag |
Ein HTTP 1.1-Entitäts-Tag für das Objekt. |
Size |
Größe des Objekts in Byte. |
KmsKeyName |
Der Name des KMS-Schlüssels zum Verschlüsseln des Objekts. Dieses Element ist nur vorhanden, wenn das Objekt mit vom Kunden verwalteten Verschlüsselungsschlüsseln verschlüsselt wird. |
Beispiele
Im folgenden Beispiel werden die Objekte in einem Bucket mit dem Namen travel-maps aufgelistet.
Anfrage
GET / HTTP/1.1 Host: travel-maps.storage.googleapis.com Date: Wed, 17 Feb 2010 15:31:56 GMT Content-Length: 0 Content-Type: text/plain Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Antwort
HTTP/1.1 200 OK Content-Length: 4061 Content-Type: application/xml Date: Wed, 17 Feb 2010 23:31:57 GMT Expires: Wed, 17 Feb 2010 23:31:57 GMT <?xml version='1.0' encoding='utf-8'?> <ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'> <Name>travel-maps</Name> <Prefix></Prefix> <Marker></Marker> <IsTruncated>false</IsTruncated> <Contents> <Key>europe/france/cannes.pdf</Key> <Generation>1360887759327000</Generation> <MetaGeneration>1</MetaGeneration> <LastModified>2010-02-17T22:11:12.487Z</LastModified> <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag> <Size>5061631</Size> </Contents> <Contents> <Key>europe/france/paris.pdf</Key> <Generation>1360887759329000</Generation> <MetaGeneration>1</MetaGeneration> <LastModified>2010-02-17T22:09:57.457Z</LastModified> <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag> <Size>5061631</Size> </Contents> </ListBucketResult>
Im folgenden Beispiel werden die Objekte in "Reisen" aufgelistet. Es wird aber auf 25 Objekte beschränkt, die mit dem Buchstaben "t" beginnen und nach "test" enden.
Anfrage
GET /?prefix=t&marker=test&max-keys=25 HTTP/1.1 Host: travel-maps.storage.googleapis.com Date: Mon, 16 Feb 2010 22:58:38 GMT Content-Length: 0 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Antwort
HTTP/1.1 200 OK Date: Mon, 15 Feb 2010 12:30:40 GMT Content-Length: 2705 Content-Type: application/xml <?xml version='1.0' encoding='utf-8'?> <ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'> <Name>travel-maps</Name> <Prefix>t</Prefix> <Marker>test</Marker> <MaxKeys>25</MaxKeys> <IsTruncated>false</IsTruncated> <Contents> <Key>test_a.jpg</Key> <Generation>1360887659329000</Generation> <MetaGeneration>1</MetaGeneration> <LastModified>2010-02-17T03:12:55.561Z</LastModified> <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag> <Size>328</Size> </Contents> <Contents> <Key>test_b.jpg</Key> <Generation>1360887659323000</Generation> <MetaGeneration>1</MetaGeneration> <LastModified>2010-02-17T03:12:54.606Z</LastModified> <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag> <Size>328</Size> </Contents> <Contents> <Key>test_c.jpg</Key> <LastModified>2010-02-17T03:12:53.734Z</LastModified> <ETag>"2281880ef78388266ecd7d4c1b472a0e"</ETag> <Size>328</Size> </Contents> </ListBucketResult>
Beispiel mit Präfix und Trennzeichen
Im folgenden Beispiel werden prefix
und delimiter
verwendet, um eine Liste von Objekten zurückzugeben, die mit einem verzeichnisähnlichen Schema benannt sind. Mit prefix=europe/
und delimiter=/
werden nur die Objekte im Verzeichnis europe/
zurückgegeben. Objekte, die sich in "Unterverzeichnissen" des europe-Verzeichnisses befinden, werden nicht aufgeführt, sondern Teil der Namen in den CommonPrefixes
-Elementen der Antwort. Im Beispiel wird davon ausgegangen, dass die folgenden Objekte in einem Bucket mit dem Namen travel-maps
enthalten sind:
- africa/ghana.jpg
- africa/egypt/kairo.jpg
- europe/finland.jpg
- europe/norway.jpg
- europe/france/paris.jpg
- europe/italien/rome.jpg
- europe/sweden/stockholm.jpg
- europe/sweden/stockholm/nordic_museum.jpg.
Die Beispielanfrage gibt ein XML-Dokument zurück, das die folgenden beiden Objekte im Element Contents
auflistet:
- europe/finland.jpg
- europe/norway.jpg
Die folgenden europe-Unterverzeichnisse sind im Element CommonPrefixes
aufgeführt:
- europe/france/
- europe/italien/
- europe/sweden/
Anfrage
GET /travel-maps?delimiter=/&prefix=europe/ HTTP/1.1 Host: storage.googleapis.com Date: Mon, 16 Feb 2010 22:58:38 GMT Content-Length: 0 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Antwort
HTTP/1.1 200 OK Date: Mon, 15 Feb 2010 12:30:40 GMT Content-Length: 1200 Content-Type: application/xml <?xml version="1.0"?> <ListBucketResult xmlns='http://doc.s3.amazonaws.com/2006-03-01'> <Name>mybucket</Name> <Prefix>europe/</Prefix> <Marker /> <IsTruncated>false</IsTruncated> <Contents> <Key>europe/finland.jpg</Key> <Generation>1360887659323000</Generation> <MetaGeneration>1</MetaGeneration> <LastModified>2010-02-17T03:12:55.561Z</LastModified> <ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag> <Size>10</Size> </Contents> <Contents> <Key>europe/norway.jpg</Key> <Generation>1360887659323000</Generation> <MetaGeneration>1</MetaGeneration> <LastModified>2010-02-17T03:12:55.561Z</LastModified> <ETag>"781e5e245d69b566979b86e28d23f2c7"</ETag> <Size>10</Size> </Contents> <CommonPrefixes> <Prefix>europe/france/</Prefix> </CommonPrefixes> <CommonPrefixes> <Prefix>europe/italy/</Prefix> </CommonPrefixes> <CommonPrefixes> <Prefix>europe/sweden/</Prefix> </CommonPrefixes> </ListBucketResult>