Acerca de los objetos de Cloud Storage

En esta página se describen los objetos, que son recursos de Cloud Storage. Para obtener una descripción general de cómo funciona Cloud Storage, consulta la descripción general del producto Cloud Storage.

Objetos

Los objetos son las partes individuales de los datos que almacenas en Cloud Storage. No hay límite en cuanto al número de objetos que puedes crear en un segmento.

Los objetos tienen dos componentes: datos del objeto y metadatos del objeto. Los datos de los objetos suelen ser archivos que quieres almacenar en Cloud Storage y que son completamente opacos para Cloud Storage. Los metadatos de un objeto son una colección de pares nombre-valor que describen varias cualidades del objeto.

Dos metadatos de objeto importantes que son comunes a todos los objetos son el nombre del objeto y su número de generación. Cuando añades un objeto a un segmento de Cloud Storage, especificas el nombre del objeto y Cloud Storage le asigna el número de generación. El nombre y la generación identifican de forma única el objeto en ese contenedor.

Puedes usar listas de control de acceso (LCA) para controlar el acceso a objetos concretos. También puedes usar Gestión de Identidades y Accesos (IAM) para controlar el acceso a todos los objetos de un segmento o una carpeta gestionada.

Consideraciones sobre los nombres

Al asignar nombres a los objetos de Cloud Storage, es fundamental cumplir ciertos requisitos para garantizar la compatibilidad y evitar errores. Estos requisitos se aplican tanto a los segmentos de espacio de nombres plano como a los segmentos con espacio de nombres jerárquico habilitado.

Requisitos generales

  • Los nombres de los objetos pueden contener cualquier secuencia de caracteres Unicode válidos.
  • Los nombres de los objetos no pueden contener retornos de carro ni avances de línea.
    • Ten en cuenta que las barras invertidas que se envían a través de interfaces como la CLI de gcloud y la consola se escapan de forma interna. Google Cloud Por ejemplo, \n se convierte en \\n. La restricción de retorno de carro y salto de línea se refiere estrictamente a los caracteres de escape ANSI.
  • Los nombres de objeto no pueden empezar por .well-known/acme-challenge/.
  • Los objetos no pueden llamarse . ni ...

Límites de tamaño de objetos específicos de espacios de nombres

El tamaño máximo de un nombre de objeto varía en función del espacio de nombres del cubo:

  • Tamaño del nombre del objeto en un segmento de espacio de nombres plano: de 1 a 1024 bytes cuando se codifica en UTF-8.

  • Tamaño del nombre de objeto en los segmentos habilitados con espacio de nombres jerárquico: los nombres de objeto se pueden dividir en dos partes:

    • Nombre de la carpeta: el nombre de la carpeta en la que se encuentra el objeto. El tamaño máximo del nombre de la carpeta es de 512 bytes cuando se codifica en UTF-8.
    • Nombre base: nombre del objeto que reside en la carpeta. El tamaño máximo del nombre base es de 512 bytes cuando se codifica en UTF-8.

    Por ejemplo, la ruta my-folder/my-object.txt representa un objeto con el nombre base my-object.txt almacenado en una carpeta llamada my-folder/.

Recomendaciones

Te recomendamos que evites lo siguiente en los nombres de los objetos:

  • Caracteres de control no permitidos en XML 1.0 (#x7F–#x84 y #x86–#x9F): estos caracteres provocan problemas en las fichas XML cuando intenta mostrar sus objetos.
  • El carácter #: los comandos de la CLI de Google Cloud interpretan los nombres de objetos que terminan en #<cadena numérica> como identificadores de versión, por lo que incluir # en los nombres de objetos puede dificultar o imposibilitar la realización de operaciones en dichos objetos versionados con la CLI de gcloud.
  • Los caracteres [, ], * o ?: los comandos de Google Cloud CLI interpretan estos caracteres como comodines, por lo que incluirlos en los nombres de los objetos puede dificultar o imposibilitar la realización de operaciones con comodines. Además, * y ? no son caracteres válidos para los nombres de archivo en Windows.
  • Los caracteres :, ", <, > o |: no son caracteres válidos para los nombres de archivo en Windows, por lo que los intentos de descargar un objeto que utilice estos caracteres en su nombre en un archivo de Windows fallarán a menos que el método de descarga incluya el cambio de nombre del archivo de Windows resultante. El carácter /, aunque tampoco es un carácter válido para los nombres de archivo en Windows, se puede usar en los nombres de objeto para imitar una estructura de directorios. Herramientas como la CLI de Google Cloud convierten automáticamente el carácter en \ al descargar en un entorno de Windows.
  • Información sensible o de identificación personal (IIP): los nombres de los objetos son más visibles que los datos de los objetos. Por ejemplo, los nombres de los objetos aparecen en las URLs del objeto y al enumerar los objetos de un segmento.

No se puede cambiar el nombre de los objetos directamente, pero puedes cambiar el nombre de un objeto indirectamente copiándolo y eliminando el original.

Espacio de nombres de objeto

Puedes almacenar objetos en los siguientes espacios de nombres:

Espacio de nombres plano

Los segmentos configurados para almacenar objetos en un espacio de nombres plano siempre crean objetos directamente en el segmento. En estos segmentos de espacio de nombres plano, no hay jerarquía dentro del segmento y no hay directorios ni carpetas en los que se encuentren los objetos.

Para mayor comodidad, los objetos de los contenedores con espacios de nombres planos se tratan como si estuvieran almacenados en una jerarquía de carpetas de varias formas:

  • Las carpetas gestionadas son un recurso de Cloud Storage que proporciona acceso ampliado a grupos de objetos con un prefijo de nombre compartido.

  • Herramientas como Google Cloud console y la CLI de Google Cloud interpretan el carácter de barra (/) en el nombre de un objeto como un delimitador para simular carpetas en los segmentos que usan un espacio de nombres plano para los objetos.

Por ejemplo, si creas un objeto llamado folder1/file.txt en el segmento your-bucket, la ruta al objeto es your-bucket/folder1/file.txt y Cloud Storage no tiene ninguna carpeta llamada folder1 almacenada en él. Desde el punto de vista de Cloud Storage, la cadena folder1/ forma parte del nombre del objeto.

Sin embargo, como el objeto tiene un / en su nombre, algunas herramientas implementan la apariencia de las carpetas. Por ejemplo, al usar la consola Google Cloud , te desplazarías al objeto folder1/file1.txt como si fuera un objeto llamado file1.txt en una carpeta llamada folder1. Del mismo modo, puedes crear una carpeta gestionada llamada folder1 y, a continuación, file1.txt estará sujeta a la política de acceso definida por esta carpeta gestionada.

Ten en cuenta que, como los objetos residen en un espacio de nombres plano, las estructuras anidadas en profundidad, como los directorios, no tienen el mismo rendimiento que un sistema de archivos nativo al enumerar subdirectorios anidados en profundidad.

Consulta las prácticas recomendadas para la frecuencia de solicitudes para obtener recomendaciones sobre cómo optimizar el rendimiento evitando los nombres secuenciales durante las subidas a gran escala. Es probable que los objetos subidos con nombres secuenciales lleguen al mismo servidor backend y limiten el rendimiento.

Carpetas simuladas

Para ayudarte a organizar los objetos de tus depósitos de Cloud Storage, algunas herramientas simulan carpetas. Además, las APIs JSON y XML tienen funciones que te permiten diseñar tu propio esquema de nomenclatura para simular carpetas. Haga clic en las siguientes pestañas para ver cómo gestionan las carpetas simuladas las diferentes herramientas.

Consola

La consola Google Cloud crea una representación visual de las carpetas que se parece a un explorador de archivos local.

En la consola de Google Cloud , puedes crear una carpeta vacía en un contenedor o subir una carpeta que ya tengas.

Cuando subes una carpeta, el nombre de la carpeta pasa a formar parte de la ruta de todos los objetos que contiene. Las subcarpetas y los objetos que contengan también se incluirán en la subida.

Para crear una carpeta, sigue estos pasos:

  1. En la Google Cloud consola, ve a la página Segmentos de Cloud Storage.

    Ir a Contenedores

  2. Desplázate hasta el contenedor.

  3. Haz clic en Crear carpeta para crear una carpeta vacía o en Subir carpeta para subir una carpeta.

Línea de comandos

Las CLIs de Cloud Storage simulan la experiencia típica de los directorios de línea de comandos mediante varias reglas.

Para conseguir la ilusión de un árbol de archivos jerárquico, la CLI de gcloud aplica las siguientes reglas para determinar si la URL de destino de un comando debe tratarse como un nombre de objeto o como una carpeta:

  1. Si la URL de destino termina con el carácter /, los comandos de la CLI de gcloud tratan la URL de destino como una carpeta. Por ejemplo, considera el siguiente comando, donde your-file es el nombre de un archivo:

    gcloud storage cp your-file gs://your-bucket/abc/

    Como resultado de este comando, Cloud Storage crea un objeto llamado abc/your-file en el segmento your-bucket.

  2. Si copias varios archivos de origen en una URL de destino, ya sea con la marca --recursive o con un comodín, como **, la CLI de gcloud tratará la URL de destino como una carpeta. Por ejemplo, considere el siguiente comando, donde top-dir es una carpeta que contiene archivos como file1 y file2:

    gcloud storage cp top-dir gs://your-bucket/abc --recursive

    Como resultado de este comando, Cloud Storage crea los objetos abc/top-dir/file1 y abc/top-dir/file2 en el segmento your-bucket.

  3. Si no se aplica ninguna de estas reglas, la CLI de gcloud comprueba los objetos del contenedor para determinar si la URL de destino es un nombre de objeto o una carpeta. Por ejemplo, considera el siguiente comando, donde your-file es el nombre de un archivo:

    gcloud storage cp your-file gs://your-bucket/abc

    La CLI de gcloud hace una solicitud de lista de objetos para your-bucket, usando el delimitador / y el prefijo abc, para determinar si hay objetos en your-bucket cuya ruta empieza por abc/. Si es así, la CLI de gcloud trata abc/ como nombre de carpeta y el comando crea el objeto abc/your-file en el contenedor your-bucket. De lo contrario, gcloud CLI crea el objeto abc en your-bucket.

Este enfoque basado en reglas es diferente de la forma en que funcionan muchas herramientas, que crean objetos de 0 bytes para marcar la existencia de carpetas. La CLI de gcloud reconoce varias convenciones que utilizan estas herramientas, como la convención de añadir _$folder$ al final del nombre del objeto de 0 bytes, pero no requiere que estos objetos de marcador implementen un comportamiento de nomenclatura coherente con los comandos de UNIX.

Además de estas reglas, la forma en que gcloud CLI trata los archivos de origen depende de si usas o no la marca --recursive. Si usas la marca, la CLI de gcloud crea nombres de objeto que reflejan la estructura del directorio de origen, empezando por el punto de procesamiento recursivo. Por ejemplo, considere el siguiente comando, donde home/top-dir es una carpeta que contiene archivos como file1 y sub-dir/file2:

gcloud storage cp home/top-dir gs://your-bucket --recursive

Como resultado de este comando, Cloud Storage crea los objetos top-dir/file1 y top-dir/sub-dir/file2 en el segmento your-bucket.

Por el contrario, si se copian archivos sin la marca --recursive, aunque se copien varios archivos debido a la presencia de un comodín como **, los objetos se denominarán con el último componente de la ruta de los archivos de origen. Por ejemplo, si home/top-dir es una carpeta que contiene archivos como file1 y sub-dir/file2, el comando:

gcloud storage cp home/top-dir/** gs://your-bucket

crea un objeto llamado file1 y otro llamado file2 en el cubo your-bucket.

Reintentos y nomenclatura

Cuando la CLI de gcloud vuelve a intentar enviar una solicitud interrumpida, puede que se produzca un problema en el que el primer intento copie un subconjunto de archivos y los intentos posteriores se encuentren con una carpeta de destino que ya existe, lo que provoca que los objetos se nombren incorrectamente.

Por ejemplo, considere el siguiente comando, donde hay subcarpetas en your-dir/, como dir1 y dir2, y ambas subcarpetas contienen el archivo abc:

gcloud storage cp ./your-dir gs://your-bucket/new --recursive

Si la ruta gs://your-bucket/new aún no existe, la CLI de gcloud crea los siguientes objetos en el primer intento correcto:

new/dir1/abc
new/dir2/abc

Sin embargo, en el siguiente intento correcto del mismo comando, la CLI de gcloud crea los siguientes objetos:

new/your-dir/dir1/abc
new/your-dir/dir2/abc

Para que gcloud CLI funcione de forma coherente en cada intento, prueba lo siguiente:

  1. Añade una barra al final de la URL de destino para que la CLI de gcloud siempre la trate como una carpeta.

  2. Utiliza gcloud storage rsync. Como rsync no usa las reglas de nomenclatura de carpetas definidas por Unix cp, funciona de forma coherente tanto si la subcarpeta de destino existe como si no.

Notas adicionales

  • No puedes crear un objeto de cero bytes para simular una carpeta vacía con la CLI de gcloud.

  • Cuando se descarga en un sistema de archivos local, la CLI de gcloud omite los objetos cuyo nombre termina con el carácter /, ya que no se permite crear un archivo que termine con / en Linux y macOS.

  • Si usas secuencias de comandos para crear rutas de archivo combinando subrutas, ten en cuenta que, como / es solo un carácter que se encuentra en el nombre del objeto, las CLIs interpretan gs://your-bucket/folder/ como un objeto diferente de gs://your-bucket/folder.

APIs REST

API JSON

Las carpetas no existen en la API JSON. Puede acotar los objetos que enumera y simular carpetas mediante los parámetros de consulta prefix y delimiter.

Por ejemplo, para mostrar todos los objetos del segmento my-bucket con el prefijo folder/subfolder/, haz una solicitud de lista de objetos con esta URL:

"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"

API XML

Las carpetas no existen en la API XML. Puedes acotar los objetos que incluyes en la lista y simular carpetas usando los parámetros de consulta prefix y delimiter.

Por ejemplo, para mostrar todos los objetos del segmento my-bucket con el prefijo folder/subfolder/, haz una solicitud de lista de objetos con esta URL:

"https://storage.googleapis.com/my-bucket?prefix=folder/subfolder/"

Eliminar carpetas simuladas

Como las carpetas simuladas no existen, normalmente puedes eliminarlas cambiando el nombre de los objetos para que la carpeta simulada deje de formar parte del nombre del objeto. Por ejemplo, si tienes un objeto llamado folder1/file, puedes quitar la carpeta simulada folder1/ cambiando el nombre del objeto a file.

Sin embargo, si has usado una herramienta que crea objetos de cero bytes como marcadores de posición de carpetas, como la consola Google Cloud , debes eliminar el objeto de cero bytes para quitar la carpeta.

Espacio de nombres jerárquico

El espacio de nombres jerárquico te permite organizar los objetos de un segmento de Cloud Storage en una jerarquía de carpetas similar a la de un sistema de archivos. El espacio de nombres jerárquico mejora el rendimiento y te ayuda a gestionar tus datos de forma eficiente. Para obtener más información sobre el espacio de nombres jerárquico y cuándo usarlo, consulta Espacio de nombres jerárquico.

Inmutabilidad del objeto

Los objetos son inmutables, lo que significa que un objeto subido no puede cambiar durante su tiempo de almacenamiento. El tiempo de conservación de un objeto es el tiempo que transcurre entre la creación correcta del objeto (por ejemplo, la subida) y la eliminación correcta del objeto. En la práctica, esto significa que no puedes hacer cambios incrementales en los objetos, como operaciones de anexión o de truncamiento. Sin embargo, es posible sustituir objetos almacenados en Cloud Storage, y esta acción se realiza de forma atómica: hasta que se completa la nueva subida, se sirve a los lectores la versión antigua del objeto y, una vez completada la subida, se sirve a los lectores la nueva versión del objeto. Una sola operación de sustitución marca el final del tiempo de vida de un objeto inmutable y el inicio del tiempo de vida de un nuevo objeto inmutable.

El número de generación de un objeto cambia cada vez que sustituyes los datos del objeto. Por lo tanto, el número de generación identifica de forma única un objeto inmutable.

Ten en cuenta que hay un límite de una vez por segundo para sustituir rápidamente el mismo objeto. Si sustituye el mismo objeto con más frecuencia, es posible que se produzcan errores 429 Too Many Requests. Debes diseñar tu aplicación para que suba datos de un objeto concreto no más de una vez por segundo y para que gestione los errores 429 Too Many Requests ocasionales mediante una estrategia de reintentos con tiempo de espera exponencial.

Siguientes pasos