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

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.googleapis.com/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 consolaGoogle Cloud

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

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:

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);
}

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

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

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
}

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());
  }
}

/**
 * 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}.`);

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);
}

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

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

Dominios personalizados

Si tienes tu propio dominio, puedes asignar sus URIs a uno o varios Google Cloud servicios, incluidos los segmentos de Cloud Storage. El término nombre de host asociado a un contenedor se usa a veces para describir este endpoint de solicitud de Cloud Storage. Para conectar un dominio personalizado a un segmento de Cloud Storage, debes crear una redirección A o CNAME en tu registro DNS.

A registros

Cuando conectas un dominio personalizado a un segmento de Cloud Storage, normalmente debes usar un registro A.

• A registros de solicitudes de asistencia HTTPS.
• Los registros A se pueden usar para enviar el tráfico procedente de un solo nombre de host a varios segmentos, así como a otros servicios Google Cloud .
• A no impone ninguna restricción al nombre del segmento.

El inconveniente de usar registros A es que requieren una configuración adicional y el uso de Google Cloud recursos adicionales. Consulta la guía Configurar el balanceador de carga y el certificado SSL para obtener información sobre cómo usar dominios personalizados con registros A.

CNAME registros

Cuando conectas un dominio personalizado a un segmento de Cloud Storage, puedes usar un registro CNAME, pero ten en cuenta que esto tiene ciertas limitaciones:

• Los registros CNAME solo admiten solicitudes HTTP.
• Los registros CNAME solo pueden dirigir el tráfico de un nombre de host determinado a un único contenedor.
• Los registros CNAME requieren que el nombre de host y el nombre del segmento asociado coincidan, y debes validar el nombre del segmento.
• Los registros CNAME solo se pueden usar en subdominios, como www.mydomain.com, no en dominios de nivel superior, como mydomain.com.

Cuando se usan registros CNAME, la parte del nombre de host del registro CNAME debe ser la siguiente:

c.storage.googleapis.com.

Por ejemplo, supongamos que tu dominio es example.com y quieres que tus clientes puedan acceder a mapas de viajes. Puedes crear un segmento en Cloud Storage llamado travel-maps.example.com y, a continuación, crear un registro CNAME en DNS que redirija las solicitudes de travel-maps.example.com al URI de Cloud Storage. Para ello, publica el siguiente registro CNAME en DNS:

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

De esta forma, tus clientes podrán usar la siguiente URL para acceder a un mapa de París:

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

El servicio de registro de tu dominio debería ofrecerte una forma de administrar tu dominio, incluida la opción de añadir un registro de recursos CNAME. Por ejemplo, si usas Cloud DNS, puedes consultar las instrucciones para añadir registros de recursos en la página Añadir, modificar y eliminar registros.

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.googleapis.com/BUCKET_NAME/OBJECT_NAME

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

Compatibilidad con TLS mutuo

• Solicitudes de la API JSON: storage.mtls.googleapis.com

• Descargas de navegador autenticadas: storage.mtls.cloud.google.com

Siguientes pasos

• Sube un archivo a Cloud Storage.
• Descargar un archivo de Cloud Storage.
• Alojar un sitio web estático.
• Consulta las opciones para controlar el acceso a tus datos.