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 y extensiones de archivos
Las apps deben especificar una extensión de archivo en la propiedad title 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 el archivo se descarga a través del 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 intenta determinarla según el tipo de MIME del archivo.
Cómo 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 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 detección proporcionando texto indexable en el campo contentHints.indexableText 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 indexará "Aquí hay algo de texto", pero no "value1". Por este motivo, guardar 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 para
contentHints.indexableTextes de 128 KB. - Captura los términos y conceptos clave que esperas que un usuario busque.
- No intentes ordenar el texto según su 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 se relacione 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 comunes para forzar que un archivo aparezca en los resultados de la búsqueda. Esto puede frustrar a los usuarios y hasta motivarlos a borrar el archivo.
Cómo 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.
En el caso de los tipos de archivos para los que Drive no puede generar una miniatura estándar, puedes proporcionar una imagen de miniatura generada por tu aplicación. Durante la creación o actualización de un archivo, sube una miniatura configurando el campo contentHints.thumbnail en el recurso files.
En particular, haz lo siguiente:
- Establece el campo
contentHints.thumbnail.imageen la imagen codificada en base64 segura para URL y nombres de archivo (consulta la sección 5 del RFC 4648). - Establece el campo
contentHints.thumbnail.mimeTypeen 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 y omite las 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 actualizarlos con cada guardado.
Para obtener más información, consulta el recurso files.
Cómo recuperar miniaturas
Puedes recuperar metadatos, incluidas miniaturas, para los archivos de Drive.
La información de la miniatura se encuentra en el campo thumbnailLink del recurso files.
Devuelve una miniatura específica
En el siguiente ejemplo de código, se muestra una solicitud del método files.get con varios campos como parámetro de consulta para devolver los metadatos de thumbnailLink para un archivo específico. Para obtener más información, consulta Cómo devolver 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 devuelve una URL de corta duración a la miniatura del archivo.
Por lo general, el vínculo dura varias horas. El campo solo se completa cuando la app solicitante puede acceder al contenido del archivo. Si el archivo no se comparte de forma pública, 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 del método files.list con varios campos como parámetro de consulta para devolver los metadatos de thumbnailLink para 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 búsqueda para establecer el tipo de MIME. Por ejemplo, en el siguiente código de muestra, se muestra cómo limitar la lista a los 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)