Points de terminaison de requêtes

Cette page explique les différents points de terminaison de requêtes que vous pouvez utiliser pour accéder à Cloud Storage. Cloud Storage est compatible avec les protocoles HTTP/1.1, HTTP/2 et HTTP/3. Un point de terminaison est l'emplacement auquel Cloud Storage est accessible, écrit sous forme d'URL.

Remarque : Les URL Cloud Storage décrits sur cette page sont susceptibles d'être modifiés.

Requêtes API classiques

API JSON

Lorsque vous envoyez des requêtes API JSON directement à Cloud Storage, utilisez les points de terminaison suivants :

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

  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 BUCKET_NAME par la valeur appropriée :

  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 PATH_TO_RESOURCE par le valeur appropriée :

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

• Pour les téléchargements d'objets d'API JSON, vous pouvez éventuellement utiliser le point de terminaison suivant, en remplaçant BUCKET_NAME et OBJECT_NAME 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.

Remarque : Un point de terminaison https://www.googleapis.com est également compatible avec l'API JSON et s'affiche dans le champ de métadonnées selfLink d'un objet, mais https://storage.googleapis.com est le point de terminaison à privilégier pour de meilleures performances et une disponibilité accrue. De même, un point de terminaison https://content-storage.googleapis.com est compatible avec les téléchargements et est renvoyé dans le champ de métadonnées mediaLink d'un objet, mais son utilisation n'est pas recommandée.

API XML

Important : Si vous envisagez de diffuser des contenus via un navigateur, sachez que l'API XML diffuse des contenus ayant la même origine que le point de terminaison de la requête. Si vous devez diffuser des contenus provenant d'une origine unique, envisagez d'utiliser l'API JSON ou les téléchargements authentifiés via un navigateur.

Lors de la création de requêtes API XML directement dans Cloud Storage, utilisez le point de terminaison hébergé virtuellement ou avec chemin en remplaçant BUCKET_NAME et OBJECT_NAME par les valeurs appropriées :

• Point de terminaison hébergé virtuellement :

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

• Point de terminaison avec chemin d'accès :

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

Remarque : Vous ne pouvez pas accéder aux buckets nommés par domaine avec les points de terminaison hébergés virtuellement. Utilisez plutôt des points de terminaison de type "avec chemin" ou une redirection.

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'URL

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 URL 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'URL 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 de l'encodage en pourcentage, consultez la section Chemin d'accès 3.3 dans la RFC 3986.

Points de terminaison de la console Google Cloud

Lorsque vous utilisez la console Google Cloud, 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
Données d'un objet	Consultez la section Téléchargements de navigateurs authentifiés.

gcloud endpoints

Les commandes gcloud storage utilisent des points de terminaison de l'API JSON. L'utilisation des points de terminaison est gérée en votre nom par gcloud CLI.

Points de terminaison des bibliothèques clientes

Les bibliothèques clientes Cloud Storage gèrent automatiquement les points de terminaison de requêtes. Vous pouvez éventuellement définir le point de terminaison de requêtes manuellement. Cette option peut s'avérer utile lorsque vous souhaitez utiliser un point de terminaison spécifique ou pour les tests, par exemple si vous souhaitez utiliser un émulateur local :

C++

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C++.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

namespace g = ::google::cloud;
namespace gcs = ::google::cloud::storage;
[](std::string const& bucket_name, std::string const& object_name) {
  // NOTE: the CLOUD_STORAGE_EMULATOR_HOST environment variable overrides any
  //     value provided here.
  auto client = gcs::Client(g::Options{}.set<gcs::RestEndpointOption>(
      "https://storage.googleapis.com"));
  PerformSomeOperations(client, bucket_name, object_name);
}

C#

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage C#.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

using Google.Cloud.Storage.V1;
using System;

public class SetClientEndpointSample
{
    public StorageClient SetClientEndpoint(string endpoint) => new StorageClientBuilder
    {
        BaseUri = endpoint
    }.Build();
}

Go

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Go.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
	"google.golang.org/api/option"
)

// setClientEndpoint sets the request endpoint.
func setClientEndpoint(w io.Writer, customEndpoint string, opts ...option.ClientOption) error {
	// customEndpoint := "https://my-custom-endpoint.example.com/storage/v1/"
	// opts := []option.ClientOption{}
	ctx := context.Background()

	// Add the custom endpoint option to any other desired options passed to storage.NewClient.
	opts = append(opts, option.WithEndpoint(customEndpoint))
	client, err := storage.NewClient(ctx, opts...)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	// Use the client as per your custom endpoint, for example, attempt to get a bucket's metadata.
	client.Bucket("bucket-name").Attrs(ctx)
	return nil
}

Java

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Java.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class SetClientEndpoint {

  public static void setClientEndpoint(String projectId, String endpoint) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The endpoint you wish to target
    // String endpoint = "https://storage.googleapis.com"

    Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).setHost(endpoint).build().getService();

    System.out.println(
        "Storage Client initialized with endpoint " + storage.getOptions().getHost());
  }
}

Node.js

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Node.js.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The custom endpoint to which requests should be made
// const apiEndpoint = 'https://yourcustomendpoint.com';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage({
  apiEndpoint: apiEndpoint,
  useAuthWithCustomEndpoint: true,
});

console.log(`Client initiated with endpoint: ${storage.apiEndpoint}.`);

PHP

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage PHP.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

use Google\Cloud\Storage\StorageClient;

/**
 * Sets a custom endpoint for storage client.
 *
 * @param string $projectId The ID of your Google Cloud Platform project.
 *        (e.g. 'my-project-id')
 * @param string $endpoint The endpoint for storage client to target.
 *        (e.g. 'https://storage.googleapis.com')
 */
function set_client_endpoint(
    string $projectId,
    string $endpoint
): void {
    $storage = new StorageClient([
        'projectId' => $projectId,
        'apiEndpoint' => $endpoint,
    ]);

    // fetching apiEndpoint and baseUri from StorageClient is excluded for brevity
    # ...
    print('Storage Client initialized.' . PHP_EOL);
}

Python

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Python.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

from google.cloud import storage


def set_client_endpoint(api_endpoint):
    """Initiates client with specified endpoint."""
    # api_endpoint = 'https://storage.googleapis.com'

    storage_client = storage.Client(client_options={'api_endpoint': api_endpoint})

    print(f"client initiated with endpoint: {storage_client._connection.API_BASE_URL}")

    return storage_client

Ruby

Pour en savoir plus, consultez la documentation de référence de l'API Cloud Storage en langage Ruby.

Pour vous authentifier auprès de Cloud Storage, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

# api_endpoint = "https://storage.googleapis.com"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new(
  endpoint: api_endpoint
)

puts "Client initiated with endpoint #{storage.service.service.root_url}"

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, la partie nom d'hôte de votre enregistrement CNAME doit être définie comme suit :

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 Cloud DNS, vous trouverez des instructions relatives à l'ajout d'enregistrements de ressources sur la page Ajouter, modifier et supprimer des enregistrements.

Téléchargements via un navigateur 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 pour établir leur identité. Le compte 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 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 BUCKET_NAME et OBJECT_NAMEpar 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

Une fois connecté, vous êtes redirigé vers le contenu demandé. L'URL de ce contenu commence par une séquence alphanumérique et contient la chaîne /download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME.

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 le point de terminaison de type avec chemin de l'API XML :

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

Pour obtenir plus d'informations et des exemples, consultez la page Accéder aux données publiques.

Compatibilité avec le protocole TLS mutuel

TLS mutuel (mTLS) est un protocole standard du secteur pour l'authentification mutuelle entre un client et un serveur. Cloud Storage est compatible avec les points de terminaison mTLS suivants :

• Requêtes d'API JSON: storage.mtls.googleapis.com

• Téléchargements de navigateurs authentifiés: storage.mtls.cloud.google.com

Étape suivante

• Transférez un fichier vers Cloud Storage.
• Téléchargez un fichier depuis Cloud Storage.
• Hébergez un site web statique.
• Découvrez les options permettant de contrôler l'accès à vos données.