Objekte auflisten

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>