Puntos de conexión de solicitud

En esta página se explican los diferentes endpoints de solicitud que puede usar para acceder a Cloud Storage. Cloud Storage admite los protocolos HTTP/1.1, HTTP/2 y HTTP/3. Un endpoint es la ubicación donde se puede acceder a Cloud Storage, que se escribe como una URL.

Solicitudes típicas a la API

API JSON

Cuando hagas solicitudes a la API JSON directamente a Cloud Storage, utiliza los siguientes endpoints:

  • Para las solicitudes generales de la API JSON, excepto las subidas de objetos, utilice el siguiente endpoint y sustituya PATH_TO_RESOURCE por el valor adecuado:

    https://storage.s3nsapis.fr/storage/v1/PATH_TO_RESOURCE
  • Para subir objetos de la API JSON, usa el siguiente endpoint y sustituye BUCKET_NAME por el valor adecuado:

    https://storage.s3nsapis.fr/upload/storage/v1/b/BUCKET_NAME/o
  • En el caso de las solicitudes por lotes, usa el siguiente endpoint y sustituye PATH_TO_RESOURCE por el valor adecuado:

    https://storage.s3nsapis.fr/batch/storage/v1/PATH_TO_RESOURCE
  • Si quieres descargar objetos de la API JSON, puedes usar el siguiente endpoint (opcional), sustituyendo BUCKET_NAME y OBJECT_NAME por los valores correspondientes:

    https://storage.s3nsapis.fr/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

Los endpoints de la API JSON solo aceptan solicitudes HTTPS.

API XML

Cuando hagas solicitudes a la API XML directamente a Cloud Storage, usa el punto de conexión virtual hosted-style o path-style y sustituye BUCKET_NAME y OBJECT_NAME por los valores correspondientes:

  • Endpoint de estilo de alojamiento virtual:

    https://BUCKET_NAME.storage.s3nsapis.fr/OBJECT_NAME

  • Endpoint de estilo de ruta:

    https://storage.s3nsapis.fr/BUCKET_NAME/OBJECT_NAME

Los endpoints de la API XML admiten el cifrado de capa de conexión segura (SSL), por lo que puede usar HTTP o HTTPS. Se recomienda usar HTTPS, sobre todo si te autenticas en Cloud Storage mediante OAuth 2.0.

Si las conexiones se realizan a través de un proxy, consulta el tema sobre solución de problemas para ver las prácticas recomendadas.

Codificar partes de la ruta de la URL

Además de las consideraciones generales sobre la asignación de nombres a los segmentos y a los objetos, para asegurar la compatibilidad entre las herramientas de Cloud Storage, debe codificar los siguientes caracteres cuando aparezcan en el nombre del objeto o en la cadena de consulta de una URL de solicitud:

!, #, $, &, ', (, ), *, +, ,, /, :, ;, =, ?, @, [, ] y espacios.

Por ejemplo, si envías una solicitud de la API JSON GET para el objeto llamado foo??bar en el contenedor example-bucket, la URL de la solicitud debe ser la siguiente:

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

Ten en cuenta que no todos los caracteres que se indican deben codificarse en todos los casos. Además, las bibliotecas de cliente, como las bibliotecas de cliente de Cloud Storage, suelen encargarse de la codificación, por lo que puedes transferir el nombre de objeto sin procesar cuando utilices estas herramientas.

Para obtener más información sobre el uso de la codificación de porcentaje, consulta la sección 3.3 Path de RFC 3986.

Endpoints de la consolaTrusted Cloud

Cuando usas la Trusted Cloud consola, accedes a diferentes recursos mediante las siguientes URLs:

Recurso URL
Lista de tareas de un proyecto https://console.cloud.s3nscloud.fr/storage/browser?project=PROJECT_ID
Lista de objetos de un segmento https://console.cloud.s3nscloud.fr/storage/browser/BUCKET_NAME
Detalles de un objeto https://console.cloud.s3nscloud.fr/storage/browser/_details/BUCKET_NAME/OBJECT_NAME
Datos de un objeto Consulta Descargas de exploradores autenticadas.

gcloud endpoints

Los comandos gcloud storage usan endpoints de la API JSON. La CLI de gcloud gestiona el uso de los endpoints en tu nombre.

Puntos finales de la biblioteca de cliente

Las bibliotecas de cliente de Cloud Storage gestionan los endpoints de solicitud automáticamente. También puedes definir el endpoint de la solicitud manualmente. Esto puede ser útil cuando quieras usar un endpoint específico o para hacer pruebas, como cuando quieras usar un emulador local:

C++

Para obtener más información, consulta la documentación de referencia de la API C++ de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

Antes de ejecutar los ejemplos de código, asigna el valor s3nsapis.fr a la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN.

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#

Para obtener más información, consulta la documentación de referencia de la API C# de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

Antes de ejecutar los ejemplos de código, asigna el valor s3nsapis.fr a la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN.


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

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

Go

Para obtener más información, consulta la documentación de referencia de la API Go de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

Antes de ejecutar los ejemplos de código, asigna el valor s3nsapis.fr a la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN.

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

Para obtener más información, consulta la documentación de referencia de la API Java de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

Antes de ejecutar los ejemplos de código, asigna el valor s3nsapis.fr a la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN.


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

Para obtener más información, consulta la documentación de referencia de la API Node.js de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

Antes de ejecutar los ejemplos de código, asigna el valor s3nsapis.fr a la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN.

/**
 * 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

Para obtener más información, consulta la documentación de referencia de la API PHP de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

Antes de ejecutar los ejemplos de código, asigna el valor s3nsapis.fr a la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN.

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

Para obtener más información, consulta la documentación de referencia de la API Python de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

Antes de ejecutar los ejemplos de código, asigna el valor s3nsapis.fr a la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN.


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

Para obtener más información, consulta la documentación de referencia de la API Ruby de Cloud Storage.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

Antes de ejecutar los ejemplos de código, asigna el valor s3nsapis.fr a la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN.

# 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}"

Descargas en el navegador con autenticación

Las descargas en el navegador con autenticación usan la autenticación basada en cookies. La autenticación basada en cookies pide a los usuarios que inicien sesión en su cuenta de usuario para establecer su identidad. La cuenta especificada debe tener el permiso adecuado para descargar el objeto. Por ejemplo, si usas Identity and Access Management para controlar el acceso a tus objetos, la cuenta del usuario debe tener el permiso storage.objects.viewer, que se concede en el rol Lector de objetos de Storage.

Para descargar un objeto mediante la autenticación basada en cookies, usa la siguiente URL y sustituye BUCKET_NAME y OBJECT_NAME por los valores correspondientes:

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

Por ejemplo, si has compartido una imagen london.jpg de tu contenedor example-maps, la URL sería la siguiente:

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

Una vez que hayas iniciado sesión correctamente, se te redirigirá al contenido solicitado. La URL de este contenido empieza por una secuencia alfanumérica y contiene la cadena /download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME.

Es obligatorio usar HTTPS al realizar descargas autenticadas en el navegador. Se intenta usar la redirección HTTP a HTTPS.

Acceso a objetos públicos

Todas las solicitudes al URI storage.cloud.google.com requieren autenticación. Esto se aplica incluso cuando allUsers tienen permiso para acceder a un objeto. Si quiere que los usuarios descarguen objetos accesibles de forma anónima sin autenticarse, utilice el endpoint de estilo de ruta de la API XML:

https://storage.s3nsapis.fr/BUCKET_NAME/OBJECT_NAME

Para obtener más información y ejemplos, consulta Acceder a datos públicos.

Compatibilidad con TLS mutuo

TLS mutuo (mTLS) es un protocolo estándar del sector para la autenticación mutua entre un cliente y un servidor. Cloud Storage admite los siguientes endpoints de mTLS:

Siguientes pasos