Administrar metadatos de archivos

En este documento, se abordan consideraciones importantes para nombrar archivos y trabajar con metadatos, como texto indexable y miniaturas. Para insertar y recuperar archivos, consulta el files recurso.

Descripción general de los metadatos

En la API de Google Drive, el recurso files representa los metadatos. A diferencia de las APIs en las que los metadatos son un subobjeto, la API de Drive trata todo el recurso files como metadatos. Puedes acceder a los metadatos directamente a través de los get o list métodos en el files recurso.

De forma predeterminada, los métodos get y list solo muestran un conjunto parcial de campos. Para recuperar datos específicos, debes definir el fields parámetro del sistema en tu solicitud. Si se omite, el servidor muestra un subconjunto predeterminado de campos específicos del método. Por ejemplo, el método list solo muestra los campos kind, id, name, mimeType y resourceKey para cada archivo. Para mostrar diferentes campos, consulta Devuelve campos específicos.

Además, la visibilidad de los metadatos depende del rol del usuario en el archivo. El permissions recurso no determina las acciones permitidas de un usuario en un archivo o una carpeta. En cambio, el recurso files contiene una colección de campos capabilities booleanos. La API de Google Drive deriva estas capabilities del recurso permissions asociado con el archivo o la carpeta. Para obtener más información, consulta Información sobre las capacidades de los archivos.

La API de Drive ofrece dos alcances de metadatos restringidos: drive.metadata y drive.metadata.readonly. El alcance drive.metadata te permite ver y administrar los metadatos de los archivos, mientras que drive.metadata.readonly es de solo lectura. Ambos prohíben estrictamente el acceso al contenido del archivo. Para obtener más información, consulta Elige los alcances de la API de Google Drive.

Por último, verifica siempre tu lógica con respecto a los permisos y los alcances. Por ejemplo, un usuario puede ser propietario de un archivo con permisos completos, pero la API de Drive bloqueará los intentos de modificar o descargar el archivo si tu app solo tiene el alcance drive.metadata.readonly.

Especifica nombres de archivo y extensiones

Las apps deben especificar una extensión de archivo en la name) propiedad cuando insertan archivos con la API de Google Drive. Por ejemplo, una operación para insertar un archivo JPEG debe especificar algo como "name": "cat.jpg" en los metadatos.

Las respuestas GET posteriores pueden incluir la propiedad fileExtension de solo lectura propagada con la extensión especificada originalmente en la propiedad name. Cuando un usuario de Google Drive solicita descargar un archivo o cuando se descarga a través del cliente de sincronización, Drive compila un nombre de archivo completo (con extensión) según el nombre. En los casos en los que falta la extensión, Drive intenta determinarla según el tipo MIME del archivo.

Guarda texto indexable

Drive indexa automáticamente los documentos para la búsqueda cuando reconoce el tipo de archivo, incluidos los documentos de texto, los archivos PDF, las imágenes con texto y otros tipos comunes. Si tu app guarda otros tipos de archivos (como dibujos, videos y accesos directos), puedes mejorar la capacidad de descubrimiento si proporcionas texto indexable en el contentHints.indexableText campo del archivo.

El texto indexable se indexa como HTML. Si guardas la cadena de texto indexable <section attribute="value1">Here's some text</section>, se indexa "Here's some text", pero no "value1". Por lo tanto, guardar XML como texto indexable no es tan útil como guardar HTML.

Cuando especifiques indexableText, ten en cuenta lo siguiente:

  • El límite de tamaño para contentHints.indexableText es de 128 KB.
  • Captura los términos y conceptos clave que esperas que busque un usuario.
  • No intentes ordenar el texto por importancia, ya que el indexador lo hace de manera eficiente por ti.
  • Tu aplicación debe actualizar el texto indexable con cada guardado.
  • Asegúrate de que el texto esté relacionado con el contenido o los metadatos del archivo.

Este último punto puede parecer obvio, pero es importante. No es recomendable agregar términos de búsqueda comunes para forzar que un archivo aparezca en los resultados de la búsqueda. Esto puede frustrar a los usuarios e incluso motivarlos a borrar el archivo.

Sube miniaturas

Drive genera automáticamente miniaturas para muchos tipos de archivos comunes, como Documentos, Hojas de cálculo y Presentaciones de Google. Las miniaturas ayudan al usuario a identificar mejor los archivos de Drive.

Para los tipos de archivos para los que Drive no puede generar una miniatura estándar, puedes proporcionar una imagen en miniatura generada por tu aplicación. Durante la creación o actualización de archivos, sube una miniatura configurando el contentHints.thumbnail campo en el files recurso.

Específicamente, son las siguientes:

  • Establece el campo contentHints.thumbnail.image en la imagen codificada en base64 segura para URL y nombres de archivo (consulta la sección 5 del documento RFC 4648 ).
  • Establece el campo contentHints.thumbnail.mimeType en el tipo MIME adecuado para la miniatura.

Si Drive puede generar una miniatura a partir del archivo, usa la generada automáticamente y omite cualquier otra que hayas subido. Si no puede generar una miniatura, usa la que proporcionas.

Las miniaturas deben cumplir con estas reglas:

  • Se pueden subir en formatos PNG, GIF o JPG.
  • El ancho recomendado es de 1,600 píxeles.
  • El ancho mínimo es de 220 píxeles.
  • El tamaño máximo permitido del archivo es de 2 MB.
  • Tu aplicación debe actualizarlas con cada guardado.

Para obtener más información, consulta el files recurso.

Recupera miniaturas

Puedes recuperar metadatos, incluidas miniaturas, para archivos de Drive. La información de la miniatura se encuentra en el thumbnailLink campo de el files recurso.

Devuelve una miniatura específica

En el siguiente ejemplo de código, se muestra una solicitud de método get con varios campos como parámetro de consulta para mostrar los thumbnailLink metadatos de un archivo específico. Para obtener más información, consulta Devuelve campos específicos para un archivo.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink

Reemplaza FILE_ID por el fileId del archivo que deseas encontrar.

Si está disponible, la solicitud muestra una URL de corta duración a la miniatura del archivo. Por lo general, el vínculo dura varias horas. El campo solo se propaga cuando la app solicitante puede acceder al contenido del archivo. Si el archivo no se comparte públicamente, la URL que se muestra en thumbnailLink se debe recuperar con una solicitud con credenciales.

Devuelve una lista de miniaturas

En el siguiente ejemplo de código, se muestra una solicitud de método list con varios campos como parámetro de consulta para mostrar los metadatos thumbnailLink de una lista de archivos. Para obtener más información, consulta Busca archivos y carpetas.

GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)

Para restringir los resultados de la búsqueda a un tipo de archivo específico, aplica una cadena de consulta para establecer el tipo MIME. Por ejemplo, en el siguiente ejemplo de código, se muestra cómo limitar la lista a archivos de Hojas de cálculo de Google. Para obtener más información sobre los tipos MIME, consulta Tipos MIME compatibles con Google Workspace y Google Drive.

GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)