搜索文件和文件夹

本指南介绍了 Google Drive API 如何支持多种搜索文件和文件夹的方式。

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

使用 fields 参数

如果您想指定要在响应中返回的字段,可以使用 fields system parameter 使用 files 资源的任何方法。如果您省略 fields 参数,服务器会返回特定于该方法的默认字段集。例如, list 方法仅返回每个文件的 kindidnamemimeTyperesourceKey 字段。如需返回不同的 字段,请参阅返回特定字段

获取文件

如需获取文件,请对 files资源使用get方法和fileId路径参数。 如果您不知道文件 ID,可以使用 list all files 方法列出所有文件。list

该方法会将文件作为 files 资源的实例返回。如果您提供 alt=media 参数,则响应会在响应正文中包含文件内容。如需下载 Blob 文件,请参阅下载 Blob 文件内容

如需确认下载已知恶意软件或其他 滥用文件的风险,请将 acknowledgeAbuse查询参数设置为true。此字段仅在设置了 alt=media 参数且用户是文件所有者或文件所在共享云端硬盘的组织者时适用。

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

使用不带任何参数的 list 方法返回所有文件和文件夹。

GET https://www.googleapis.com/drive/v3/files

搜索当前用户的“我的云端硬盘”中的特定文件或文件夹

如需搜索特定的一组文件或文件夹,请将查询字符串 q 字段 与 list 方法搭配使用,以通过组合一个或多个搜索字词来过滤要返回的文件。

查询字符串语法包含以下三个部分:

query_term operator values

其中:

  • query_term 是要搜索的查询字词或字段。

  • operator 指定查询字词的条件。

  • values 是您要用于过滤搜索结果的特定值。

例如,以下查询字符串通过设置 MIME 类型来过滤搜索结果,使其仅返回 文件夹:

q: mimeType = 'application/vnd.google-apps.folder'

如需查看所有文件查询字词,请参阅特定于文件的查询字词

如需查看可用于构建查询的所有查询运算符,请参阅查询 运算符

查询字符串示例

下表列出了一些基本查询字符串的示例。实际代码因您用于搜索的客户端库而异。

您还必须转义文件名中的特殊字符,以确保查询正常运行。例如,如果文件名同时包含撇号 (') 和反斜线 ("\") 字符,请使用反斜线对其进行转义:name contains 'quinn\'s paper\\essay'

您要查询的内容 示例
名称为“hello”的文件 name = 'hello'
名称包含“hello”和“goodbye”字词的文件 name contains 'hello' and name contains 'goodbye'
名称不包含“hello”字词的文件 not name contains 'hello'
包含文本“important”且位于回收站中的文件 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'
在给定日期之后修改的文件(默认时区为 UTC) 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

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, files(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
import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Searches for files in Google Drive.
 * @return {Promise<object[]>} A list of files.
 */
async function searchFile() {
  // Authenticate with Google and get an authorized client.
  // TODO (developer): Use an appropriate auth mechanism for your app.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Drive API client (v3).
  const service = google.drive({version: 'v3', auth});

  // Search for files with the specified query.
  const result = await service.files.list({
    q: "mimeType='image/jpeg'",
    fields: 'nextPageToken, files(id, name)',
    spaces: 'drive',
  });

  // Print the name and ID of each found file.
  (result.data.files ?? []).forEach((file) => {
    console.log('Found file:', file.name, file.id);
  });

  return result.data.files ?? [];
}

PHP

drive/snippets/drive_v3/src/DriveSearchFiles.php
<?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;
    }
}

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

如需搜索具有自定义文件属性的文件,请将 propertiesappProperties 搜索查询字词与键和值搭配使用。例如,如需搜索对请求方应用私有的自定义文件属性(名为 additionalID,值为 8e8aceg2af2ge72e78),请执行以下操作:

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'

如需了解详情,请参阅搜索具有特定标签或字段 值的文件。

搜索语料库

默认情况下,使用 list 方法时,corpora 查询参数 会设置为 user 项集合。如需搜索其他项集合(例如与 domain 共享的项集合),您必须明确设置 corpora 参数。

您可以在单个查询中搜索多个语料库;但是,如果组合的语料库过大,API 可能会返回不完整的结果。检查响应正文中的 incompleteSearch 字段。如果该字段为 true,则表示省略了一些文档。如需解决此问题,请将 corpora 缩小为使用 userdrive

orderBy查询 参数与list方法一起使用时,请避免对 大型项集合使用createdTime键进行查询,因为这需要额外的处理,并且可能会导致 超时或其他问题。如需对大型项集合进行与时间相关的排序,您可以使用 modifiedTime,因为它经过优化,可以处理这些查询。例如,?orderBy=modifiedTime

如果您省略 orderBy 查询参数,则没有默认排序顺序,并且项会随意返回。