Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

ファイルとフォルダを検索する

このガイドでは、Google Drive API がファイルとフォルダを検索する複数の方法をサポートしていることについて説明します。

files リソースで list メソッドを使用すると、ドライブユーザーのファイルとフォルダのすべてまたは一部を返すことができます。list メソッドは、一部のリソースメソッド（get メソッドや update メソッドなど）に必要な fileId を取得するためにも使用できます。

fields パラメータを使用する

レスポンスで返すフィールドを指定する場合は、files リソースの任意の方法で fields システムパラメータを設定できます。fields パラメータを省略すると、サーバーはメソッドに固有のデフォルトのフィールドセットを返します。たとえば、list メソッドは、各ファイルの kind、id、name、mimeType、resourceKey フィールドのみを返します。別のフィールドを返すには、特定のフィールドを返すをご覧ください。

ファイルを取得する

ファイルを取得するには、fileId パスパラメータを使用して files リソースの get メソッドを使用します。ファイル ID がわからない場合は、list メソッドを使用してすべてのファイルを一覧表示できます。

このメソッドは、ファイルを files リソースのインスタンスとして返します。alt=media パラメータを指定すると、レスポンスの本文にファイルの内容が含まれます。blob ファイルをダウンロードするには、blob ファイルのコンテンツをダウンロードするをご覧ください。

既知のマルウェアやその他の不正なファイルをダウンロードするリスクを認識するには、acknowledgeAbuse クエリパラメータを true に設定します。このフィールドは、alt=media パラメータが設定されていて、ユーザーがファイルのオーナーであるか、ファイルが保存されている共有ドライブの管理者のいずれかである場合にのみ適用されます。

現在のユーザーのマイドライブにあるすべてのファイルとフォルダを検索する

パラメータなしで list メソッドを使用すると、すべてのファイルとフォルダが返されます。

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

現在のユーザーのマイドライブ内の特定のファイルまたはフォルダを検索する

特定のファイルやフォルダのセットを検索するには、list メソッドで q クエリ文字列フィールドを使用して、1 つ以上の検索語句を組み合わせて返すファイルをフィルタします。

クエリ文字列の構文には、次の 3 つの部分が含まれます。

query_term operator values

ここで

query_term は、検索するクエリ語句またはフィールドです。
operator は、クエリ用語の条件を指定します。
values は、検索結果のフィルタに使用する特定の値です。

たとえば、次のクエリ文字列は、MIME タイプを設定して、フォルダのみを返すように検索をフィルタします。

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

ファイルクエリのすべての用語を表示するには、ファイル固有のクエリ用語をご覧ください。

クエリの作成に使用できるすべてのクエリ演算子を表示するには、クエリ演算子をご覧ください。

クエリ文字列の例

次の表に、基本的なクエリ文字列の例を示します。実際のコードは、検索に使用するクライアントライブラリによって異なります。

クエリが正しく動作するように、ファイル名内の特殊文字をエスケープする必要もあります。たとえば、ファイル名にアポストロフィ（'）とバックスラッシュ（"\"）の両方が含まれている場合は、バックスラッシュを使用してエスケープします（name contains 'quinn\'s paper\\essay'）。

クエリの対象	例
文字列一致演算子（`contains`）
「hello」という単語を含むファイル	`fullText contains 'hello'`
「hello world」という語句が完全に一致するファイル	`fullText contains '"hello world"'`
「\」文字を含むクエリ（「\authors」など）を含むファイル	`fullText contains '\\authors'`
名前に「budget」が含まれるファイル	`name contains 'budget'`
等価演算子と不等価演算子（`=`、`!=`）
「hello」という名前のファイル	`name = 'hello'`
フォルダであるファイル	`mimeType = 'application/vnd.google-apps.folder'`
フォルダ以外のファイル	`mimeType != 'application/vnd.google-apps.folder'`
スター付きのファイル	`starred = true`
ゴミ箱内のファイル	`trashed = true`
ゴミ箱にないファイル	`trashed = false`
特定のファイル ID を指すショートカット	`shortcutDetails.targetId = '1987654321'`
ユーザーやドメインと共有されていないファイル（非公開、または特定のユーザーやグループと共有されているファイル）	`visibility = 'limited'`
比較演算子（`>`、`>=`、`<`、`<=`）
指定した日付以降に変更されたファイル（デフォルトのタイムゾーンは UTC）	`modifiedTime > '2012-06-04T12:00:00'`
2023 年 1 月 1 日以降に作成されたファイル	`createdTime > '2023-01-01T00:00:00'`
2023 年 1 月 1 日より前に変更されたファイル	`modifiedTime < '2023-01-01T00:00:00'`
コレクションメンバーシップ演算子（`in`）
コレクション内のファイル（例: `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`
ユーザー「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'`
「important」というテキストが含まれていて、ゴミ箱にあるファイル	`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'`
ゴミ箱にない「Project Plan」という名前のファイル	`name = 'Project Plan' and trashed = false`

クライアントライブラリで検索結果をフィルタする

次のコードサンプルは、クライアントライブラリを使用して検索結果を JPEG ファイルのファイル名と ID にフィルタする方法を示しています。このサンプルでは、mimeType クエリ用語を使用して、結果を image/jpeg タイプのファイルに絞り込んでいます。また、spaces を drive に設定して、検索をドライブのスペースに絞り込みます。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;
    }
}

カスタムファイルプロパティでファイルを検索する

カスタムファイルプロパティでファイルを検索するには、properties または appProperties の検索クエリ語句にキーと値を指定します。たとえば、値が 8e8aceg2af2ge72e78 で、リクエスト元のアプリに非公開の additionalID というカスタムファイルプロパティを検索するには:

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' を使用します。

詳細については、特定のラベルまたはフィールド値を持つファイルを検索するをご覧ください。

コーパスを検索する

デフォルトでは、list メソッドが使用されると、user アイテムコレクションは corpora クエリパラメータに設定されます。domain と共有されているアイテムコレクションなど、他のアイテムコレクションを検索するには、corpora パラメータを明示的に設定する必要があります。

1 つのクエリで複数のコーパスを検索できますが、結合されたコーパスが大きすぎると、API が不完全な結果を返すことがあります。レスポンスの本文で incompleteSearch フィールドを確認します。true の場合、一部のドキュメントが省略されています。この問題を解決するには、corpora を絞り込んで user または drive を使用します。

list メソッドで orderBy クエリパラメータを使用する場合は、大きなアイテムコレクションに対するクエリで createdTime キーを使用しないでください。追加の処理が必要になり、タイムアウトなどの問題が発生する可能性があります。大きなアイテムコレクションで時間に関連する並べ替えを行う場合は、これらのクエリを処理するように最適化されている modifiedTime を代わりに使用できます。例: ?orderBy=modifiedTime

orderBy クエリパラメータを省略すると、デフォルトの並べ替え順序がなくなり、項目は任意に返されます。

ファイルとフォルダを検索する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

fields パラメータを使用する

ファイルを取得する

現在のユーザーのマイドライブにあるすべてのファイルとフォルダを検索する

現在のユーザーのマイドライブ内の特定のファイルまたはフォルダを検索する

クエリ文字列の例

クライアント ライブラリで検索結果をフィルタする

Java

Python

Node.js

PHP

カスタム ファイル プロパティでファイルを検索する

特定のラベルまたはフィールド値を持つファイルを検索する

コーパスを検索する

関連トピック

ファイルとフォルダを検索する

クライアントライブラリで検索結果をフィルタする

カスタムファイルプロパティでファイルを検索する