搜索文件和文件夹

Google Drive API 支持通过多种方式搜索文件和文件夹。

您可以使用 files.list 方法返回 所有或部分云端硬盘用户的文件和文件夹。files.list 方法还可用于检索某些资源所需的 fileId 方法(例如 files.getfiles.update)。

搜索当前用户的“我的云端硬盘”中的所有文件和文件夹

使用不带任何参数的 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”字样的文件和“再见” 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 类型的文件。它还会将 从 spacesdrive,进一步将搜索范围缩小到 云端硬盘 空间。当 nextPageToken 返回 null 时, 没有更多结果。

Java

drive/snippets/drive_v3/src/main/java/SearchFile.java
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.api.services.drive.model.File;
import com.google.api.services.drive.model.FileList;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

/* Class to demonstrate use-case of search files. */
public class SearchFile {

  /**
   * Search for specific set of files.
   *
   * @return search result list.
   * @throws IOException if service account credentials file not found.
   */
  public static List<File> searchFile() throws IOException {
           /*Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
           guides on implementing OAuth2 for your application.*/
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList(DriveScopes.DRIVE_FILE));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();

    List<File> files = new ArrayList<File>();

    String pageToken = null;
    do {
      FileList result = service.files().list()
          .setQ("mimeType='image/jpeg'")
          .setSpaces("drive")
          .setFields("nextPageToken, items(id, title)")
          .setPageToken(pageToken)
          .execute();
      for (File file : result.getFiles()) {
        System.out.printf("Found file: %s (%s)\n",
            file.getName(), file.getId());
      }

      files.addAll(result.getFiles());

      pageToken = result.getNextPageToken();
    } while (pageToken != null);

    return files;
  }
}

Python

drive/snippets/drive-v3/file_snippet/search_file.py
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def search_file():
  """Search file in drive location

  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()

  try:
    # create drive api client
    service = build("drive", "v3", credentials=creds)
    files = []
    page_token = None
    while True:
      # pylint: disable=maybe-no-member
      response = (
          service.files()
          .list(
              q="mimeType='image/jpeg'",
              spaces="drive",
              fields="nextPageToken, files(id, name)",
              pageToken=page_token,
          )
          .execute()
      )
      for file in response.get("files", []):
        # Process change
        print(f'Found file: {file.get("name")}, {file.get("id")}')
      files.extend(response.get("files", []))
      page_token = response.get("nextPageToken", None)
      if page_token is None:
        break

  except HttpError as error:
    print(f"An error occurred: {error}")
    files = None

  return files


if __name__ == "__main__":
  search_file()

Node.js

drive/snippets/drive_v3/file_snippets/search_file.js
/**
 * Search file in drive location
 * @return{obj} data file
 * */
async function searchFile() {
  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const service = google.drive({version: 'v3', auth});
  const files = [];
  try {
    const res = await service.files.list({
      q: 'mimeType=\'image/jpeg\'',
      fields: 'nextPageToken, files(id, name)',
      spaces: 'drive',
    });
    Array.prototype.push.apply(files, res.files);
    res.data.files.forEach(function(file) {
      console.log('Found file:', file.name, file.id);
    });
    return res.data.files;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

PHP

drive/snippets/drive_v3/src/DriveSearchFiles.php
use Google\Client;
use Google\Service\Drive;
function searchFiles()
{
    try {
        $client = new Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Drive::DRIVE);
        $driveService = new Drive($client);
        $files = array();
        $pageToken = null;
        do {
            $response = $driveService->files->listFiles(array(
                'q' => "mimeType='image/jpeg'",
                'spaces' => 'drive',
                'pageToken' => $pageToken,
                'fields' => 'nextPageToken, files(id, name)',
            ));
            foreach ($response->files as $file) {
                printf("Found file: %s (%s)\n", $file->name, $file->id);
            }
            array_push($files, $response->files);

            $pageToken = $response->pageToken;
        } while ($pageToken != null);
        return $files;
    } catch(Exception $e) {
       echo "Error Message: ".$e;
    }
}

搜索具有自定义文件属性的文件

要搜索具有自定义文件属性的文件,请使用 properties 或 包含键和值的 appProperties 搜索查询字词。例如, 搜索名为 值为 8e8aceg2af2ge72e78additionalID

appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }

有关详情,请参阅添加自定义文件 属性

搜索具有特定标签或字段值的文件

如需搜索带有特定标签的文件,请使用 labels 搜索查询字词 具有特定标签 ID 的过滤器。例如:'labels/LABEL_ID' in labels。如果成功,响应正文将包含 标签。

如需搜索没有特定标签 ID 的文件,请执行以下操作:Not 'labels/LABEL_ID' in labels

您还可以根据特定字段值搜索文件。例如, 搜索包含文本值的文件: labels/LABEL_ID.text_field_id ='TEXT'

有关详情,请参阅搜索具有特定标签或字段的文件 值

搜索语料库

调用 files.list 的搜索使用 默认数量为 corpora,上限为 user。搜索 其他语料库(例如与 domain 共享的文件)设置 corpora 参数。

虽然结果不完整,但可在一次查询中搜索多个语料库 组合的语料库过大时可能会返回。如果incompleteSearch true,则未返回所有文档。如果 则应通过选择其他语料库来缩小查询范围,例如 userdrive