Solicita extremos

En esta página, se explican los diferentes extremos de solicitud que puedes usar para acceder a Cloud Storage. Cloud Storage es compatible con los protocolos HTTP/1.1, HTTP/2 y HTTP/3. Un extremo es la ubicación en la que se puede acceder a Cloud Storage, escrito como una URL.

Solicitudes a la API típicas

API de JSON

Cuando realizas solicitudes a la API de JSON directamente a Cloud Storage, usa los extremos siguientes:

  • Para las solicitudes generales a la API de JSON, sin incluir las cargas de objetos, usa los siguientes extremos y reemplaza PATH_TO_RESOURCE por el valor apropiado:

    https://storage.s3nsapis.fr/storage/v1/PATH_TO_RESOURCE
  • Para las cargas de objeto de la API de JSON, usa el extremo siguiente y reemplaza BUCKET_NAME por el valor apropiado:

    https://storage.s3nsapis.fr/upload/storage/v1/b/BUCKET_NAME/o
  • Para las solicitudes por lotes, usa el siguiente extremo y reemplaza PATH_TO_RESOURCE por los valores adecuados:

    https://storage.s3nsapis.fr/batch/storage/v1/PATH_TO_RESOURCE
  • De manera opcional, para las descargas de objetos de la API de JSON, puedes usar el siguiente extremo y reemplazar BUCKET_NAME y OBJECT_NAME por los valores adecuados:

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

Los extremos de la API de JSON solo aceptan solicitudes HTTPS.

API de XML

Cuando realices solicitudes a la API de XML directamente a Cloud Storage, usa el extremo de estilo de alojamiento virtual o de estilo de ruta de acceso y reemplaza BUCKET_NAME y OBJECT_NAME por los valores correspondientes:

  • Extremo de estilo de alojamiento virtual:

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

  • Extremo de estilo de ruta de acceso:

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

Los extremos de la API de XML son compatibles con la encriptación de la capa de conexión segura (SSL), lo que significa que puedes usar HTTP o HTTPS. Se recomienda usar HTTPS, en especial si realizas la autenticación en Cloud Storage con OAuth 2.0.

Para obtener más información sobre conexiones a través de un proxy, consulta las prácticas recomendadas en Solución de problemas.

Codifica partes de la ruta de URL

Además de las consideraciones generales para la definición de nombres de buckets y de objetos, para garantizar la compatibilidad entre las herramientas de Cloud Storage, debes codificar los siguientes caracteres cuando aparezcan en el nombre del objeto o en la cadena de consulta de la URL de una solicitud:

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

Por ejemplo, si envías una solicitud GET para la API de JSON correspondiente al objeto llamado foo??bar en el bucket example-bucket, tu URL de 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 enumerados deben codificarse en todas las situaciones. Además, las bibliotecas cliente, como las bibliotecas cliente de Cloud Storage, manejan la codificación para que puedas pasar el nombre del objeto sin procesar cuando uses esas herramientas.

Para obtener más información sobre el uso de la codificación en porcentajes, consulta la sección 3.3 Ruta de acceso en la RFC 3986.

Trusted Cloud extremos de la consola

Cuando usas la consola de Trusted Cloud , puedes acceder a diferentes recursos a través de las siguientes URLs:

Recurso URL
Lista de buckets para un proyecto https://console.cloud.s3nscloud.fr/storage/browser?project=PROJECT_ID
Lista de objetos para un bucket 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 para un objeto Consulta Descargas autenticadas del navegador

gcloud endpoints

Los comandos de gcloud storage usan extremos de la API de JSON. El uso de los extremos se administra en tu nombre mediante gcloud CLI.

Extremos de bibliotecas cliente

Las bibliotecas cliente de Cloud Storage administran los extremos de las solicitudes de forma automática. De forma opcional, puedes configurar el extremo de la solicitud de forma manual. Esto puede ser útil cuando deseas usar un extremo específico o para realizar pruebas, como cuando quieres usar un emulador local:

C++

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.

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#

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.


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

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

Go

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.

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

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.


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

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.

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

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.

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

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.


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

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

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.

# 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 autenticadas del navegador

Las descargas autenticadas de navegador usan una autenticación basada en cookies. La autenticación basada en cookies les pide a los usuarios que accedan a su cuenta de usuario para establecer su identidad. La cuenta especificada debe tener permisos apropiados para descargar el objeto. Por ejemplo, si usas la administración de identidades y accesos para controlar el acceso a tus objetos, la cuenta del usuario debe tener el permiso storage.objects.viewer, que se otorga con el rol Visualizador de objetos de almacenamiento.

Para descargar un objeto con la autenticación basada en cookies, usa la siguiente URL y reemplaza BUCKET_NAME y OBJECT_NAME por los valores adecuados:

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

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

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

Después de acceder correctamente, se te redireccionará al contenido deseado. La URL de este contenido comienza con una secuencia alfanumérica y contiene la string /download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME

Se requiere el uso de HTTPS cuando se realizan descargas autenticadas del navegador; los intentos de usar HTTP redireccionan 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 tiene permiso para acceder a un objeto. Si quieres que los usuarios descarguen objetos accesibles de forma anónima sin necesidad de autenticarse, usa el extremo de estilo de ruta de acceso de la API de XML:

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

Para obtener más detalles y ejemplos, consulta Accede a datos públicos.

Compatibilidad con TLS mutua

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

¿Qué sigue?