Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Как искать файлы и папки

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

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

Как использовать параметр fields

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

Получение файла по идентификатору

Чтобы получить файл, используйте метод get для ресурса files с параметром пути 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'

Чтобы посмотреть все условия запросов для файлов, ознакомьтесь с разделом Условия запросов для файлов.

Все операторы, которые можно использовать для создания запроса, перечислены в разделе Операторы запросов.

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

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

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

Что запрашивать	Пример
Оператор соответствия строк (`contains`)
Файлы, содержащие слово "привет"	`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`
Файлы, владельцем которых является пользователь test@example.org	`'test@example.org' in owners`
Файлы, для которых у пользователя test@example.org есть разрешение на запись	`'test@example.org' in writers`
Файлы, для которых у участников группы group@example.org есть разрешение на запись	`'group@example.org' in writers`
Файлы, для которых у пользователя test@example.org есть разрешение на чтение.	`'test@example.org' 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`
Файлы, в которых нет слова "привет"	`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. Также задается значение drive для параметра spaces, чтобы сузить область поиска до Диска. Если nextPageToken возвращает null, значит результатов больше нет.

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

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 вашего проекта.

Поиск в дочерних папках и файлах

Запрос parents возвращает только прямые дочерние файлы и папки, расположенные в указанной папке. Drive API не предоставляет оператор запроса или параметр для рекурсивного поиска по деревьям дочерних подпапок за один вызов API.

Чтобы выполнить поиск по папке и всем ее дочерним подпапкам и файлам, приложение должно выполнить обход дерева на стороне клиента:

Запрашивайте дочерние элементы целевой папки, используя тег 'FOLDER_ID' in parents and trashed = false.
Чтобы найти вложенные папки, отфильтруйте результаты, в которых mimeType = 'application/vnd.google-apps.folder'.
Рекурсивно или итеративно запрашивайте идентификатор каждой дочерней папки, чтобы получить ее содержимое.

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

Node.js

/**
 * Recursively searches a folder and all descendant subfolders for files.
 * @param {string} folderId The ID of the starting folder.
 * @param {Object} authClient An authorized OAuth 2.0 client.
 * @return {Promise<Array>} The list of all descendant files.
 */
async function searchFolderRecursively(folderId, authClient) {
  const {google} = require('googleapis');
  const service = google.drive({version: 'v3', auth: authClient});
  const allFiles = [];
  const foldersToSearch = [folderId];

  try {
    while (foldersToSearch.length > 0) {
      const currentFolderId = foldersToSearch.pop();
      let pageToken = null;

      do {
        const response = await service.files.list({
          q: `'${currentFolderId}' in parents and trashed = false`,
          fields: 'nextPageToken, files(id, name, mimeType)',
          pageSize: 1000,
          supportsAllDrives: true,
          includeItemsFromAllDrives: true,
          pageToken: pageToken,
        });

        const files = response.data.files || [];
        for (const file of files) {
          if (file.mimeType === 'application/vnd.google-apps.folder') {
            foldersToSearch.push(file.id);
          } else {
            allFiles.push(file);
          }
        }

        pageToken = response.data.nextPageToken;
      } while (pageToken);
    }
    return allFiles;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
    throw err;
  }
}

Python

from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

def search_folder_recursively(folder_id, creds):
    """Recursively searches a folder and all descendant subfolders for
    files.

    Args:
        folder_id: The ID of the starting folder.
        creds: An authorized OAuth 2.0 credentials object.

    Returns:
        A list of all descendant file resources.
    """
    service = build("drive", "v3", credentials=creds)
    all_files = []
    folders_to_search = [folder_id]

    try:
        while folders_to_search:
            current_folder_id = folders_to_search.pop()
            page_token = None

            while True:
                response = (
                    service.files()
                    .list(
                        q=f"'{current_folder_id}' in parents and trashed = false",
                        fields="nextPageToken, files(id, name, mimeType)",
                        pageSize=1000,
                        supportsAllDrives=True,
                        includeItemsFromAllDrives=True,
                        pageToken=page_token,
                    )
                    .execute()
                )

                for item in response.get("files", []):
                    if (
                        item.get("mimeType")
                        == "application/vnd.google-apps.folder"
                    ):
                        folders_to_search.append(item.get("id"))
                    else:
                        all_files.append(item)

                page_token = response.get("nextPageToken")
                if not page_token:
                    break

        return all_files
    except HttpError as error:
        # TODO(developer): Handle error
        print(f"An error occurred: {error}")
        return None

Как искать файлы с дополнительными свойствами

Чтобы найти файлы с определенным свойством, используйте поисковый запрос 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, порядок сортировки по умолчанию не будет задан и объекты будут возвращены в произвольном порядке.

Как искать файлы и папки Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Как использовать параметр fields

Получение файла по идентификатору

Как посмотреть список всех файлов и папок в разделе "Мой диск"

Как искать определенные файлы и папки в разделе "Мой диск"

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

Как фильтровать результаты поиска с помощью клиентской библиотеки

Java

Python

Node.js

PHP

Как посмотреть список файлов в общей папке

Node.js

curl

Поиск в дочерних папках и файлах

Node.js

Python

Как искать файлы с дополнительными свойствами

Как искать файлы по ярлыку или значению поля

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

Статьи по теме

Как искать файлы и папки