Google Drive API 支持通过多种方式搜索文件和文件夹。
您可以使用 files.list
方法返回云端硬盘用户的全部或部分文件和文件夹。files.list
方法还可用于检索某些资源方法(如 files.get
和 files.update
)所需的 fileId
。
搜索当前用户的“我的云端硬盘”中的所有文件和文件夹
使用不带任何参数的 files.list
方法可返回所有文件和文件夹。
GET https://www.googleapis.com/drive/v3/files
在当前用户的“我的云端硬盘”中搜索特定文件或文件夹
如需搜索一组特定的文件或文件夹,请将查询字符串 q
字段与 files.list
方法结合使用,通过组合一个或多个搜索字词来过滤要返回的文件。
查询字符串包含以下三个部分:
query_term operator values
其中:
query_term
是要搜索的查询字词或字段。operator
指定查询字词的条件。values
是您要用于过滤搜索结果的特定值。
如需查看可用于过滤文件和文件夹的查询字词和运算符,请参阅搜索查询字词和运算符。
例如,以下查询字符串通过设置 MIME 类型过滤搜索,使其仅返回文件夹:
q: mimeType = 'application/vnd.google-apps.folder'
如需详细了解 MIME 类型,请参阅 Google Workspace 和 Google 云端硬盘支持的 MIME 类型。
查询字符串示例
下表列出了一些基本查询字符串的示例。实际代码因您用于搜索的客户端库而异。
您还必须对文件名中的特殊字符进行转义,以确保查询正常运行。例如,如果文件名同时包含撇号 ('
) 和反斜杠 ("\"
) 字符,请使用反斜杠对其进行转义:name
contains 'quinn\'s paper\\essay'
。
您要查询的内容 | 示例 |
---|---|
名称为“hello”的文件 | name = 'hello' |
名称中包含“hello”和“goodbye”的文件 | name contains 'hello' and name contains 'goodbye' |
名称中不包含“hello”一词的文件 | not name contains 'hello' |
回收站中包含文本“重要”的文件 | fullText contains 'important' and trashed = true |
包含字词“hello”的文件 | fullText contains 'hello' |
不包含“hello”一词的文件 | not fullText contains 'hello' |
包含“hello world”确切词组的文件 | fullText contains '"hello world"' |
文件的查询中包含“\”字符(例如“\authors”) | fullText contains '\\authors' |
属于文件夹的文件 | mimeType = 'application/vnd.google-apps.folder' |
非文件夹文件 | mimeType != 'application/vnd.google-apps.folder' |
在指定日期(默认时区为世界协调时间)之后修改的文件 | modifiedTime > '2012-06-04T12:00:00' |
在特定日期后修改的图片文件或视频文件 | modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/') |
已加星标的文件 | starred = true |
集合中的文件(例如,parents 集合中的文件夹 ID) |
'1234567' in parents |
集合中的应用数据文件夹内的文件 | 'appDataFolder' in parents |
用户“test@example.org”是所有者的文件 | 'test@example.org' in owners |
用户“test@example.org”具有写入权限的文件 | 'test@example.org' in writers |
群组“group@example.org”的成员拥有写入权限的文件 | 'group@example.org' in writers |
与授权用户共享的文件,名称中含有“hello” | sharedWithMe and name contains 'hello' |
具有自定义文件属性的文件对所有应用可见 | properties has { key='mass' and value='1.3kg' } |
包含请求方应用的专用自定义文件属性的文件 | appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' } |
未与任何人或网域共享的文件(仅不公开,或者仅与特定用户或群组共享的文件) | visibility = 'limited' |
使用客户端库过滤搜索结果
以下代码示例展示了如何使用客户端库过滤搜索结果,使其仅显示 JPEG 文件的文件名和 ID。此示例使用 mimeType
查询字词将结果范围缩小为 image/jpeg
类型的文件。此外,它还会将 spaces
设置为 drive
,以进一步将搜索范围缩小到 云端硬盘空间。当 nextPageToken
返回 null
时,没有更多结果。
Java
Python
Node.js
PHP
搜索具有自定义文件属性的文件
如需搜索具有自定义文件属性的文件,请使用 properties
或 appProperties
搜索查询字词以及键和值。例如,如需搜索名为 additionalID
且值为 8e8aceg2af2ge72e78
的发出请求的应用专用的自定义文件属性,请执行以下命令:
appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
如需了解详情,请参阅添加自定义文件属性。
搜索具有特定标签或字段值的文件
如需搜索带有特定标签的文件,请使用具有特定标签 ID 的 labels
搜索查询字词。例如:'labels/LABEL_ID' in
labels
。如果成功,响应正文将包含应用了标签的所有文件实例。
如需搜索没有特定标签 ID 的文件,请执行以下操作:Not
'labels/LABEL_ID' in labels
。
您还可以根据特定字段值搜索文件。例如,如需搜索包含文本值的文件,请使用以下格式:labels/LABEL_ID.text_field_id ='TEXT'
。
如需了解详情,请参阅搜索具有特定标签或字段值的文件。
搜索语料库
默认情况下,调用 files.list
的搜索使用 user
的 corpora
。如需搜索其他语料库(例如与 domain
共享的文件),请设置 corpora
参数。
可以在单个查询中搜索多个语料库,但如果合并后的语料库太大,可能会返回不完整的结果。如果响应正文中的 incompleteSearch
为 true
,则不会返回所有文档。如果发生这种情况,您应通过选择其他语料库(如 user
或 drive
)来缩小查询范围。