Présentation de l'API XML

Ce document présente l'API XML de Cloud Storage. Elle est destinée aux développeurs de logiciels. Nous partons ici du principe que vous maîtrisez les services RESTful et la programmation Web, et que vous maîtrisez la création d'applications capables d'effectuer des requêtes HTTP. Si cela ne vous concerne pas, envisagez l'une des solutions suivantes:

  • Si vous débutez avec Cloud Storage, commencez par essayer le guide de démarrage rapide de Cloud Console ou le guide de démarrage rapide de gsutil. Ces tutoriels illustrent les principes de base de l'utilisation de Cloud Storage sans avoir à utiliser directement l'API.

  • Si vous travaillez dans certains langages de programmation, vous pouvez utiliser les bibliothèques clientes Cloud Storage.

  • Si vous êtes un développeur d'applications mobiles ou Web, vous pouvez utiliser les SDK Firebase pour Cloud Storage.

  • Si vous n'êtes pas développeur logiciel et que vous souhaitez stocker vos données personnelles dans le cloud et les partager avec d'autres utilisateurs, vous pouvez utiliser Google Drive.

Présentation

L'API XML de Cloud Storage est une interface RESTful qui vous permet de gérer les données Cloud Storage de manière automatisée. En tant qu'API RESTful, il s'appuie sur les informations sur la méthode et sur la copie des informations pour définir les opérations à effectuer:

Vous utilisez des méthodes HTTP pour effectuer des opérations sur la ressource spécifiée dans le champ d'application. Pour obtenir la liste des opérations disponibles dans l'API XML, consultez la page Méthodes de requête de l'API XML.

L'accès à Cloud Storage via l'API XML est utile lorsque vous utilisez des outils et des bibliothèques qui doivent fonctionner avec différents fournisseurs de stockage, ou lorsque vous effectuez une migration d'un autre fournisseur de stockage vers Cloud Storage. Dans le cas du pipeline, il vous suffit d'apporter quelques modifications simples à vos outils et bibliothèques existants pour commencer à envoyer des requêtes à Cloud Storage. Pour plus d'informations sur la migration vers Cloud Storage, consultez la page Migrer depuis Amazon S3 vers Google Cloud Storage.

Requêtes

L'API XML de Cloud Storage fournit une interface Web pour effectuer des requêtes HTTP et gérer les réponses HTTP. L'API est compatible avec les protocoles HTTP/1.1, HTTP/2 et HTTP/3. Chaque requête met en œuvre une méthode HTTP standard. En plus de ces méthodes, vous pouvez utiliser divers en-têtes de requête HTTP.

Authentification

Toutes les requêtes adressées à Cloud Storage doivent être authentifiées, à l'exception des requêtes adressées à des objets ou buckets accessibles de manière anonyme. Pour obtenir des informations détaillées sur la définition des en-têtes d'autorisation pour les requêtes Cloud Storage, consultez la page Authentification.

Endpoints

La plupart des requêtes de l'API XML de Cloud Storage utilisent l'URI suivant pour accéder aux buckets et aux objets:

storage.googleapis.com

Vous pouvez affiner davantage ce champ en ajoutant un bucket et un objet à l'URI. L'URL obtenue peut prendre deux formes:

BUCKET_NAME.storage.googleapis.com/OBJECT_NAME
storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

Vous pouvez utiliser l'URI Cloud Storage avec des requêtes non sécurisées (HTTP) et sécurisées (HTTPS) utilisant le chiffrement SSL (Secure Sockets Layer).

Pour utiliser des points de terminaison supplémentaires, tels que les points de terminaison dédiés à l'importation et au téléchargement pour l'API XML, consultez la page Points de terminaison de requêtes.

En-têtes et paramètres de chaîne de requête

L'API XML de Cloud Storage accepte les en-têtes de requêtes HTTP. Il accepte également plusieurs en-têtes de requête d'extension (personnalisés), qui portent le préfixe x-goog-. Les exigences relatives aux en-têtes de requête varient en fonction du type de requête que vous effectuez. Voici quelques-uns des en-têtes de requête fréquemment utilisés:

En-tête de requête Description Utilisation
Authorization Chaîne d'authentification pour les requêtes. Obligatoire pour toutes les requêtes authentifiées.
Content-Length Taille du corps de la requête (en-têtes exclus), en octets. Obligatoire pour toutes les requêtes PUT et POST, à l'exception des transferts fragmentés.
Content-Type Type MIME du corps de la requête, par exemple application/xml ou text/html. Recommandé pour les requêtes contenant un corps d'entité.
Date Date et heure de la requête. Obligatoire pour toutes les requêtes.
Host URI de la requête. Obligatoire pour toutes les requêtes.
x-goog-project-id ID du projet que vous souhaitez utiliser. Obligatoire pour la création de buckets ou pour répertorier des buckets, sauf lorsque vous utilisez l'API XML pour l'interopérabilité, par exemple pour assurer la compatibilité avec Amazon S3. Pour en savoir plus, consultez la section Migrer depuis Amazon S3 vers Google Cloud Storage.

L'API XML de Cloud Storage est également compatible avec divers paramètres de chaîne de requête que vous pouvez utiliser pour définir vos champs d'application. Ajoutez des paramètres de chaîne de requête à la partie chemin d'accès HTTP de la requête avec la syntaxe suivante:

PATH_TO_OBJECT/?PARAMETER=VALUE&PARAMETER=VALUE...

Pour obtenir la liste complète des en-têtes de l'API XML et des paramètres de chaîne de requête, consultez la section En-têtes HTTP et paramètres de chaîne de requête.

Exemple de requête

Une requête Cloud Storage authentifiée type est présentée dans l'exemple suivant. Cette requête récupérer une liste d'objets stockés dans un bucket nommé travel-maps. La requête limite la liste d'objets à ceux uniquement avec le préfixe /europe/france.

GET /?prefix=/europe/france/ HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Wed, 17 Feb 2010 15:31:56 -0800
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Réponses

L'API XML de Cloud Storage renvoie des en-têtes de réponse HTTP standards et plusieurs en-têtes de réponse d'extension (personnalisés). Les en-têtes de réponse varient en fonction de l'opération que vous effectuez. Voici quelques en-têtes de réponse fréquemment utilisés:

En-tête de la réponse Description
Cache-Control Paramètre de contrôle du cache pour la réponse.
Content-Length Taille du corps de la réponse (en-têtes exclus), en octets.
Content-Type Type MIME du corps de la réponse, tel que application/xml ou text/html.
Date Date et heure de la réponse.
ETag Un tag d'entité HTTP 1.1, que vous pouvez utiliser pour déterminer

si un objet a été modifié.

Les réponses peuvent également inclure un code d'état. Cloud Storage utilise des codes d'état HTTP standards. Une réponse d'erreur inclut un document XML dans le corps de la réponse, qui contient des informations sur les conditions d'erreur. Pour obtenir la liste des codes d'état utilisés par l'API XML, consultez la page État HTTP et codes d'erreur.

L'exemple suivant illustre une réponse Cloud Storage type. Cet exemple est une réponse à une requête visant à répertorier le contenu d'un bucket. Le nom du bucket est travel-maps et la requête est définie de sorte que seuls les objets comportant le préfixe /europe/france/ soient renvoyés dans la liste.

HTTP/1.1 200 OK
Content-Length: 4061
Content-Type: application/xml
Date: Wed, 17 Feb 2010 23:31:57 GMT
Cache-Control: private, max-age=0

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.storage.googleapis.com/2010-03-01'>
  <Name>travel-maps</Name>
  <Prefix>/europe/france/</Prefix>
  <Marker></Marker>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/france/cannes.jpg</Key>
    <LastModified>2010-02-17T22:11:12.487Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>europe/france/paris.jpg</Key>
    <LastModified>2010-02-17T22:09:57.457Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>