Solicita extremos

En esta página, se explican los diferentes extremos de solicitud (URI) que puedes usar para acceder a Cloud Storage. Cloud Storage admite los protocolos HTTP/1.1, HTTP/2 y HTTP/3.

Solicitudes a la API típicas

Cuando realizas solicitudes directamente a una de las API de Cloud Storage, usa los URI siguientes:

API de JSON

  • Para las solicitudes a la API de JSON generales, sin incluir las cargas de objetos, usa el siguiente extremo y reemplaza PLACEHOLDER por los valores adecuados:

    https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE
  • Para cargas de objeto de la API de JSON, usa el extremo siguiente y reemplaza PLACEHOLDER con los valores correctos:

    https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o
  • Para las solicitudes por lotes, usa el siguiente extremo y reemplaza PLACEHOLDER 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 PLACEHOLDER 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.

API de XML

  • Para las solicitudes a la API de XML, puedes usar el extremo de estilo de alojamiento virtual o el de estilo de ruta de acceso y reemplazar PLACEHOLDER por los valores adecuados:

    Estilo de alojamiento virtual:

    https://BUCKET_NAME.storage.googleapis.com/OBJECT_NAME
    Estilo de ruta de acceso:
    https://storage.googleapis.com/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 acceso del URI

Además de las consideraciones generales para la definición de nombres de depósitos y de objetos, a fin de garantizar la compatibilidad entre las herramientas de Cloud Storage, debes codificar los siguientes caracteres cuando aparezcan en el nombre del objeto o en la string de consulta del URI 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 URI de solicitud debe ser el 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.

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

Extremos de Cloud Console

Cuando usas Cloud Console, puedes acceder a diferentes recursos medianre las siguientes URL:

Recurso URL
Lista de depósitos 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

Extremos de gsutil

De forma predeterminada, gsutil accede a Cloud Storage a través de los extremos de solicitud de la API de JSON. Para controlar este valor predeterminado, configura la variable prefer_api en la sección "GSUtil" del archivo de configuración.boto en xml o json de la siguiente manera:

prefer_api = xml

Aunque gsutil usa la API preferida cuando es posible, si no es posible, gsutil recurre de manera silenciosa a la otra API. Por ejemplo, el comando ubla no es compatible con la API de XML, por lo que gsutil siempre usa la API de JSON para ese comando. Del mismo modo, gsutil siempre usa la API de XML cuando interactúa con proveedores de almacenamiento en la nube que no son compatibles con la API de JSON.

Consideraciones de rendimiento y costo

La API de XML usa el framework boto. Este framework vuelve a leer los archivos descargados para calcular un hash MD5 si no hay uno presente. En el caso de los objetos que no incluyen hashes MD5 en sus metadatos, como los objetos compuestos, esto duplica el ancho de banda consumido y el tiempo transcurrido que se necesita para la descarga. Si trabajas con objetos compuestos, debes evitar configurar prefer_api en xml.

La API de XML también requiere llamadas separadas para obtener diferentes campos de metadatos de objetos y depósitos, como las configuraciones de depósito. Usar la API de JSON siempre que sea posible usa menos operaciones y tiene un costo menor.

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 a fin de 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, se debe agregar el siguiente URI a la parte del nombre del host de tu registro CNAME:

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 depósito 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 Google Domains, las instrucciones para agregar un registro de recurso se pueden encontrar en la página de ayuda de Google Domains, en la sección desplegable Registros de recursos.

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 Google para establecer su identidad. La Cuenta de Google 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 de Google del usuario debe tener el permiso storage.objects.viewer, que se obtiene en el Visualizador de objetos de almacenamiento.

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

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

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

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

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 URI storage.googleapis.com documentado en Solicitudes a la API típicas. Para obtener más detalles y ejemplos, consulta Accede a datos públicos.

Pasos siguientes