Поиск файлов и папок

В этом руководстве объясняется, как API Google Drive поддерживает несколько способов поиска файлов и папок.

Метод list ресурса files позволяет получить доступ ко всем или некоторым файлам и папкам пользователя Google Диска. Также метод list используется для получения идентификатора fileId , необходимого для некоторых методов ресурса (например, методов get и update ).

Используйте параметр fields.

Если вы хотите указать поля, которые должны быть возвращены в ответе, вы можете задать системный параметр fields с помощью любого метода ресурса files . Если вы опустите параметр fields , сервер вернет набор полей по умолчанию, специфичных для данного метода. Например, метод list возвращает только поля kind , id , name , mimeType и resourceKey для каждого файла. Чтобы вернуть другие поля, см. раздел «Возврат специфических полей» .

Получить файл по ID

Чтобы получить доступ к файлу, используйте метод get ресурса files с параметром `path` ` fileId . Если идентификатор файла неизвестен, вы можете вывести список всех файлов с помощью метода list .

Метод возвращает файл в виде экземпляра ресурса files . Если вы укажете параметр alt=media , то в теле ответа будет содержаться содержимое файла. Чтобы загрузить файл BLOB-объекта, см. раздел «Загрузка содержимого файла BLOB-объекта» .

Чтобы подтвердить риск загрузки известных вредоносных программ или других вредоносных файлов, установите параметр запроса acknowledgeAbuse в true . Это поле применимо только в том случае, если установлен параметр alt=media , и пользователь является либо владельцем файла, либо организатором общего диска, на котором находится файл.

Список всех файлов и папок на моем диске

Используйте метод list без параметров, чтобы получить все файлы и папки в папке «Мой диск» текущего пользователя.

Следующая команда curl показывает, как вывести список всех файлов:

curl -X GET \
  'https://www.googleapis.com/drive/v3/files' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: application/json'

Замените ACCESS_TOKEN на авторизованный токен доступа OAuth 2.0 .

Поиск определенных файлов и папок в разделе «Мой диск».

Для поиска определенного набора файлов или папок в папке «Мой диск» текущего пользователя используйте поле запроса q с методом list , чтобы отфильтровать возвращаемые файлы, комбинируя один или несколько поисковых запросов.

Синтаксис строки запроса состоит из следующих трех частей:

query_term operator values

Где:

• query_term — это поисковый запрос или поле, по которому будет производиться поиск.

• operator задает условие для поискового запроса.

• values — это конкретные значения, которые вы хотите использовать для фильтрации результатов поиска.

Например, следующая строка запроса фильтрует поиск, чтобы возвращать только папки, задавая MIME-тип :

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

Чтобы просмотреть все поисковые запросы по файлам, см. раздел «Поисковые запросы по конкретным файлам» .

Чтобы просмотреть все операторы запросов, которые можно использовать для построения запроса, см. раздел «Операторы запросов» .

Примеры строк запроса

В таблице ниже приведены примеры некоторых базовых строк запроса. Фактический код может отличаться в зависимости от используемой вами клиентской библиотеки для поиска.

Важно: В следующих запросах используются поля из Drive API версии 3. Некоторые поля ресурсов изменились между версиями 2 и 3. Например, name заменяет title . Если вы используете Drive API версии 2 , скорректируйте эти запросы, чтобы использовать поля версии 2. Для получения дополнительной информации см. справочник по сравнению Drive API версий 2 и 3 .

Для корректной работы запроса необходимо также экранировать специальные символы в именах файлов. Например, если имя файла содержит как апостроф ( ' ), так и обратную косую черту ( "\" ), используйте обратную косую черту для их экранирования: name contains 'quinn\'s paper\\essay' .

Примечание: В этих примерах используется незакодированный параметр q , где name = 'hello' кодируется как name+%3d+%27hello%27 . Клиентские библиотеки обрабатывают это кодирование автоматически.

Что следует запросить	Пример
Оператор сопоставления строк ( contains )
Файлы, содержащие слово "hello"	fullText contains 'hello'
Файлы, содержащие точную фразу "hello world"	fullText contains '"hello world"'
Файлы, в запросе которых содержится символ "\" (например, "\authors")	fullText contains '\\authors'
Файлы, в имени которых содержится слово "бюджет".	name contains 'budget'
Операторы равенства и неравенства ( = , != )
Файлы с именем "hello"	name = 'hello'
Файлы, являющиеся папками	mimeType = 'application/vnd.google-apps.folder'
Файлы, которые не являются папками	mimeType != 'application/vnd.google-apps.folder'
Файлы, отмеченные звездочкой	starred = true
Файлы, находящиеся в корзине	trashed = true
Файлы, которые не находятся в корзине	trashed = false
Ярлыки, указывающие на конкретный идентификатор файла.	shortcutDetails.targetId = '1987654321'
Файлы, которые не были предоставлены никому или никаким доменам (частные или предоставлены определенным пользователям или группам).	visibility = 'limited'
Файлы, доступные любому пользователю по ссылке.	visibility = 'anyoneWithLink'
Файлы, которые находятся в открытом доступе в интернете.	visibility = 'anyoneCanFind'
Операторы сравнения ( > , >= , < , <= )
Файлы, измененные после указанной даты (часовой пояс по умолчанию — UTC).	modifiedTime > '2012-06-04T12:00:00'
Файлы, созданные после 1 января 2023 года.	createdTime > '2023-01-01T00:00:00'
Файлы, измененные до 1 января 2023 года.	modifiedTime < '2023-01-01T00:00:00'
Оператор членства в коллекции ( in )
Файлы внутри коллекции (например, идентификатор папки в parents коллекции)	'1234567' in parents
Файлы в папке данных приложения	'appDataFolder' in parents
Файлы, владельцем которых является пользователь "[e-mail]".	'[e-mail]' in owners
Файлы, для которых пользователь "[e-mail]" имеет права на запись.	'[e-mail]' in writers
Файлы, для которых у участников группы "[e-mail]" есть права на запись.	'[e-mail]' in writers
Файлы, для которых пользователь "[e-mail]" имеет права на чтение.	'[e-mail]' in readers
Оператор сопоставления коллекций ( has )
Файлы с пользовательскими свойствами, видимыми для всех приложений.	properties has { key='mass' and value='1.3kg' }
Файлы с пользовательским свойством, доступным только запрашивающему приложению.	appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
Файлы, имеющие пользовательское свойство с ключом "department" (независимо от значения).	properties has { key='department' }
Логические операторы ( and , or , not )
Файлы, в названии которых содержатся слова «hello» и «goodbye».	name contains 'hello' and name contains 'goodbye'
Файлы, в имени которых отсутствует слово "hello".	not name contains 'hello'
Файлы, содержащие текст "важно", находятся в корзине.	fullText contains 'important' and trashed = true
Файлы, в которых отсутствует слово "hello"	not fullText contains 'hello'
Файлы изображений или видео, измененные после определенной даты.	modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')
Файлы, предоставленные авторизованному пользователю, в названии которых содержится "hello".	sharedWithMe and name contains 'hello'
Файлы, представляющие собой папки или ярлыки.	mimeType = 'application/vnd.google-apps.folder' or mimeType = 'application/vnd.google-apps.shortcut'
Файлы с названием "План проекта", которые не находятся в корзине.	name = 'Project Plan' and trashed = false
Файлы в определенной папке, которые не находятся в корзине.	'1234567' in parents and trashed = false

Фильтрация результатов поиска с помощью клиентской библиотеки

Приведённый ниже пример кода демонстрирует, как использовать клиентскую библиотеку для фильтрации результатов поиска по именам и идентификаторам файлов JPEG. В этом примере используется поисковый запрос mimeType для сужения результатов до файлов типа image/jpeg . Также устанавливаются spaces для drive , чтобы ещё больше сузить поиск до пространства Drive . Если nextPageToken возвращает null , результатов больше нет.

Примечание: Если вы используете более старую версию Drive API v2, примеры кода можно найти на GitHub . Узнайте, как перейти на Drive API v3 .

Java

drive/snippets/drive_v3/src/main/java/SearchFile.java

Посмотреть на GitHub

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

Посмотреть на GitHub

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

Посмотреть на GitHub

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

Посмотреть на GitHub

<?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;
    }
}

Список файлов в общедоступной папке

Для поиска или отображения списка файлов в общедоступной папке (доступ к которой установлен как «Любой, у кого есть ссылка» или «Общедоступная в интернете») используйте метод list ресурса files с параметром запроса q , настроенным на фильтрацию по идентификатору папки в parents коллекции:

'FOLDER_ID' in parents and trashed = false

При отображении списка файлов в общедоступной папке можно аутентифицировать запросы, используя ключ API вместо учетных данных пользователя OAuth 2.0. Если папка находится на общем диске, необходимо также установить supportsAllDrives=true и includeItemsFromAllDrives=true в запросе.

Приведенные ниже примеры кода показывают, как вывести список файлов в общедоступной папке:

Node.js

/**
 * List files in a public folder using an API key.
 * @param {string} folderId The ID of the public folder.
 * @param {string} apiKey Your Google Cloud API key.
 * @return {Promise<Array>} The list of files.
 */
async function listPublicFolder(folderId, apiKey) {
  const {google} = require('googleapis');
  const service = google.drive({version: 'v3', auth: apiKey});

  try {
    const response = await service.files.list({
      q: `'${folderId}' in parents and trashed = false`,
      fields: 'nextPageToken, files(id, name, mimeType)',
      supportsAllDrives: true,
      includeItemsFromAllDrives: true,
    });
    const files = response.data.files;
    console.log('Files:');
    for (const file of files) {
      console.log(`${file.name} (${file.id})`);
    }
    return files;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

локон

curl -G \
  'https://www.googleapis.com/drive/v3/files' \
  --data-urlencode "q='FOLDER_ID' in parents and trashed = false" \
  --data-urlencode 'supportsAllDrives=true' \
  --data-urlencode 'includeItemsFromAllDrives=true' \
  --data-urlencode 'fields=nextPageToken,files(id,name,mimeType)' \
  --data-urlencode 'key=API_KEY' \
  -H 'Accept: application/json'

Замените следующее:

• FOLDER_ID : Идентификатор общедоступной папки.
• API_KEY : Ключ API вашего проекта.

Поиск файлов с пользовательскими свойствами

Для поиска файлов с пользовательскими свойствами используйте поисковый запрос ` properties или ` appProperties , указав ключ и значение. Например, для поиска пользовательского свойства файла, являющегося частным для запрашивающего приложения, с именем additionalID и значением ` 8e8aceg2af2ge72e78 :

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

Для получения дополнительной информации см. раздел «Добавление пользовательских свойств файла» .

Поиск файлов по метке или значению поля.

Для поиска файлов с определенными метками используйте поисковый запрос labels с конкретным идентификатором метки.

Для поиска файлов с определенной меткой:

'labels/LABEL_ID' in labels

Для поиска файлов, которым не присвоена определенная метка:

not 'labels/LABEL_ID' in labels

Для поиска файлов по значению определенного поля метки:

labels/LABEL_ID.FIELD_ID = 'VALUE'

В случае успеха тело ответа будет содержать все экземпляры файлов, соответствующие запросу. Дополнительную информацию см. в разделе «Поиск файлов с определенной меткой или значением поля» .

Поиск по корпусам

По умолчанию коллекция элементов user задается в параметре запроса corpora при использовании метода list . Для поиска в других коллекциях элементов, например, общих для domain , необходимо явно указать параметр corpora .

Вы можете выполнять поиск по нескольким корпусам в одном запросе; однако, если объединенный корпус слишком велик, API может вернуть неполные результаты. Проверьте поле incompleteSearch в теле ответа. Если оно true , значит, некоторые документы были пропущены. Чтобы решить эту проблему, сузьте corpora , используя либо user , либо drive .

При использовании параметра запроса orderBy в методе list избегайте использования ключа createdTime для запросов к большим коллекциям элементов, поскольку это требует дополнительной обработки и может привести к таймаутам или другим проблемам. Для сортировки по времени в больших коллекциях элементов можно использовать modifiedTime , поскольку он оптимизирован для обработки таких запросов. Например, установите orderBy равным modifiedTime (или modifiedTime desc ).

Если опустить параметр запроса orderBy , порядок сортировки по умолчанию отсутствует, и элементы возвращаются произвольно.

Связанные темы

• Поиск общих дисков
• Поисковые запросы и операторы
• Google Workspace и Google Drive поддерживают типы MIME.
• Роли и права доступа
• Поиск файлов с определенной меткой или значением поля.