En esta guía, se explica cómo la API de Google Drive admite varias formas de buscar archivos y carpetas.
Puedes usar el método list
en el recurso files
para devolver todos o algunos de los archivos y las carpetas de un usuario de Drive. El método list
también se puede usar para recuperar el fileId
requerido para algunos métodos de recursos (como el método get
y el método update
).
Usa el parámetro fields
Si deseas especificar los campos que se devolverán en la respuesta, puedes establecer el parámetro del sistema fields
con cualquier método del recurso files
. Si omites el parámetro fields
, el servidor devolverá un conjunto predeterminado de campos específicos del método. Por ejemplo, el método list
solo devuelve los campos kind
, id
, name
, mimeType
y resourceKey
para cada archivo. Para devolver diferentes campos, consulta Cómo devolver campos específicos.
Cómo obtener un archivo
Para obtener un archivo, usa el método get
en el recurso files
con el parámetro de ruta de acceso fileId
.
Si no conoces el ID del archivo, puedes listar todos los archivos con el método list
.
El método devuelve el archivo como una instancia de un recurso files
. Si proporcionas el parámetro de consulta alt=media
, la respuesta incluirá el contenido del archivo en el cuerpo de la respuesta. Para descargar o exportar el archivo, consulta Descarga y exporta archivos.
Para confirmar que conoces el riesgo de descargar software malicioso conocido o archivos abusivos, establece el parámetro de consulta acknowledgeAbuse
en true
. Este campo solo se aplica cuando se establece el parámetro alt=media
y el usuario es el propietario del archivo o el organizador de la unidad compartida en la que se encuentra el archivo.
Buscar todos los archivos y carpetas en la sección Mi unidad del usuario actual
Usa el método list
sin parámetros para devolver todos los archivos y las carpetas.
GET https://www.googleapis.com/drive/v3/files
Buscar archivos o carpetas específicos en la sección Mi unidad del usuario actual
Para buscar un conjunto específico de archivos o carpetas, usa el campo de cadena de consulta q
con el método list
para filtrar los archivos que se devolverán combinando uno o más términos de búsqueda.
La sintaxis de la cadena de consulta contiene las siguientes tres partes:
query_term operator values
Donde:
query_term
es el término de búsqueda o el campo en el que se realizará la búsqueda.operator
especifica la condición del término de búsqueda.values
son los valores específicos que deseas usar para filtrar los resultados de la búsqueda.
Por ejemplo, la siguiente cadena de consulta filtra la búsqueda para que solo muestre carpetas configurando el tipo de MIME:
q: mimeType = 'application/vnd.google-apps.folder'
Para ver todos los términos de búsqueda de archivos, consulta Términos de búsqueda específicos de archivos.
Para ver todos los operadores de consulta que puedes usar para crear una consulta, consulta Operadores de consulta.
Ejemplos de cadenas de consulta
En la siguiente tabla, se enumeran ejemplos de algunas cadenas de búsqueda básicas. El código real difiere según la biblioteca cliente que uses para tu búsqueda.
También debes escapar los caracteres especiales en los nombres de los archivos para asegurarte de que la consulta funcione correctamente. Por ejemplo, si un nombre de archivo contiene un apóstrofe ('
) y una barra inversa ("\"
), usa una barra inversa para escaparlos: name
contains 'quinn\'s paper\\essay'
.
Lo que quieres consultar | Ejemplo |
---|---|
Archivos con el nombre "hello" | name = 'hello' |
Archivos con un nombre que contiene las palabras "hola" y "adiós" | name contains 'hello' and name contains 'goodbye' |
Archivos con un nombre que no contiene la palabra "hola" | not name contains 'hello' |
Archivos que contienen el texto "importante" y que están en la papelera | fullText contains 'important' and trashed = true |
Archivos que contienen la palabra "hola" | fullText contains 'hello' |
Archivos que no tienen la palabra "hola" | not fullText contains 'hello' |
Archivos que contienen la frase exacta “hello world” | fullText contains '"hello world"' |
Archivos con una búsqueda que contiene el carácter "\" (por ejemplo, "\authors") | fullText contains '\\authors' |
Archivos que son carpetas | mimeType = 'application/vnd.google-apps.folder' |
Archivos que no son carpetas | mimeType != 'application/vnd.google-apps.folder' |
Archivos modificados después de una fecha determinada (la zona horaria predeterminada es UTC) | modifiedTime > '2012-06-04T12:00:00' |
Archivos de imagen o video modificados después de una fecha específica | modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/') |
Archivos destacados | starred = true |
Archivos dentro de una colección (por ejemplo, el ID de la carpeta en la colección parents ) |
'1234567' in parents |
Archivos en una carpeta de datos de la aplicación en una colección | 'appDataFolder' in parents |
Archivos para los que el usuario "test@example.org" es el propietario | 'test@example.org' in owners |
Archivos para los que el usuario "test@example.org" tiene permiso de escritura | 'test@example.org' in writers |
Archivos para los que los miembros del grupo "group@example.org" tienen permiso de escritura | 'group@example.org' in writers |
Archivos compartidos con el usuario autorizado que tienen "hola" en el nombre | sharedWithMe and name contains 'hello' |
Archivos con una propiedad de archivo personalizada visible para todas las apps | properties has { key='mass' and value='1.3kg' } |
Archivos con una propiedad de archivo personalizada privada para la app solicitante | appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' } |
Archivos que no se compartieron con nadie ni con ningún dominio (solo privados o compartidos con usuarios o grupos específicos) | visibility = 'limited' |
Cómo filtrar los resultados de la búsqueda con una biblioteca cliente
En la siguiente muestra de código, se muestra cómo usar una biblioteca cliente para filtrar los resultados de la búsqueda por nombres de archivo y IDs de archivos JPEG. En este ejemplo, se usa el término de búsqueda mimeType
para acotar los resultados a archivos de tipo image/jpeg
. También establece spaces
en drive
para limitar aún más la búsqueda al espacio de Drive. Cuando nextPageToken
devuelve null
, significa que no hay más resultados.
Java
Python
Node.js
PHP
Cómo buscar archivos con una propiedad de archivo personalizada
Para buscar archivos con una propiedad de archivo personalizada, usa el término de búsqueda properties
o appProperties
con una clave y un valor. Por ejemplo, para buscar una propiedad de archivo personalizada que sea privada para la app solicitante llamada additionalID
con un valor de 8e8aceg2af2ge72e78
, haz lo siguiente:
appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
Para obtener más información, consulta Cómo agregar propiedades de archivo personalizadas.
Cómo buscar archivos con una etiqueta o un valor de campo específicos
Para buscar archivos con etiquetas específicas, usa el término de búsqueda labels
con un ID de etiqueta específico. Por ejemplo: 'labels/LABEL_ID' in
labels
. Si se ejecuta correctamente, el cuerpo de la respuesta contiene todas las instancias de archivo en las que se aplicó la etiqueta.
Para buscar archivos sin un ID de etiqueta específico, usa Not
'labels/LABEL_ID' in labels
.
También puedes buscar archivos según valores de campo específicos. Por ejemplo, para buscar archivos con un valor de texto, usa labels/LABEL_ID.text_field_id ='TEXT'
.
Para obtener más información, consulta Cómo buscar archivos con una etiqueta o un valor de campo específicos.
Cómo buscar en los corpus
Las búsquedas que llaman al método list
usan corpora
de user
de forma predeterminada. Para buscar en otros corpus, como los archivos compartidos con un domain
, configura el parámetro corpora
.
Se pueden buscar varios corpus en una sola consulta, aunque es posible que se muestren resultados incompletos si el conjunto de corpus combinados es demasiado grande. Si incompleteSearch
es true
en el cuerpo de la respuesta, no se devolvieron todos los documentos. Si esto ocurre, debes acotar tu búsqueda eligiendo un corpus diferente, como user
o drive
.
Temas relacionados
- Cómo buscar unidades compartidas
- Términos y operadores de búsqueda
- Tipos de MIME compatibles con Google Workspace y Google Drive
- Funciones y permisos
- Cómo buscar archivos con una etiqueta o un valor de campo específicos