Points de terminaison de requêtes

Cette page explique les différents points de terminaison de requêtes (URI) que vous pouvez utiliser pour accéder à Cloud Storage. Cloud Storage est compatible avec les protocoles HTTP/1.1, HTTP/2 et HTTP/3.

Requêtes API classiques

Lorsque vous envoyez des requêtes directement à l'une des API Cloud Storage, utilisez les URI suivants :

API JSON

  • Pour les requêtes d'API JSON générales, à l'exclusion des importations d'objets, utilisez le point de terminaison suivant, en remplaçant PLACEHOLDER par les valeurs appropriées :

    https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE

  • Pour les importations d'objets d'API JSON, utilisez le point de terminaison suivant, en remplaçant PLACEHOLDER par les valeurs appropriées :

    https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o

  • Pour les requêtes par lot, utilisez le point de terminaison suivant, en remplaçant PLACEHOLDER par les valeurs appropriées :

    https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE

  • Si vous souhaitez télécharger des objets de l'API JSON, vous pouvez éventuellement utiliser le point de terminaison suivant, en remplaçant PLACEHOLDER par les valeurs appropriées :

    https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

Les points de terminaison de l'API JSON n'acceptent que les requêtes HTTPS.

API XML

  • Pour les requêtes d'API XML, vous pouvez utiliser un point de terminaison hébergé virtuellement ou avec chemin, en remplaçant les éléments entre crochets (PLACEHOLDER) par les valeurs appropriées :

    Hébergé virtuellement :

    https://BUCKET_NAME.storage.googleapis.com/OBJECT_NAME
    Avec chemin :
    https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

Les points de terminaison de l'API XML sont compatibles avec le chiffrement SSL, ce qui signifie que vous pouvez utiliser HTTP ou HTTPS. L'utilisation de HTTPS est recommandée, en particulier si vous vous authentifiez auprès de Cloud Storage à l'aide d'OAuth 2.0.

Pour connaître les pratiques recommandées dans le cas de connexions via un proxy, consultez la rubrique dédiée de la page Dépannage.

Encoder des parties de chemin d'URI

En plus des considérations générales à prendre en compte pour les noms de buckets et les noms d'objets, vous devez encoder les caractères suivants lorsqu'ils s'affichent dans le nom d'objet ou la chaîne de requête d'un URI de requête afin d'assurer la compatibilité entre les outils Cloud Storage :

!, #, $, &, ', (, ), *, +, ,, /, :, ;, =, ?, @, [, ] et les espaces

Par exemple, si vous envoyez une requête GET depuis l'API JSON pour l'objet nommé foo??bar dans le bucket example-bucket, l'URI de votre requête doit être au format suivant :

GET https://storage.googleapis.com/storage/v1/b/example-bucket/o/foo%3f%3fbar

Notez que tous les caractères répertoriés ne doivent pas être encodés dans chaque scénario. En outre, les bibliothèques clientes, telles que les bibliothèques clientes Cloud Storage, gèrent généralement l'encodage pour vous afin que vous puissiez leur transmettre le nom de l'objet brut.

Pour en savoir plus sur l'utilisation des URI encodés en pourcentage, consultez la Section 3.3 Chemin dans la RFC 3986.

Points de terminaison Cloud Console

Lorsque vous utilisez Cloud Console, vous accédez à différentes ressources via les URL suivantes :

Ressource URL
Liste des buckets pour un projet https://console.cloud.google.com/storage/browser?project=PROJECT_ID
Liste des objets pour un bucket https://console.cloud.google.com/storage/browser/BUCKET_NAME
Détails d'un objet https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME

Points de terminaison gsutil

Par défaut, gsutil accède à Cloud Storage via les points de terminaison de requêtes de l'API JSON. Vous pouvez contrôler ce comportement par défaut en définissant la variable prefer_api dans la section "GSUtil" du fichier de configuration .boto sur xml ou json, comme suit :

prefer_api = xml

gsutil utilise si possible l'API de votre choix. Si cela n'est pas possible, il utilise l'autre API sans vous le notifier. Par exemple, la commande ubla n'est pas compatible avec l'API XML. gsutil utilise donc toujours l'API JSON pour cette commande. De même, gsutil utilise toujours l'API XML pour interagir avec des fournisseurs de stockage cloud qui n'acceptent pas l'API JSON.

Considérations sur les performances et les coûts

L'API XML utilise le framework boto. Ce framework relit les fichiers téléchargés pour en calculer un hachage MD5 s'ils n'en possèdent pas. Concernant les objets qui n'incluent pas les hachages MD5 dans leurs métadonnées, tels que les objets composites, la quantité de bande passante consommée et le temps écoulé nécessaires au téléchargement sont doublés. Si vous utilisez des objets composites, vous devez éviter de définir prefer_api sur xml.

L'API XML nécessite également des appels distincts pour obtenir différents champs de métadonnées d'objets et de buckets, tels que les configurations de bucket. Utilisez l'API JSON dans la mesure du possible, car elle nécessite moins d'opérations et entraîne donc un coût inférieur.

Domaines personnalisés

Si vous êtes propriétaire de votre propre domaine, vous pouvez mapper ses URI à un ou plusieurs services Google Cloud, y compris des buckets Cloud Storage. Le terme nom d'hôte lié au bucket est parfois utilisé pour décrire ce point de terminaison de requête Cloud Storage. Pour connecter un domaine personnalisé à un bucket Cloud Storage, vous devez créer une redirection A ou CNAME dans votre enregistrement DNS.

Enregistrements A

Lorsque vous connectez un domaine personnalisé à un bucket Cloud Storage, vous devez généralement utiliser un enregistrement A.

  • Les enregistrements A acceptent les requêtes HTTPS.
  • Les enregistrements A permettent d'envoyer du trafic provenant d'un seul nom d'hôte à plusieurs buckets, ainsi qu'à d'autres services Google Cloud.
  • Les enregistrements A n'imposent aucune restriction sur le nom de votre bucket.

L'inconvénient de l'utilisation des enregistrements A est qu'ils nécessitent une configuration supplémentaire et l'utilisation de ressources Google Cloud supplémentaires. Pour savoir comment utiliser des domaines personnalisés avec des enregistrements A, consultez la page Configurer votre équilibreur de charge et votre certificat SSL.

Enregistrements CNAME

Lorsque vous connectez un domaine personnalisé à un bucket Cloud Storage, vous pouvez utiliser un enregistrement CNAME. Notez toutefois que cela comporte certaines limites :

  • Les enregistrements CNAME n'acceptent que les requêtes HTTP.
  • Les enregistrements CNAME peuvent uniquement diriger le trafic d'un nom d'hôte donné vers un seul bucket.
  • Les enregistrements CNAME exigent que le nom d'hôte et le nom du bucket associé correspondent. Vous devez valider le nom de votre bucket.
  • Les enregistrements CNAME ne peuvent être utilisés que pour des sous-domaines, tels que www.mydomain.com, et non pour les domaines de premier niveau tels que mydomain.com.

Lorsque vous utilisez des enregistrements CNAME, l'URI suivant doit être ajouté à la partie nom d'hôte de votre enregistrement CNAME :

c.storage.googleapis.com.

Par exemple, supposons que votre domaine soit example.com et que vous souhaitiez mettre des cartes de voyage à la disposition de vos clients. Vous pouvez créer un bucket dans Cloud Storage nommé travel-maps.example.com, puis créer un enregistrement CNAME dans le DNS qui redirige les requêtes de travel-maps.example.com vers l'URI Cloud Storage. Pour ce faire, publiez l'enregistrement CNAME suivant dans le DNS :

NAME                      TYPE     DATA
travel-maps               CNAME    c.storage.googleapis.com.

Vos clients peuvent ainsi utiliser l'URL suivante pour accéder à une carte de Paris :

http://travel-maps.example.com/paris.jpg

Votre service d'enregistrement de domaine devrait vous permettre d'administrer votre domaine, y compris en ajoutant un enregistrement de ressource CNAME. Par exemple, si vous utilisez Google Domains, les instructions permettant d'ajouter un enregistrement de ressource sont disponibles sur la page Aide Google Domains, dans la section déroulante Enregistrements de ressources.

Téléchargements de navigateurs authentifiés

Les téléchargements authentifiés via un navigateur utilisent une authentification basée sur les cookies. Celle-ci demande aux utilisateurs de se connecter à leur compte Google pour établir leur identité. Le compte Google spécifié doit disposer des autorisations appropriées pour télécharger l'objet. Par exemple, si vous utilisez Cloud Identity and Access Management pour contrôler l'accès à vos objets, le compte Google de l'utilisateur doit disposer de l'autorisation storage.objects.viewer, qui est accordée dans le cadre du rôle Lecteur des objets de l'espace de stockage.

Pour télécharger un objet à l'aide d'une authentification basée sur les cookies, utilisez l'URL suivante, en remplaçant PLACEHOLDER par les valeurs appropriées :

https://storage.cloud.google.com/BUCKET_NAME/OBJECT_NAME

Par exemple, si vous avez partagé une image london.jpg à partir de votre bucket example-maps, l'URL serait la suivante :

https://storage.cloud.google.com/example-maps/london.jpg

L'utilisation du protocole HTTPS est requise pour les téléchargements authentifiés via un navigateur. Si vous tentez d'envoyer des requêtes en HTTP, elles sont redirigées vers HTTPS.

Accès aux objets publics

Toutes les requêtes à l'URI storage.cloud.google.com nécessitent une authentification. Ceci s'applique même lorsque tous les utilisateurs (allUsers) ont l'autorisation d'accéder à un objet. Si vous souhaitez que les utilisateurs téléchargent des objets accessibles anonymement sans authentification, utilisez l'URI storage.googleapis.com documenté dans les requêtes API directes. Pour obtenir plus d'informations et des exemples, consultez la page Accéder aux données publiques.

Étapes suivantes