Trabaja con metadatos de objeto

Descripción general de los metadatos

Los objetos pueden tener metadatos asociados, que controlan los aspectos acerca de cómo se manejan las solicitudes GET, como el tipo de contenido, el control de caché, la disposición de contenido y la codificación de contenido (que se analiza con más detalle en las siguientes subsecciones). Además, puedes configurar metadatos personalizados que las aplicaciones pueden usar (p. ej., etiquetar esos objetos particulares que tienen alguna propiedad).

Existen dos formas de establecer metadatos en los objetos:

  • En el momento de la carga, puedes especificar una o más propiedades de metadatos para asociar con objetos mediante la opción gsutil -h. Por ejemplo, el siguiente comando podría hacer que gsutil configure el tipo de contenido y el control de caché para cada uno de los archivos que se suben desde un directorio local llamado images:

    gsutil -h "Content-Type:text/html" \
           -h "Cache-Control:public, max-age=3600" cp -r images \
           gs://bucket/images
    

    Ten en cuenta que -h es una opción del comando de gsutil, no del subcomando cp.

  • Puedes establecer o quitar campos de metadatos de objetos ya cargados mediante el comando gsutil setmeta. Consulta gsutil help setmeta.

A continuación, se analizan más detalles sobre las partes específicas de los metadatos.

Tipo de contenido

Los metadatos que se configuran con mayor frecuencia son los del tipo de contenido (también conocido como tipo de MIME), que permite a los navegadores procesar el objeto de forma correcta. gsutil establece el tipo de contenido de forma automática en el momento de la carga, según cada extensión de nombre de archivo. Por ejemplo, subir archivos con nombres que terminan en .txt configurará el tipo de contenido como texto/sin formato. Si ejecutas gsutil en Linux o macOS y prefieres configurar el tipo de contenido en función del nombre y el examen de contenido, consulta la variable de configuración use_magicfile en el archivo de configuración .boto. En general, el uso de use_magicfile es más resistente y fácil de configurar, pero no está disponible en Windows.

Si especificas el tipo de contenido con -h cuando subes contenido (como el comando de gsutil de ejemplo de la sección anterior), se anula el tipo de contenido que se hubiera establecido en función de la extensión o el contenido del nombre de archivo. Esto puede ser útil si el algoritmo de detección del tipo de contenido no funciona como deseas en algunos archivos.

Control de caché

Otra parte de los metadatos que se configura con frecuencia es el control de caché, que te permite controlar si el navegador y la caché de Internet pueden almacenar los objetos y por cuánto tiempo. El control de caché solo se aplica a los objetos con una LCA de lectura pública. Los datos no públicos no se pueden almacenar en caché.

A continuación, se muestra un ejemplo de cómo subir un conjunto de objetos desde un directorio local llamado photos para permitir el almacenamiento en caché:

gsutil -h "Cache-Control:public,max-age=3600" cp -a public-read \
       -r photos gs://bucket/photos

Con este comando, se subirían todos los archivos en el directorio photos (y los subdirectorios) y haría que puedan leerse de forma pública y que puedan almacenarse en caché, con un vencimiento de caché de una hora.

Ten en cuenta que si permites el almacenamiento en caché, en el momento de la descarga puedes ver versiones anteriores de objetos después de subir un objeto de reemplazo más reciente. Ten en cuenta también que, debido a que los objetos se pueden almacenar en caché en varios lugares de Internet, no hay manera de forzar el vencimiento global de un objeto (a diferencia de la forma en que puedes hacer que el navegador actualice la caché). Si quieres evitar que se entreguen versiones almacenadas en caché de objetos que se pueden leer de forma pública, configura “Cache-Control:no-cache, max-age=0” en el objeto. Puedes hacer esto con un comando como el siguiente:

gsutil -h "Cache-Control:no-cache,max-age=0" \
       cp -a public-read file.png gs://your-bucket

Otro uso del control de caché es a través del valor “no-transform”, que indica a Cloud Storage que no aplique transformaciones de contenido basadas en información específica de una solicitud de descarga, como quitar la codificación de contenido de gzip para clientes incompatibles. Ten en cuenta que este parámetro solo se respeta en la API de XML. La API de JSON de Cloud Storage solo respeta los parámetros del control de caché público, privado, sin caché y de max-age.

Para obtener más información sobre cómo configurar los metadatos del control de caché, consulta gsutil help setmeta.

Codificación del contenido

Puedes especificar una codificación de contenido para indicar que un objeto está comprimido (por ejemplo, con compresión gzip) mientras mantienes el tipo de contenido. Deberás asegurarte de que los archivos se compriman mediante la codificación de contenido especificada antes de usar gsutil para subirlos. Considera el siguiente ejemplo para Linux:

echo "Highly compressible text" | gzip > foo.txt
gsutil -h "Content-Encoding:gzip" \
       -h "Content-Type:text/plain" \
       cp foo.txt gs://bucket/compressed

Ten en cuenta que esto no es lo mismo que subir un objeto foo.txt.gz en formato gzip con el tipo de contenido application/x-gzip, ya que la mayoría de los navegadores pueden descomprimir y procesar objetos de forma dinámica que se entregan mediante la codificación de contenido gzip basado en el tipo de contenido subyacente.

Para el contenido que puede comprimirse, se usa la codificación de contenido: gzip ahorra costos de almacenamiento y red, y mejora el rendimiento de la entrega de contenido. Sin embargo, para el contenido que ya está comprimido (por ejemplo, archivos y muchos formatos multimedia), aplicar otro nivel de compresión mediante la codificación de contenido suele ser perjudicial para el tamaño y el rendimiento del objeto; por ende, se debe evitar.

También ten en cuenta que gsutil proporciona una manera fácil de hacer que el contenido se comprima y se almacene con la codificación de contenido gzip: consulta las opciones -z y -Z en gsutil help cp.

Disposición del contenido

Puedes configurar la disposición de contenido en los objetos para especificar la información de presentación sobre los datos que se transmiten. Este es un ejemplo de carga de archivos desde un directorio local llamado attachments:

gsutil -h 'Content-Disposition:attachment; filename=filename.ext' \
       cp -r attachments gs://bucket/attachments

La configuración de la disposición de contenido te permite controlar el estilo de la presentación del contenido. Por ejemplo, puedes determinar si un archivo adjunto debe mostrarse de forma automática o si el usuario debería realizar alguna acción para abrirlo. Consulta https://tools.ietf.org/html/rfc6266 para obtener más detalles sobre el significado de la disposición de contenido.

Metadatos personalizados

Puedes agregar tus propios metadatos personalizados (p. ej., para que los use tu aplicación) a un objeto de Cloud Storage mediante “x-goog-meta” con -h. Por ejemplo:

gsutil -h x-goog-meta-reviewer:jane cp mycode.java gs://bucket/reviews

Puedes agregar varios campos de metadatos personalizados con nombres diferentes a cada objeto.

Campos que se pueden configurar y valores de campo

Algunos campos de metadatos no se pueden, como ETag y el largo del contenido. Los campos que puedes configurar son los siguientes:

  • Cache-Control
  • Content-Disposition
  • Content-Encoding
  • Content-Language
  • Tipo de contenido
  • Custom metadata

Los nombres de campos no distinguen entre mayúsculas y minúsculas.

Todos los campos y sus valores deben constar solo de caracteres ASCII, excepto los valores de x-goog-meta-fields, que pueden contener valores arbitrarios de Unicode. Ten en cuenta que cuando configuras metadatos mediante la API de XML, que envía metadatos personalizados como encabezados HTTP, los caracteres Unicode se codifican mediante UTF-8 y, luego, se codifican como URL a ASCII. Por ejemplo:

gsutil setmeta -h "x-goog-meta-foo: ã" gs://bucket/object

En el ejemplo anterior, se almacenaría el par clave-valor de metadatos personalizado de “foo” y “%C3%AD”. Luego, si se ejecuta “ls -L” mediante la API de JSON para enumerar los metadatos del objeto, se imprimiría “%C3%A3” y, si se ejecuta “ls -L” mediante la API de XML, se decodificaría de forma automática este valor como URL, por lo que se imprimiría el carácter “ã”.

Visualiza metadatos configurados en este momento

Para ver qué metadatos están configurados en este momento en un objeto, usa lo siguiente:

gsutil ls -L gs://the_bucket/the_object