En esta página se describe cómo usar los endpoints de ubicación para acceder a Cloud Storage. Si usas endpoints de ubicación, puedes asegurarte de que tus datos en reposo permanezcan en la jurisdicción correspondiente para cumplir los requisitos de residencia de datos.
Información general
Los endpoints de ubicación son endpoints de solicitud que solo permiten que las solicitudes se completen si el recurso afectado se encuentra en la ubicación especificada por el endpoint. Por ejemplo, cuando usas el endpoint https://us-central1-storage.googleapis.com en una solicitud para eliminar un segmento, la solicitud solo se procesa si el segmento se encuentra en US-CENTRAL1.
A diferencia de los endpoints globales, en los que las solicitudes se pueden procesar en una ubicación diferente a la del recurso, los endpoints de ubicación garantizan que las solicitudes se procesen únicamente en la ubicación especificada por el endpoint, que es donde reside el recurso.
Si usas endpoints de ubicación, te aseguras de lo siguiente:
Los datos almacenados en Cloud Storage no salen de la ubicación especificada.
Tus datos se terminan con TLS en la región especificada por el endpoint cuando se transfieren de las instalaciones locales a Google Cloud.
Al usar endpoints de ubicación, asumes las siguientes responsabilidades:
Para obtener garantías de residencia de datos, las solicitudes realizadas a un endpoint de ubicación deben proceder de la misma ubicación que se especifica en el endpoint. Por ejemplo, si usas una máquina virtual de Compute Engine para enviar una solicitud a un bucket ubicado en
US-CENTRAL1a través del endpointus-central1-storage.googleapis.com, la máquina virtual también debe estar ubicada enUS-CENTRAL1.Los endpoints de ubicación solo se deben usar al realizar operaciones admitidas. Si se realizan operaciones no admitidas, se produce un error.
Los endpoints de ubicación admiten el tráfico entre las instalaciones locales y Google Cloud a través de Interconnect o VPN, así como el tráfico entre servicios de Google Cloud (por ejemplo, de BigQuery a Cloud Storage). No se admite el tráfico de Internet.
Operaciones admitidas
En la siguiente tabla se resumen las operaciones que se pueden y no se pueden realizar con los endpoints de ubicación. Por lo general, las operaciones dentro de una misma ubicación se pueden realizar con endpoints de ubicación, mientras que las operaciones entre ubicaciones no.
Si intentas realizar una operación no admitida mediante un endpoint de ubicación, Cloud Storage devuelve un código de error HTTP 400 con el mensaje "This endpoint does not implement this operation. Usa el endpoint global".
| Operación | Modifica los datos del objeto. | Se admite el uso con endpoints de ubicación |
|---|---|---|
| objetos compuestos | Sí | Sí1 |
| objects delete | No | Sí1 |
| objects get | Sí | Sí1 |
| insertar objetos | Sí | Sí1 |
| lista de objetos | No | Sí1 |
| parche de objetos | No | Sí1 |
| copia de objetos | Sí | Sí4 |
| reescritura de objetos | Sí | Sí4 |
| insertar segmentos | No | Sí2 |
| buckets delete | No | Sí3 |
| buckets get | No | Sí2 |
| Parche de segmentos | No | Sí2 |
| Actualización de los contenedores | No | Sí2 |
| buckets getIamPolicy | No | Sí2 |
| buckets setIamPolicy | No | Sí2 |
| buckets testIamPermissions | No | Sí2 |
| buckets lockRetentionPolicy | No | Sí2 |
| buckets BucketAccessControls | No | Sí2 |
| buckets DefaultObjectAccessControls | No | Sí2 |
| buckets ObjectAccessControls | No | Sí2 |
| Operaciones con claves HMAC | No | No |
| Operaciones de cuentas de servicio | No | No |
| Operaciones de notificación de Pub/Sub | Varía según la operación | No |
| Operaciones de notificación de cambios en objetos | Varía según la operación | No |
| Operaciones por lotes | Varía según la operación | No |
1 Para realizar esta operación con endpoints de ubicación, el contenedor que contiene el objeto afectado debe existir en la ubicación especificada por el endpoint. Por ejemplo, una solicitud de eliminación de un objeto en us-central1-storage.googleapis.com solo se puede usar para eliminar objetos de los contenedores que se encuentran en la región US-CENTRAL1. Si intentas eliminar un objeto
en una ubicación que no sea US-CENTRAL1, la operación devolverá un error NOT_FOUND.
2 Para realizar esta operación mediante endpoints de ubicación, el bucket debe existir en la ubicación especificada por el endpoint. Por ejemplo, una solicitud de creación de un contenedor en us-central1-storage.googleapis.com solo se puede usar para crear un contenedor en la región US-CENTRAL1. Si intentas crear el contenedor en una ubicación que no sea US-CENTRAL1, la operación devolverá un error INVALID_ARGUMENT.
3 Para realizar esta operación mediante puntos de conexión de ubicación, el segmento debe existir en la ubicación especificada por el punto de conexión. Por ejemplo, una solicitud de eliminación de un
contenedor de us-central1-storage.googleapis.com solo se puede usar para eliminar un
contenedor de la región US-CENTRAL1. Si intentas eliminar un contenedor en una ubicación que no sea US-CENTRAL1, la operación devuelve un error NOT_FOUND.
4 Para realizar esta operación con endpoints de ubicación, los segmentos de origen y destino deben estar en la ubicación especificada por el endpoint. Por ejemplo, puede usar endpoints de ubicación para copiar un objeto de un contenedor a otro si ambos contenedores están en la misma ubicación. Sin embargo, no puedes usar endpoints de ubicación para copiar un objeto de un segmento a otro si los segmentos están en ubicaciones diferentes. Si el contenedor de origen o de destino se encuentra en una ubicación diferente a la especificada en el endpoint, la operación devuelve un error NOT_FOUND.
Regiones disponibles
Los endpoints de ubicación se admiten en todas las regiones de EE. UU., en la multirregión US y en la birregión predefinida NAM4. Para obtener más información sobre las regiones que se pueden especificar, consulta Ubicaciones de segmentos.
Hacer solicitudes
Consola
Consulta Restricciones y limitaciones de ITAR para obtener información sobre cómo realizar operaciones con la consola Google Cloud de forma que cumplan los requisitos de ITAR.
Línea de comandos
Para configurar Google Cloud CLI para usarlo con endpoints de ubicación, sigue estos pasos:
Asigna a la propiedad
api_endpoint_overrides/storageel endpoint de ubicación que quieras usar:gcloud config set api_endpoint_overrides/storage https://LOCATION-storage.googleapis.com/
Una vez que se haya definido esta propiedad, podrá usar los comandos de la CLI de gcloud como lo haría normalmente.
También puedes usar endpoints de ubicación para comandos individuales configurando la variable de entorno CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE en cada comando. Por ejemplo:
CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE=https://LOCATION-storage.googleapis.com/ gcloud ls gs://my-bucket
Bibliotecas de cliente
Las bibliotecas de cliente de Cloud Storage gestionan los endpoints de las solicitudes automáticamente, pero puedes definir endpoints de ubicación manualmente. Para saber cómo definir endpoints de ubicación, consulta los ejemplos de código de la biblioteca de cliente que usan endpoints de solicitud.
APIs REST
API JSON
Cuando hagas solicitudes a endpoints de ubicación, usa los siguientes URIs:
Para las solicitudes generales de la API JSON, excepto las subidas de objetos, utiliza el siguiente endpoint:
https://LOCATION-storage.googleapis.com
Sustituye LOCATION por una ubicación de contenedor admitida. Por ejemplo,
us-central1.Para subir objetos de la API JSON, utiliza el siguiente endpoint:
https://LOCATION-storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o
Sustituye:
LOCATION con una ubicación de segmento admitida. Por ejemplo,
us-central1.BUCKET_NAME con el nombre del contenedor al que quieras subir un objeto. Por ejemplo,
my-example-bucket.
Para descargar objetos de la API JSON, utiliza el siguiente endpoint:
https://LOCATION-storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media
Sustituye:
LOCATION con una ubicación de segmento admitida. Por ejemplo,
us-central1.BUCKET_NAME con el nombre del segmento que contiene el objeto que quieres descargar. Por ejemplo,
my-example-bucket.OBJECT_NAME con el nombre del objeto que quieras descargar. Por ejemplo,
waterfall.png.
Ten en cuenta que los endpoints de la API JSON solo admiten solicitudes HTTPS.
API XML
Cuando usas la API XML para enviar solicitudes a endpoints de ubicación, puedes usar un endpoint de estilo de host virtual o un endpoint de estilo de ruta:
Endpoint de estilo alojado virtual:
https://BUCKET_NAME.LOCATION-storage.googleapis.com
Endpoint de estilo de ruta:
https://LOCATION-storage.googleapis.com/BUCKET_NAME
En ambos tipos de endpoint, sustituye lo siguiente:
LOCATION con una ubicación de segmento admitida. Por ejemplo,
us-central1.BUCKET_NAME con un nombre de segmento válido. Por ejemplo,
my-example-bucket.
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.
Formatear las solicitudes correctamente
Para asegurarte de que tus solicitudes sean compatibles con las herramientas de Cloud Storage, sigue estas recomendaciones:
Asegúrate de codificar correctamente los caracteres especiales que aparecen en el nombre del objeto o en la cadena de consulta de un URI de solicitud.
Familiarícese con las directrices para asignar nombres a los segmentos y las consideraciones para asignar nombres a los objetos.
Restricciones conocidas
No se admiten endpoints de mTLS.
Restringir el uso de puntos de conexión de API globales
Para ayudar a aplicar el uso de endpoints de ubicación, puedes usar la restricción de política de organización constraints/gcp.restrictEndpointUsage para bloquear las solicitudes al endpoint de la API global. Para obtener más información, consulta la documentación sobre cómo restringir el uso de endpoints.