Acerca de los objetos de Cloud Storage

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

Objetos

Los objetos son los datos individuales que almacenas en Cloud Storage. No hay límite en la cantidad de objetos que puedes crear en un bucket.

Los objetos tienen dos componentes: datos de objeto y metadatos de objeto. Los datos de objeto suelen ser un archivo que deseas almacenar en Cloud Storage y son en su totalidad opacos para Cloud Storage. Los metadatos de objeto son una recopilación de pares nombre-valor en los que se describen varias calidades del objeto.

Dos partes importantes de los metadatos de objetos que son comunes de todos los objetos son el nombre del objeto y su número de generación. Cuando agregas un objeto a un bucket de Cloud Storage, debes especificar el nombre del objeto y Cloud Storage asigna el número de generación. Juntos, el nombre y la generación identifican de forma única el objeto dentro de ese bucket.

Puedes usar las listas de control de acceso (LCA) para controlar el acceso a objetos individuales. También puedes usar Identity and Access Management (IAM) para controlar el acceso a todos los objetos dentro de un bucket o una carpeta administrada.

Consideraciones de nombres

Cuando nombres objetos en Cloud Storage, es fundamental cumplir con requisitos específicos para garantizar la compatibilidad y evitar errores. Estos requisitos se aplican a los buckets con espacio de nombres plano y buckets con espacio de nombres jerárquico habilitado.

Requisitos generales

  • Los nombres de objetos pueden contener cualquier secuencia de caracteres Unicode válidos.
  • Los nombres de objetos no pueden contener caracteres de retorno de carro o salto de línea.
  • Los nombres de los objetos no pueden empezar con .well-known/acme-challenge/.
  • Los objetos no se pueden llamar . ni ...

Límites de tamaño de objetos específicos del espacio de nombres

El tamaño máximo de un nombre de objeto varía según el espacio de nombres del bucket:

  • Tamaño del nombre de objeto en un bucket de espacio de nombres plano: De 1 a 1,024 bytes con codificación UTF-8.

  • Tamaño del nombre de objeto en buckets habilitados con el espacio de nombres jerárquico: Los nombres de objetos se pueden dividir en dos partes:

    • Nombre de la carpeta: Es el nombre de la carpeta en la que reside el objeto. El tamaño máximo del nombre de la carpeta es de 512 bytes cuando está codificado en UTF-8.
    • Nombre base: Es el nombre del objeto que reside en la carpeta. El tamaño máximo del nombre base es de 512 bytes con codificación UTF-8.

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

Recomendaciones

Recomendamos que evites lo siguiente en los nombres de tus objetos:

  • Evita el uso de caracteres de control que sean ilegales en XML 1.0 (#x7F–#x84 y #x86–#x9F). Estos caracteres provocan problemas con las listas de XML cuando intentas hacer una lista de tus objetos.
  • El carácter #: los comandos de Google Cloud CLI interpretan los nombres de objetos que terminan en #<string numérica> como identificadores de versión, por lo que incluir # en los nombres de objetos puede dificultar los procesos o es imposible hacer operaciones en esos objetos con versión mediante gcloud CLI
  • 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 las operaciones de comodines. Además, * y ? no son caracteres válidos para los nombres de archivos en Windows.
  • Los caracteres :, ", <, > o |: No son caracteres válidos para los nombres de archivo en Windows, por lo que se intenta descargar un objeto que use caracteres en su nombre a un archivo de Windows fallan, 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 archivos en Windows, se suele aceptar su uso en nombres de objetos para imitar una estructura de directorio. Herramientas como \ y Google Cloud CLI convierten el carácter a `` de forma automática cuando se descarga en un entorno de Windows.
  • Información sensible o de identificación personal (PII): 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 de los objetos y cuando se enumeran objetos en un bucket.

No se puede cambiar el nombre de los objetos existentes de forma directa, pero puedes cambiar el nombre de un objeto de forma indirecta si copias y borras el objeto original.

Espacio de nombres del objeto

Puedes almacenar objetos en los siguientes espacios de nombres:

Espacio de nombres plano

Los buckets con un espacio de nombres plano almacenan objetos en una estructura plana sin jerarquía, lo que significa que no hay directorios ni carpetas.

Para mayor comodidad, hay varias formas en que los objetos se tratan como si se almacenaran en una jerarquía de carpetas:

Por ejemplo, si creas un objeto llamado folder1/file.txt en el bucket your-bucket, la ruta al objeto es your-bucket/folder1/file.txt y Cloud Storage no tiene una carpeta llamada folder1 almacenada. dentro de él. Desde la perspectiva de Cloud Storage, la string folder1/ es parte del nombre del objeto.

Sin embargo, debido a que el objeto tiene un / en su nombre, algunas herramientas implementan la apariencia de las carpetas. Por ejemplo, cuando usas la consola de Google Cloud, debes navegar 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 administrada llamada folder1 y, luego, file1.txt estará sujeto a la política de acceso que establece esta carpeta administrada.

Ten en cuenta que, debido a que los objetos residen en un espacio de nombres fijo, las estructuras anidadas similares a un directorio no tienen el rendimiento de un sistema de archivos nativo cuando se enumeran subdirectorios profundamente anidados.

Consulta las Prácticas recomendadas sobre el porcentaje de solicitudes para obtener recomendaciones sobre cómo optimizar el rendimiento si se evitan los nombres secuenciales durante las cargas a gran escala. Es probable que los objetos subidos con nombres secuenciales alcancen el mismo servidor de backend y limiten el rendimiento.

Carpetas simuladas

Para ayudarte a organizar objetos en tus buckets de Cloud Storage, algunas herramientas simulan carpetas y las API de JSON y XML tienen capacidades que te permiten diseñar tu propio esquema de nombres para simular carpetas. Haz clic en las siguientes pestañas para ver cómo las diferentes herramientas manejan las carpetas simuladas.

Console

La consola de Google Cloud crea una representación visual de las carpetas que son similares a un navegador de archivos local.

En la consola de Google Cloud, puedes crear una carpeta vacía en un bucket o subir una carpeta existente.

Cuando subes una carpeta existente, el nombre de la carpeta se vuelve parte de la ruta de acceso para todos los objetos contenidos en la carpeta. Todas las subcarpetas y los objetos que contienen también se incluyen en la carga.

Para crear una carpeta, haz lo siguiente:

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

    Ir a Buckets

  2. Navega al bucket.

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

Línea de comandos

Las CLI de Cloud Storage simulan la experiencia típica del directorio de línea de comandos con una variedad de reglas.

Para lograr la ilusión de un árbol jerárquico de archivos, a través de gcloud CLI se aplican las siguientes reglas para determinar si la URL de destino en un comando debe tratarse como un nombre de objeto o una carpeta:

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

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

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

  2. Si copias varios archivos fuente a una URL de destino, ya sea con la marca --recursive o un comodín, como **, gcloud CLI trata la URL de destino como una carpeta. Por ejemplo, observa el siguiente comando, en el que 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, se crean los objetos abc/top-dir/file1 y abc/top-dir/file2 en el bucket your-bucket mediante Cloud Storage

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

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

    A través de gcloud CLI se hace una solicitud de enumeración de objetos para your-bucket, con el delimitador / y el prefijo=abc, para determinar si hay objetos en your-bucket cuya ruta de acceso empieza con abc/. Si es así, gcloud CLI trata a abc/ como un nombre de carpeta y el comando crea el objeto abc/your-file en el bucket your-bucket. De lo contrario, se crea el objeto abc en your-bucket mediante gcloud CLI.

Este enfoque basado en reglas es diferente a la forma en que funcionan muchas herramientas, que crean objetos de 0 bytes para marcar la existencia de carpetas. La gcloud CLI comprende varias convenciones que usan estas herramientas, como la convención de agregar _$folder$ al final del nombre del objeto de 0 bytes, pero no es obligatorio. objetos de marcador para implementar comportamientos de nombres coherentes con los comandos UNIX.

Además de estas reglas, la forma en que gcloud CLI trata los archivos fuente depende de si usas o no la marca --recursive. Si usas la marca, gcloud CLI construye nombres de objetos para reflejar la estructura del directorio de código fuente, a partir del punto de procesamiento recursivo. Por ejemplo, observa el siguiente comando, en el que 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, se crean los objetos top-dir/file1 y top-dir/sub-dir/file2 en el bucket your-bucket mediante Cloud Storage

Por el contrario, copiar sin la marca --recursive, incluso si se copian varios archivos debido a la presencia de un comodín, como **, genera objetos con el nombre del componente de ruta de acceso final de los archivos de origen. Por ejemplo, si nuevamente suponemos que home/top-dir es una carpeta que contiene archivos como file1 y sub-dir/file2, el comando es el siguiente:

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

Crea un objeto llamado file1 y un objeto llamado file2 en el bucket your-bucket.

Reintentos y nombres

Cuando gcloud CLI vuelve a intentar una solicitud interrumpida, puede ocurrir un problema en el que el primer intento copia un subconjunto de archivos y los intentos posteriores encuentran una carpeta de destino existente, lo que hace que los objetos se nombren de forma incorrecta.

Por ejemplo, considera el siguiente comando, en el que 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 de acceso gs://your-bucket/new aún no existe, se crean los siguientes objetos en el primer intento exitoso mediante gcloud CLI:

new/dir1/abc
new/dir2/abc

Sin embargo, en el siguiente intento exitoso del mismo comando, se crean los siguientes objetos con gcloud CLI:

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

Para que gcloud CLI funcione de manera coherente en cada intento, intenta lo siguiente:

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

  2. Usar gcloud storage rsync. Dado que rsync no usa las reglas de nombres de carpetas definidas por cp de Unix, funciona con coherencia si la subcarpeta de destino existe o no.

Notas adicionales

  • No puedes crear un objeto de cero bytes para imitar una carpeta vacía mediante gcloud CLI

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

  • Si usas secuencias de comandos para compilar rutas de acceso a archivos a través de la combinación de rutas secundarias, ten en cuenta que, debido a que / es solo un carácter que está en nombre del objeto, las CLI interpretan que gs://your-bucket/folder/ es un objeto diferente de gs://your-bucket//folder.

API de REST

API de JSON

Las carpetas no existen en la API de JSON. Puedes limitar los objetos que listas y simular carpetas mediante los parámetros de búsqueda prefix y delimiter.

Por ejemplo, para enumerar todos los objetos en el bucket my-bucket con el prefijo folder/subfolder/, realiza una solicitud de listado de objetos con esta URL:

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

API de XML

Las carpetas no existen en la API de XML. Puedes limitar los objetos que listas y simular carpetas mediante prefix y delimiter parámetros de búsqueda

Por ejemplo, para enumerar todos los objetos en el bucket my-bucket con el prefijo folder/subfolder/, realiza una solicitud de listado de objetos con esta URL:

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

Quita carpetas simuladas

Debido a que las carpetas simuladas no existen, por lo general, puedes quitar carpetas simuladas si cambias el nombre de los objetos para que la carpeta simulada ya no forme parte del nombre del objeto. Por ejemplo, si tienes un objeto llamado folder1/file, puedes quitar la carpeta simulada folder1/ si cambias el nombre del objeto a solo file.

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

Espacio de nombres jerárquico

El espacio de nombres jerárquico te permite organizar objetos dentro de un bucket de Cloud Storage en un sistema de archivos, como una jerarquía de carpetas. El espacio de nombres jerárquico mejora el rendimiento y te ayuda a administrar tus datos de manera 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 de objetos

Los objetos son inmutables, lo que significa que un objeto subido no puede cambiar durante su ciclo de vida de almacenamiento. El ciclo de vida de almacenamiento de un objeto es el tiempo entre la creación correcta de un objeto, como cuando se sube un objeto, y la eliminación correcta de este. En la práctica, esto significa que no puedes hacer cambios incrementales en los objetos, como agregar o truncar operaciones. Sin embargo, es posible reemplazar objetos almacenados en Cloud Storage, lo que ocurre de manera atómica. La versión anterior del objeto se entrega a los lectores hasta que la carga nueva se complete y después de esto, se entrega a los lectores la versión nueva del objeto. Una operación de reemplazo única marca el final del ciclo de vida de un objeto inmutable y el inicio del ciclo de vida de un objeto inmutable nuevo.

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

Ten en cuenta que existe un límite de una vez por segundo para reemplazar de forma rápida el mismo objeto. Si reemplazas el mismo objeto con mayor frecuencia se pueden generar errores 429 Too Many Requests. Debes diseñar tu aplicación para que suba datos para un objeto en particular no más de una vez por segundo y para que controle errores 429 Too Many Requests ocasionales mediante una estrategia de reintento de retirada exponencial.

¿Qué sigue?