Metadatos del objeto

Administrar

En esta página, se analizan los campos de metadatos de uso general que se almacenan junto con objetos en Cloud Storage.

Introducción

Los objetos almacenados en Cloud Storage tienen metadatos asociados a ellos. Los metadatos identifican las propiedades del objeto y especifican cómo se lo debe controlar cuando se accede a él. Los metadatos existen como pares clave-valor. Por ejemplo, la clase de almacenamiento de un objeto se representa mediante la entrada de metadatos storageClass:STANDARD. storageClass es la clave para los metadatos. Todos los objetos tienen una clave similar asociada. STANDARD especifica el valor que tiene este objeto en particular y el valor varía de objeto a objeto.

La mutabilidad de los metadatos varía: a algunos metadatos los puedes editar en cualquier momento, a algunos los puedes configurar solo en el momento en el que se crean y a otros solo los puedes visualizar. Por ejemplo, puedes editar el valor de los metadatos Cache-Control en cualquier momento, pero solo puedes asignar los metadatos storageClass cuando se crea o se reescribe el objeto y no puedes editar de forma directa el valor de los metadatos generation, aunque el valor de generation cambia cuando se reemplaza el objeto.

Metadatos editables

Existen dos categorías de metadatos que los usuarios pueden cambiar por objetos:

  • Metadatos de clave fija: metadatos en los que las claves están configuradas, pero para los que puedes especificar un valor.

  • Metadatos personalizados: metadatos que agregas cuando especificas una clave y un valor asociado con la clave.

Cuando editas metadatos, debes evitar caracteres que no sean ASCII debido a que no están permitidos en los encabezados HTTP que usa la API de XML.

Metadatos de clave fija

Puedes editar los metadatos siguientes para los objetos, aunque debes tener permiso suficiente si quieres hacerlo:

Metadatos de control de acceso

Cloud Storage usa Identity and Access Management (IAM) y listas de control de acceso (LCA) para controlar el acceso a los objetos. Usa estos vínculos para obtener más información sobre estos métodos de control de acceso y metadatos asociados.

Cache-Control

Los metadatos Cache-Control pueden especificar dos aspectos diferentes de cómo se entregan los datos de Cloud Storage: si los datos se pueden almacenar en caché y si se pueden transformar.

Almacena datos en caché

Los metadatos Cache-Control te permiten controlar si las cachés pueden almacenar en caché tus objetos y durante cuánto tiempo pueden hacerlo. Luego estos objetos se pueden entregar para satisfacer solicitudes futuras. Las memorias caché pueden incluir cachés del navegador y de Internet, así como almacenamiento en caché integrado de Cloud Storage.

Si un objeto aplicable no tiene una entrada de metadatos Cache-Control, Cloud Storage usa el siguiente valor predeterminado:

Si permites que se almacene en caché, las descargas pueden continuar recibiendo versiones anteriores de un objeto, incluso después de subir una versión más nueva. Esto se debe a que esas versiones anteriores permanecen “activas” en las memorias caché durante un período determinado por el max-age. Además, debido a que los objetos se pueden almacenar en caché en varias ubicaciones de Internet, no hay manera de forzar el vencimiento de un objeto almacenado en caché de forma global. Significa que si revocas el acceso público a un objeto, este aún se puede entregar desde una caché, según cuándo se accedió por última vez y su configuración de Cache-Control. Por ejemplo, si tu objeto se entregó con un Cache-Control de public, max-age=3600, puede persistir en una caché durante una hora. Si quieres evitar que se entreguen versiones almacenadas en caché de objetos que se pueden leer de forma pública, configura Cache-Control: no-store en el objeto.

Si necesitas un mayor control sobre el comportamiento de la caché, puedes configurar Cloud CDN frente al bucket.

Transforma datos

Los metadatos Cache-Control también te permiten entregar objetos como están almacenados, sin aplicar ninguna transformación a los datos, como quitar la codificación de contenido gzip para los clientes que no son compatibles. Para entregar un objeto tal como es, configura Cache-Control:no-transform.

Content-Disposition

Los metadatos Content-Disposition especifican información de presentación de los datos que se transmiten. La configuración Content-Disposition te permite controlar el estilo de presentación del contenido, por ejemplo, determinar si un adjunto se debe mostrar de forma automática o si se requiere que el usuario realice alguna acción para abrirlo. Consulta https://datatracker.ietf.org/doc/html/rfc6266 para ver la especificación Content-Disposition.

Content-Encoding

Los metadatos Content-Encoding se pueden usar para indicar que un objeto está comprimido y, al mismo tiempo, mantener el Content-Type subyacente del objeto. Por ejemplo, para un archivo de texto comprimido en gzip, el hecho de que es un archivo de texto se puede indicar en Content-Type y en Content-Encoding, se puede indicar que está comprimido en gzip. Te debes asegurar de que los archivos se compriman con el Content-Encoding especificado antes de subirlos, de lo contrario, puede ocurrir un comportamiento inesperado cuando se intenten descargar los objetos. Para obtener más información, consulta la página de transcodificación.

Para el contenido que se puede comprimir, como el texto, el uso de Content-Encoding: gzip ahorra costos de red y almacenamiento, y mejora el rendimiento de la entrega del contenido. Sin embargo, para el contenido ya comprimido de manera inherente, como los archivos y muchos formatos de contenido multimedia, aplicar otro nivel de compresión y marcarlo en los metadatos Content-Encoding suele ser perjudicial para el tamaño y el rendimiento del objeto, por lo que debe evitarse.

Content-Language

Los metadatos Content-Language indican los lenguajes para los que está destinado el objeto. Consulta los códigos de lenguajes ISO 639-1 para los valores típicos de estos metadatos.

Cloud Storage admite valores Content-Language de hasta 100 caracteres.

Content-Type

Los metadatos que se configuran con mayor frecuencia son Content-Type (también conocidos como tipo de medio), que permiten que los navegadores procesen el objeto de forma adecuada. Todos los objetos tienen un valor especificado en sus metadatos Content-Type, pero este valor no tiene que coincidir con el tipo subyacente del objeto. Por ejemplo, si quien lo sube no especifica el Content-Type y este no se puede determinar, se configura en application/octet-stream o application/x-www-form-urlencoded, según cómo subiste el objeto. Para ver una lista de los tipos de contenido válidos, consulta la página Tipos de medios de IANA.

Custom-Time

Los metadatos Custom-Time son una fecha y hora especificadas por el usuario que se representan en el formato YYYY-MM-DD'T'HH:MM:SS.SS'Z' o YYYY-MM-DD'T'HH:MM:SS'Z' de RFC 3339 cuando los milisegundos son cero. Por lo general, estos metadatos se configuran para usar la condición DaysSinceCustomTime en la Administración del ciclo de vida de los objetos.

No puedes quitar Custom-Time una vez configurado en un objeto. Además, el valor de Custom-Time no puede disminuir. Es decir, no puedes configurar Custom-Time para que sea una fecha y hora anteriores a la Custom-Time existente. Sin embargo, puedes quitar o restablecer los metadatos Custom-Time mediante la reescritura del objeto.

Conservaciones de objetos

Usa marcas de metadatos para colocar conservaciones de objetos, lo que impedirá que se borren o reemplacen objetos. Para obtener más información, consulta la página de conservaciones de objetos.

Configuración de la retención

Cuando está presente, la configuración de retención de un objeto define una fecha y una hora anteriores a las cuales el objeto no se puede borrar ni reemplazar. Consulta Bloqueo de retención de objetos para obtener más información.

Metadatos personalizados

Los metadatos personalizados son metadatos para los que defines la clave y el valor. Para crear metadatos personalizados, especifica una clave y un valor. Una vez que hayas creado un par de metadatos personalizados key:value, puedes borrar la clave o cambiar el valor.

Los metadatos personalizados están sujetos a un límite de tamaño y, además, incurren en costos de almacenamiento.

En la página Visualiza y edita metadatos, se incluye información sobre cómo configurar metadatos personalizados.

El prefijo x-goog-meta-

La API de XML establece y recupera metadatos de objetos mediante encabezados de solicitudes, y la API de JSON permite configurar metadatos personalizados en la solicitud final de una carga reanudable mediante encabezados de solicitud. Para distinguir claramente los encabezados de metadatos personalizados de los encabezados de solicitudes estándar, ambos prefijos incluyen los encabezados de metadatos personalizados con x-goog-meta-.

Metadatos no editables

Algunos metadatos no se pueden editar directamente. Estos metadatos se configuran al momento de la creación o de la reescritura del objeto. Como parte de la creación o la reescritura del objeto, puedes configurar algunos de estos metadatos, como la clase de almacenamiento del objeto o las claves de encriptación administradas por el cliente. Otros metadatos se agregan de forma automática y solo se pueden visualizar, como el número de generación del objeto o la fecha de creación.

Números de generación y metageneración

Como parte de sus metadatos, cada objeto de Cloud Storage tiene una propiedad generation numérica y una propiedad metageneration numérica que identifica el objeto de manera inequívoca:

Propiedad Descripción
generation Identifica la versión de un objeto y existe para cada objeto, sin importar si un bucket usa el control de versiones de objetos.
  • El valor de generation de la versión de un objeto nunca cambia. Un objeto nuevo con el mismo nombre puede reemplazar un objeto existente, pero el objeto nuevo siempre tiene una generation diferente asignada.
  • Ten en cuenta que no hay garantía de que los números de generación aumenten para las versiones sucesivas, solo que cada versión nueva tiene un número de generación único.
  • No existe una relación entre los números de generación de objetos no relacionados, incluso si los objetos están en el mismo bucket.
metageneration Identifica la versión de metadatos y aumenta cada vez que se actualizan los metadatos de una generation determinada.
  • metageneration comienza en 1 para cada generation nueva de un objeto.
  • La propiedad metageneration no tiene sentido sin la propiedad generation y debe usarse solo junto con ella. No tiene sentido comparar las generaciones de metadatos de dos versiones de objetos.

Las propiedades generation y metageneration se usan en las siguientes circunstancias:

Sumas de verificación

Las sumas de comprobación son metadatos calculados a partir de los datos del objeto asociado. Las sumas de verificación se usan para validar que los datos del objeto no estén dañados. Los objetos de Cloud Storage tienen varios campos de metadatos de suma de comprobación.

CRC32C

Todos los objetos de Cloud Storage tienen un hash CRC32C. Entre las bibliotecas para procesar CRC32C se incluyen las siguientes:

CRC32C codificado en Base64 está en el orden de bytes big-endian.

MD5

Los objetos de Cloud Storage tienen un hash MD5 si cumplen con los siguientes criterios:

Cuando un encabezado Content-MD5 está presente en la solicitud, Cloud Storage valida la integridad de los datos del objeto comparando el hash MD5 proporcionado con el hash calculado del objeto subido. Si los hashes no coinciden, se rechaza la solicitud.

ETags

Todos los objetos de Cloud Storage tienen una ETag. Sin embargo, el mismo objeto puede tener un valor de ETag diferente cuando se solicita desde la API de XML en comparación con la API de JSON. En la mayoría de los casos, los usuarios no deben hacer suposiciones sobre el valor usado en una ETag, excepto que cambia cada vez que cambian los datos subyacentes o metadatos, según la especificación.

El encabezado ETag de un objeto muestra el valor MD5 del objeto si se cumplen las siguientes condiciones:

Marcas de tiempo

Los metadatos de un objeto de Cloud Storage pueden incluir las siguientes marcas de tiempo. Los nombres de los campos varían según la herramienta o el lenguaje del SDK que uses para trabajar con el objeto. En el caso de los SDKs, consulta la documentación de la biblioteca cliente correspondiente.

Línea de comandos

Nombre del campo Descripción
creation_time Es la hora de creación del objeto. Esta marca de tiempo no cambia.
update_time Es la hora de modificación más reciente de los metadatos del objeto. Este valor se establece inicialmente en la hora de creación del objeto y, luego, se actualiza cada vez que cambia algún metadato del objeto. Esto incluye los cambios que realiza un solicitante, como modificar metadatos personalizados, y los cambios que realiza Cloud Storage en nombre de un solicitante, como cambiar la clase de almacenamiento según una configuración del ciclo de vida de los objetos.
noncurrent_time Es la hora de eliminación del objeto. Se muestra solo si esta versión del objeto ya no es una versión publicada, pero permanece en el bucket como una versión no actual.
soft_delete_time Fecha y hora en que se borró de forma no definitiva el objeto. Solo está disponible para los objetos en buckets con una política de eliminación no definitiva.
hard_delete_time Fecha y hora en la que se borrará de forma permanente un objeto borrado de forma no definitiva y ya no se podrá restablecer. Este valor es la suma de los valores del tiempo de eliminación no definitiva y la duración de retención que se establece en la política de retención del bucket. Solo está disponible para los objetos en buckets con una política de eliminación no definitiva. Ten en cuenta que el valor del tiempo de eliminación definitiva es permanente después de que se establece y no cambia en respuesta a los cambios en la duración de la retención.
retention_settings.retainUntilTime Es la fecha y hora más tempranas en las que se puede borrar o reemplazar el objeto. Este valor es independiente de cualquier política de retención establecida para el bucket que contiene el objeto. El valor máximo es de 3,155,760,000 segundos (100 años) a partir de la fecha y hora actuales.
retention_expiration Es la fecha y hora más tempranas en las que se puede borrar el objeto. Este valor depende de la configuración de retención establecida para el objeto y de la política de retención establecida para el bucket que contiene el objeto.
storage_class_update_time Es la fecha y hora en la que se modificó la clase de almacenamiento del objeto por última vez. Cuando se crea el objeto inicialmente, el valor se establece en la hora de creación del objeto.
finalize_time Es la fecha y hora de finalización del objeto.
contexts.KEY.createTime Fecha y hora en que se agregó por primera vez esta clave de contexto del objeto al objeto.
contexts.KEY.updateTime Fecha y hora en que se actualizó por última vez esta clave de contexto del objeto.
custom_time Es la marca de tiempo especificada por el usuario para el objeto. Después de establecer una hora personalizada en un objeto, esta no se puede quitar ni establecer en una fecha y hora anteriores. Para obtener más información sobre cómo usar el tiempo personalizado, consulta los metadatos de tiempo personalizado.

API

API de JSON

Nombre del campo Descripción
timeCreated Es la hora de creación del objeto. Esta marca de tiempo no cambia.
updated Es la hora de modificación más reciente de los metadatos del objeto. Este valor se establece inicialmente en la hora de creación del objeto y, luego, se actualiza cada vez que cambia algún metadato del objeto. Esto incluye los cambios que realiza un solicitante, como modificar metadatos personalizados, y los cambios que realiza Cloud Storage en nombre de un solicitante, como cambiar la clase de almacenamiento según una configuración del ciclo de vida de los objetos.
timeDeleted Es la hora de eliminación del objeto. Se muestra solo si esta versión del objeto ya no es una versión publicada, pero permanece en el bucket como una versión no actual.
softDeleteTime Fecha y hora en que se borró de forma no definitiva el objeto. Solo está disponible para los objetos en buckets con una política de eliminación no definitiva.
hardDeleteTime Fecha y hora en la que se borrará de forma permanente un objeto borrado de forma no definitiva y ya no se podrá restablecer. Este valor es la suma de los valores del tiempo de eliminación no definitiva y la duración de retención que se establece en la política de retención del bucket. Solo está disponible para los objetos en buckets con una política de eliminación no definitiva. Ten en cuenta que el valor del tiempo de eliminación definitiva es permanente después de que se establece y no cambia en respuesta a los cambios en la duración de la retención.
retention.retainUntilTime Es la fecha y hora más tempranas en las que se puede borrar o reemplazar el objeto. Este valor es independiente de cualquier política de retención establecida para el bucket que contiene el objeto. El valor máximo es de 3,155,760,000 segundos (100 años) a partir de la fecha y hora actuales.
retentionExpirationTime Es la fecha y hora más tempranas en las que se puede borrar el objeto. Este valor depende de la configuración de retención establecida para el objeto y de la política de retención establecida para el bucket que contiene el objeto.
timeStorageClassUpdated Es la fecha y hora en la que se modificó la clase de almacenamiento del objeto por última vez. Cuando se crea el objeto inicialmente, el valor se establece en la hora de creación del objeto.
timeFinalized Es la fecha y hora de finalización del objeto.
contexts.custom.KEY.createTime Fecha y hora en que se agregó por primera vez esta clave de contexto del objeto al objeto.
contexts.custom.KEY.updateTime Fecha y hora en que se actualizó por última vez esta clave de contexto del objeto.
customTime Es la marca de tiempo especificada por el usuario para el objeto. Después de establecer una hora personalizada en un objeto, esta no se puede quitar ni establecer en una fecha y hora anteriores. Para obtener más información sobre cómo usar el tiempo personalizado, consulta los metadatos de tiempo personalizado.

API de XML

Nombre del campo Descripción
Created Es la hora de creación del objeto. Esta marca de tiempo no cambia.
LastModified Es la hora de modificación más reciente de los metadatos del objeto. Este valor se establece inicialmente en la hora de creación del objeto y, luego, se actualiza cada vez que cambia algún metadato del objeto. Esto incluye los cambios que realiza un solicitante, como modificar metadatos personalizados, y los cambios que realiza Cloud Storage en nombre de un solicitante, como cambiar la clase de almacenamiento según una configuración del ciclo de vida de los objetos.
DeletedTime Es la hora de eliminación del objeto. Se muestra solo si esta versión del objeto ya no es una versión publicada, pero permanece en el bucket como una versión no actual.
x-goog-object-lock-retain-until-date Es la fecha y hora más tempranas en las que se puede borrar o reemplazar el objeto. Este valor es independiente de cualquier política de retención establecida para el bucket que contiene el objeto. El valor máximo es de 3,155,760,000 segundos (100 años) a partir de la fecha y hora actuales.
Finalized Es la fecha y hora de finalización del objeto.
x-goog-custom-time Es la marca de tiempo especificada por el usuario para el objeto. Después de establecer una hora personalizada en un objeto, esta no se puede quitar ni establecer en una fecha y hora anteriores. Para obtener más información sobre cómo usar el tiempo personalizado, consulta los metadatos de tiempo personalizado.

API de RPC

Nombre del campo Descripción
create_time Es la hora de creación del objeto. Esta marca de tiempo no cambia.
update_time Es la hora de modificación más reciente de los metadatos del objeto. Este valor se establece inicialmente en la hora de creación del objeto y, luego, se actualiza cada vez que cambia algún metadato del objeto. Esto incluye los cambios que realiza un solicitante, como modificar metadatos personalizados, y los cambios que realiza Cloud Storage en nombre de un solicitante, como cambiar la clase de almacenamiento según una configuración del ciclo de vida de los objetos.
delete_time Es la hora de eliminación del objeto. Se muestra solo si esta versión del objeto ya no es una versión publicada, pero permanece en el bucket como una versión no actual.
soft_delete_time Fecha y hora en que se borró de forma no definitiva el objeto. Solo está disponible para los objetos en buckets con una política de eliminación no definitiva.
hard_delete_time Fecha y hora en la que se borrará de forma permanente un objeto borrado de forma no definitiva y ya no se podrá restablecer. Este valor es la suma de los valores del tiempo de eliminación no definitiva y la duración de retención que se establece en la política de retención del bucket. Solo está disponible para los objetos en buckets con una política de eliminación no definitiva. Ten en cuenta que el valor del tiempo de eliminación definitiva es permanente después de que se establece y no cambia en respuesta a los cambios en la duración de la retención.
retention.retain_until_time Es la fecha y hora más tempranas en las que se puede borrar o reemplazar el objeto. Este valor es independiente de cualquier política de retención establecida para el bucket que contiene el objeto. El valor máximo es de 3,155,760,000 segundos (100 años) a partir de la fecha y hora actuales.
retention_expire_time Es la fecha y hora más tempranas en las que se puede borrar el objeto. Este valor depende de la configuración de retención establecida para el objeto y de la política de retención establecida para el bucket que contiene el objeto.
update_storage_class_time Es la fecha y hora en la que se modificó la clase de almacenamiento del objeto por última vez. Cuando se crea el objeto inicialmente, el valor se establece en la hora de creación del objeto.
finalize_time Es la fecha y hora de finalización del objeto.
contexts.custom.KEY.createTime Fecha y hora en que se agregó por primera vez esta clave de contexto del objeto al objeto.
contexts.custom.KEY.updateTime Fecha y hora en que se actualizó por última vez esta clave de contexto del objeto.
custom_time Es la marca de tiempo especificada por el usuario para el objeto. Después de establecer una hora personalizada en un objeto, esta no se puede quitar ni establecer en una fecha y hora anteriores. Para obtener más información sobre cómo usar el tiempo personalizado, consulta los metadatos de tiempo personalizado.

¿Qué sigue?