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.

Nota: Las URL de Cloud Storage que se describen en esta página están sujetos a cambios.

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.googleapis.com/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.googleapis.com/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.googleapis.com/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.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

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

Nota: Un extremo https://www.googleapis.com también es compatible con la API de JSON y se muestra en el campo de metadatos selfLink para un objeto, pero https://storage.googleapis.com es el extremo preferido para obtener mejor rendimiento y disponibilidad. De manera similar, un extremo https://content-storage.googleapis.com es compatible con las descargas y se muestra en el campo de metadatos mediaLink para un objeto, pero tampoco se recomienda su uso.

API de XML

Importante: Si quieres entregar contenido a través de un navegador, ten en cuenta que la API de XML entrega contenido desde el mismo origen que el extremo de la solicitud. Si necesitas entregar contenido desde un origen único, considera usar la API de JSON o las descargas autenticadas del navegador.

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

• Extremo de estilo de ruta de acceso:

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

Nota: Los extremos de estilo de alojamiento virtual no se pueden usar para acceder a los buckets con nombre de dominio. En su lugar, usa extremos de estilo de ruta de acceso o un redireccionamiento.

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

Extremos de la consola de Google Cloud

Cuando usas la consola de Google Cloud, puedes acceder a diferentes recursos mediante las siguientes URL:

Recurso	URL
Lista de buckets para un proyecto	https://console.cloud.google.com/storage/browser?project=PROJECT_ID
Lista de objetos para un bucket	https://console.cloud.google.com/storage/browser/BUCKET_NAME
Detalles de un objeto	https://console.cloud.google.com/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.

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.

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.

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.

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.

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

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.

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.

# 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 eres propietario de tu dominio, puedes mapear sus URI a uno o más servicios de Google Cloud, incluidos los buckets de Cloud Storage. A veces, se usa el término nombre de host vinculado al bucket para describir a este extremo de solicitud de Cloud Storage. Para conectar un dominio personalizado a un bucket de Cloud Storage, debes crear un redireccionamiento A o CNAME en tu registro DNS.

Registros A

Cuando conectas un dominio personalizado a un bucket de Cloud Storage, por lo general, debes usar un registro A.

• Los registros A admiten solicitudes HTTPS.
• Los registros A se pueden usar para enviar tráfico que provenga de un nombre de host único a varios buckets y a otros servicios de Google Cloud.
• Los registros A no establecen restricciones en el nombre de tu bucket.

El inconveniente para usar los registros A es que requieren una configuración y un uso adicional de recursos adicionales de Google Cloud. Consulta cómo configurar tu balanceador de cargas y certificado SSL para obtener una guía para usar dominios personalizados con registros A.

Registros CNAME

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

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

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

c.storage.googleapis.com.

Por ejemplo, supongamos que tu dominio es example.com y que deseas que los mapas de viaje estén disponibles para tus clientes. Puedes crear un bucket en Cloud Storage llamado travel-maps.example.com y, luego, crear un registro CNAME en el DNS que redireccione las solicitudes de travel-maps.example.com al URI de Cloud Storage. Para hacerlo, publica el siguiente registro CNAME en DNS:

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

Cuando hagas esto, tus clientes podrán usar la URL siguiente para acceder a un mapa de París:

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

El servicio de registro de tu dominio debe contar con una forma para que administres tu dominio, incluido un registro de recurso CNAME. Por ejemplo, si usas Cloud DNS, las instrucciones para agregar registros de recursos se pueden encontrar en la página Agrega, modifica y borra registros.

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

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

Compatibilidad con TLS mutua

TLS mutuo (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:

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

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

¿Qué sigue?

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