A API Google Drive oferece várias formas de pesquisar arquivos e pastas.
Use o método files.list
para retornar todos ou alguns dos arquivos e pastas de um usuário do Drive. O método files.list
também pode ser usado para extrair o fileId
necessário para alguns métodos
de recurso (como files.get
e
files.update
).
Pesquisar todos os arquivos e pastas no Meu Drive do usuário atual
Use o método files.list
sem nenhum parâmetro para retornar todos os arquivos e
pastas.
GET https://www.googleapis.com/drive/v3/files
Pesquisar arquivos ou pastas específicos no Meu Drive do usuário atual
Para pesquisar um conjunto específico de arquivos ou pastas, use o campo q
da string de consulta com o método files.list
para filtrar os arquivos a serem retornados combinando um ou mais termos de pesquisa.
Uma string de consulta contém estas três partes:
query_term operator values
Em que:
query_term
é o termo ou campo de consulta a ser pesquisado.operator
especifica a condição do termo de consulta.values
são os valores específicos que você quer usar para filtrar os resultados da pesquisa.
Para ver os termos e operadores de consulta que podem ser usados para filtrar arquivos e pastas, consulte Termos e operadores de consulta de pesquisa.
Por exemplo, a string de consulta a seguir filtra a pesquisa para retornar apenas pastas definindo o tipo MIME:
q: mimeType = 'application/vnd.google-apps.folder'
Para mais informações sobre os tipos MIME, consulte Tipos MIME compatíveis com o Google Workspace e o Google Drive.
Exemplos de string de consulta
A tabela a seguir lista exemplos de algumas strings de consulta básicas. O código real varia de acordo com a biblioteca de cliente usada na pesquisa.
O que você quer consultar | Exemplo |
---|---|
Arquivos com o nome "hello" | name = 'hello' |
Arquivos com um nome que contenha as palavras "hello" e "goodbye" | name contains 'hello' and name contains 'goodbye' |
Arquivos com um nome que não contém a palavra "hello" | not name contains 'hello' |
Arquivos que contêm o texto "importante" e estão na lixeira | fullText contains 'important' and trashed = true |
Arquivos que contêm a palavra "hello" | fullText contains 'hello' |
Arquivos que não têm a palavra "hello" | not fullText contains 'hello' |
Arquivos que contêm a frase exata "hello world" | fullText contains '"hello world"' |
Arquivos com uma consulta que contém o caractere "\" (por exemplo, "\authors") | fullText contains '\\authors' |
Arquivos que são pastas | mimeType = 'application/vnd.google-apps.folder' |
Arquivos que não são pastas | mimeType != 'application/vnd.google-apps.folder' |
Arquivos modificados após uma determinada data (o fuso horário padrão é UTC) | modifiedTime > '2012-06-04T12:00:00' |
Arquivos de imagem ou vídeo modificados após uma data específica | modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/') |
Arquivos com estrela | starred = true |
Arquivos em uma coleção (por exemplo, o ID da pasta na coleção parents ) |
'1234567' in parents |
Arquivos em uma pasta de dados do aplicativo em uma coleção | 'appDataFolder' in parents |
Arquivos dos quais o usuário "test@example.org" é o proprietário | 'test@example.org' in owners |
Os arquivos em que o usuário "test@example.org" tem permissão de gravação | 'test@example.org' in writers |
Os arquivos em que os membros do grupo "group@example.org" têm permissão de gravação | 'group@example.org' in writers |
Arquivos compartilhados com o usuário autorizado com "hello" no nome | sharedWithMe and name contains 'hello' |
Arquivos com uma propriedade de arquivo personalizada visível para todos os apps | properties has { key='mass' and value='1.3kg' } |
Arquivos com uma propriedade personalizada que pertence ao app solicitante | appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' } |
Arquivos que não foram compartilhados com ninguém nem com domínios (apenas particulares ou compartilhados com usuários ou grupos específicos) | visibility = 'limited' |
Filtrar resultados da pesquisa com uma biblioteca de cliente
O exemplo de código a seguir mostra como usar uma biblioteca de cliente para filtrar os resultados da pesquisa para nomes de arquivo e IDs de arquivos JPEG. Nesta amostra, o termo de consulta mimeType
é usado para restringir os resultados aos arquivos do tipo image/jpeg
. Ele também define
spaces
como drive
para restringir ainda mais a pesquisa ao espaço
do Drive. Quando nextPageToken
retornar null
,
não haverá mais resultados.
Java
Python
Node.js
PHP
Pesquisar arquivos com uma propriedade de arquivo personalizada
Para pesquisar arquivos com uma propriedade de arquivo personalizada, use o termo de consulta de pesquisa properties
ou appProperties
com uma chave e um valor. Por exemplo, para
pesquisar uma propriedade de arquivo personalizada que é particular para o app solicitante, chamada
additionalID
com um valor de 8e8aceg2af2ge72e78
:
appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
Para mais informações, consulte Adicionar propriedades de arquivo personalizadas.
Pesquisar arquivos com um marcador ou valor de campo específico
Para pesquisar arquivos com rótulos específicos, use o termo de consulta de pesquisa labels
com um ID de rótulo específico. Por exemplo, 'labels/LABEL_ID' in
labels
. Se a solicitação for bem-sucedida, o corpo da resposta incluirá todas as instâncias de arquivo em que o rótulo foi aplicado.
Para pesquisar arquivos sem um ID de marcador específico: Not
'labels/LABEL_ID' in labels
.
Você também pode pesquisar arquivos com base em valores de campo específicos. Por exemplo, para
pesquisar arquivos com um valor de texto:
labels/LABEL_ID.text_field_id ='TEXT'
.
Para saber mais, consulte Pesquisar arquivos com um marcador ou valor de campo específico.
Pesquisar nos corpora
As pesquisas que chamam files.list
usam a
corpora
de user
por padrão. Para pesquisar
outros corpora, como arquivos compartilhados com um domain
, defina o parâmetro
corpora
.
É possível pesquisar vários corpora em uma única consulta. No entanto, resultados incompletos podem ser retornados se o corpora combinado for muito grande. Se incompleteSearch
for
true
no corpo da resposta, nenhum documento será retornado. Se isso acontecer, restrinja a consulta escolhendo um corpora diferente, como user
ou drive
.
Temas relacionados
- Pesquisar drives compartilhados
- Termos e operadores de consulta de pesquisa
- Tipos MIME compatíveis com o Google Workspace e o Google Drive
- Papéis e permissões
- Pesquisar arquivos com um marcador ou valor de campo específico