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 recurso files
.
Especifica nombres de archivos y extensiones
Las apps deben especificar una extensión de archivo en la propiedad de título 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 que se especificó originalmente en la propiedad name
. Cuando un usuario de Google Drive solicita descargar un archivo, o cuando el archivo se descarga mediante el cliente de sincronización, Drive crea un nombre de archivo completo (con extensión) basado en el título. En los casos en que falta la extensión,
Drive intentará determinar la extensión en función del tipo de MIME del archivo.
Guardar texto indexable
Drive indexa automáticamente los documentos para la búsqueda cuando reconoce el tipo de archivo, incluidos los documentos de texto, los 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 visibilidad si proporcionas texto indexable en el campo contentHints.indexableText
del archivo.
El texto indexable se indexa como HTML. Si guardas la string de texto indexable <section attribute="value1">Here's some text</section>
, se indexará "Aquí hay algo de texto", pero no "value1". Por este motivo, guardar el XML como texto indexable no es tan útil como guardar HTML.
Cuando especifiques indexableText
, también ten en cuenta lo siguiente:
- El límite de tamaño de
contentHints.indexableText
es de 128 KB. - Captura los términos y conceptos clave que esperas que busquen los usuarios.
- No intentes ordenar el texto por orden de importancia, ya que el indizador lo hace de manera eficiente por ti.
- Tu aplicación debería 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 una buena idea agregar términos de búsqueda frecuentes para forzar la aparición de un archivo en los resultados de la búsqueda. Esto puede frustrar a los usuarios y motivarlos a borrar el archivo.
Subir 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 archivo 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, configura el campo contentHints.thumbnail
en el recurso files
para subir una miniatura.
En particular, haz lo siguiente:
- Establece el campo
contentHints.thumbnail.image
en la imagen segura codificada en base64 de la URL y del nombre de archivo (consulta la sección 5 de RFC 4648). - Establece el campo
contentHints.thumbnail.mimeType
en el tipo de MIME adecuado para la miniatura.
Si Drive puede generar una miniatura a partir del archivo, usa la que se generó automáticamente e ignora las que hayas subido. Si no puede generar una miniatura, usará la que proporciones.
Las miniaturas deben cumplir con estas reglas:
- Se pueden subir en formato PNG, GIF o JPG.
- El ancho recomendado es de 1,600 píxeles.
- El ancho mínimo es 220 píxeles.
- El tamaño máximo permitido del archivo es 2 MB.
- La aplicación debe actualizarlos cada vez que se guarde.
Para obtener más información, consulta el recurso files
.
Cómo recuperar miniaturas
Puedes recuperar metadatos, incluidas miniaturas, de los archivos de Drive.
La información de las miniaturas se encuentra en el campo thumbnailLink
del recurso files
.
Cómo mostrar una miniatura específica
En la siguiente muestra de código, se incluye una solicitud del método files.get
con varios campos como parámetro de consulta para mostrar los metadatos thumbnailLink
de un archivo específico. Si quieres obtener más información, consulta Cómo mostrar 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 buscar.
Si está disponible, la solicitud muestra una URL de corta duración a la miniatura del archivo.
Normalmente, 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 mediante una solicitud con credenciales.
Cómo mostrar una lista de miniaturas
En la siguiente muestra de código, se incluye una solicitud del método files.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 Cómo buscar 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 de MIME. En la siguiente muestra de código, se indica cómo limitar la lista a archivos de Hojas de cálculo de Google. Para obtener más información sobre los tipos de MIME, consulta Tipos de 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)