Répertorier les objets

Pour répertorier les objets d'un bucket, vous exécutez une requête GET limitée à un bucket. Vous pouvez également utiliser des paramètres de chaîne de requête pour affiner davantage la requête. La requête renvoie la liste des objets dans un document XML dans le corps de la réponse, et les objets de la liste sont classés de façon lexicographiquement par nom.

Vous devez disposer de l'autorisation READ pour obtenir la liste des objets d'un bucket, et vous devez disposer de l'autorisation FULL_CONTROL sur le bucket pour répertorier les LCA ou le CORS d'un bucket.

Vous pouvez limiter et organiser la liste d'objets renvoyés dans une requête de bucket GET à l'aide des paramètres de chaîne de requête delimiter, marker, max-keys et prefix.

L'API XML ne renvoie pas de listes comportant plus de 1 000 objets.

Paramètres de la chaîne de requête

Paramètre Description Requis
delimiter Caractère ou plusieurs caractères pouvant être utilisés pour simplifier une liste d'objets utilisant un schéma de nommage semblable à un répertoire. Peut être utilisé conjointement avec une commande prefix. Non
encoding-type Lorsque ce paramètre est défini sur url, les noms d'objets sont encodés sous forme d'URL dans la réponse. Non
generation-marker Il s'agit de la génération d'objets à partir de laquelle vous souhaitez commencer à répertorier les objets. Si vous utilisez un marqueur de génération, vous devez également utiliser le marqueur. Non
marker Nom d'objet sur lequel vous souhaitez commencer à répertorier les objets. Les objets dont les noms sont lexicographiquement supérieurs à marker sont renvoyés dans la liste d'objets. Non
max-keys Nombre maximal d'objets à renvoyer dans une requête d'objet de liste. Non
prefix Chaîne permettant de limiter le nombre d'objets renvoyés dans une requête de bucket GET aux seuls noms dont les noms commencent par la valeur spécifiée. Peut être utilisé conjointement avec delimiter. Non
versions Si spécifié sur un bucket avec versions gérées, renvoie la liste de toutes les versions d'objet. Si cette option est omise, elle n'inclut que les versions actuelles. Non

Consultez la section Paramètres de la chaîne de requête d'URL signée pour en savoir plus sur les paramètres que vous incluez lors de la création et de l'utilisation d'URL signées.

En-têtes de requête

Voir les en-têtes de requêtes courants.

Éléments du corps de la requête

Cette requête n'inclut pas de document XML dans le corps de la requête.

Syntaxe des requêtes

La syntaxe suivante s'applique aux requêtes de bucket GET qui ne contiennent aucun paramètre, ou à un ou plusieurs des paramètres delimiter, generation-marker, marker, max-keys et prefix. et versions.

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

En-têtes de réponse

La requête peut renvoyer divers en-têtes de réponse en fonction des en-têtes de requête que vous utilisez.

Éléments du corps de la réponse

Les éléments de corps de réponse suivants ne s'appliquent que si vous n'utilisez aucun paramètre, ou un ou plusieurs des paramètres delimiter, generation-marker, marker, max-keys et prefix. } ou versions pour répertorier les objets d'un bucket.

Élément Description
ListBucketResult Conteneur des informations que vous demandez.
Name Nom du bucket.
CommonPrefixes Conteneur pour les préfixes qui respectent vos contraintes prefix et delimiter. Ce conteneur n'est utilisé que si vous spécifiez un delimiter dans la requête, et que les entrées en double sont omises.
Delimiter La valeur delimiter que vous avez spécifiée dans la requête.
MaxKeys La valeur max-keys que vous avez spécifiée dans la requête.
Prefix La valeur prefix que vous avez spécifiée dans la requête.
GenerationMarker La valeur generation-marker que vous avez spécifiée dans la requête.
NextGenerationMarker Si la liste des objets renvoyés est incomplète et que le paramètre versions a été utilisé, NextGenerationMarker fournit la génération du dernier objet renvoyé. Si la liste est déjà terminée, NextGenerationMarker n'est pas renvoyé.
Marker La valeur marker que vous avez spécifiée dans la requête.
NextMarker NextMarker fournit le nom du dernier objet qui a été renvoyé. La valeur de NextMarker peut être fournie dans le paramètre de chaîne de requête marker lors d'un prochain appel GET Bucket pour continuer à répertorier le bucket après cet ensemble de résultats. S'il n'y a plus d'objets dans le bucket qui suivent le dernier objet de la liste, NextMarker n'est pas renvoyé.
IsTruncated Indique si tous les objets d'un bucket apparaissent dans la liste. Si max-keys est inférieur au nombre d'objets dans un bucket, cet élément est vrai.
Contents Conteneur pour les informations relatives aux objets si le paramètre de requête versions n'est pas utilisé.
Version Conteneur pour les informations relatives aux objets si le paramètre de requête versions est utilisé.
Key Nom d'un objet.
Generation Génération de l'objet.
MetaGeneration Génération des métadonnées de l'objet.
IsLatest Si le paramètre de requête versions est spécifié, il est défini sur "true" si l'objet est actuellement actif. Cela signifie que si cet objet est demandé sans génération, cet objet est renvoyé.
LastModified Date et heure de la dernière modification des métadonnées de l'objet.
DeletedTime Si le paramètre de requête versions a été spécifié, contient la date et l'heure de remplacement ou de suppression d'un objet pour des objets obsolètes (si la gestion des versions est activée pour le bucket).
ETag Un tag d'entité HTTP 1.1 pour l'objet.
Size Taille de l'objet en octets.
KmsKeyName Nom de la clé KMS utilisée pour chiffrer l'objet. Cet élément n'est présent que si l'objet est chiffré avec des clés de chiffrement gérées par le client.

Exemples

L'exemple suivant répertorie les objets d'un bucket nommé travel-maps.

Requête

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

Réponse

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>

L'exemple suivant répertorie les objets sur maps-maps, mais limite la liste à 25 objets commençant par la lettre "t" et viennent après "test".

Requête

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

Réponse

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>

Exemple d'utilisation de préfixe et de délimiteur

L'exemple suivant utilise un objet prefix et un objet delimiter pour afficher une liste d'objets nommés à l'aide d'un schéma semblable à un répertoire. Si vous utilisez prefix=europe/ et delimiter=/, seuls les objets qui se trouvent dans le "répertoire" europe/ sont renvoyés. Les objets se trouvant dans des "sous-répertoires" du répertoire europe ne sont pas répertoriés, mais incluent la première partie de leurs noms dans les éléments CommonPrefixes de la réponse. L'exemple suppose que les objets suivants sont contenus dans un bucket nommé travel-maps:

  • africa/ghana.jpg
  • africa/egypt/cairo.jpg
  • europe/finland.jpg
  • europe/norway.jpg
  • europe/france/paris.jpg
  • europe/italy/rome.jpg
  • europe/sweden/stockholm.jpg
  • europe/sweden/stockholm/nordic_museum.jpg

L'exemple de requête renvoie un document XML qui répertorie les deux objets suivants dans l'élément Contents:

  • europe/finland.jpg
  • europe/norway.jpg

Les sous-répertoires europe suivants sont répertoriés dans l'élément CommonPrefixes:

  • europe/france/
  • europe/italy/
  • europe/sweden/

Requête

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

Réponse

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>