ค้นหาไฟล์และโฟลเดอร์

คู่มือนี้อธิบายวิธีที่ 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 เพื่อกรองไฟล์ที่จะแสดงผลโดยรวมข้อความค้นหาอย่างน้อย 1 รายการ

ไวยากรณ์สตริงการค้นหามี 3 ส่วนต่อไปนี้

query_term operator values

โดยที่

• query_term คือข้อความค้นหาหรือช่องที่จะค้นหา

• operator ระบุเงื่อนไขสำหรับข้อความค้นหา

• values คือค่าที่เฉพาะเจาะจงที่คุณต้องการใช้เพื่อกรองผลการค้นหา

ตัวอย่างเช่น สตริงการค้นหาต่อไปนี้จะกรองการค้นหาเพื่อแสดงผลเฉพาะ โฟลเดอร์โดยการตั้งค่า ประเภท MIME:

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

หากต้องการดูข้อความค้นหาไฟล์ทั้งหมด โปรดดู ข้อความค้นหาที่เฉพาะเจาะจงกับไฟล์

หากต้องการดูโอเปอเรเตอร์การค้นหาทั้งหมดที่คุณใช้เพื่อสร้างการค้นหาได้ โปรดดูโอเปอเรเตอร์ การค้นหา

ตัวอย่างสตริงการค้นหา

ตารางต่อไปนี้แสดงตัวอย่างสตริงการค้นหาพื้นฐานบางรายการ โค้ดจริงจะแตกต่างกันไปตามไลบรารีของไคลเอ็นต์ที่คุณใช้สำหรับการค้นหา

นอกจากนี้ คุณต้องหลีกเลี่ยงการใช้อักขระพิเศษในชื่อไฟล์เพื่อให้การค้นหาทำงานได้อย่างถูกต้อง ตัวอย่างเช่น หากชื่อไฟล์มีทั้งอักขระอะพอสทรอฟี (') และแบ็กสแลช ("\") ให้ใช้แบ็กสแลชเพื่อหลีกเลี่ยงการใช้อักขระเหล่านั้น: name contains 'quinn\'s paper\\essay'.

กรองผลการค้นหาด้วยไลบรารีของไคลเอ็นต์

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีใช้ไลบรารีของไคลเอ็นต์เพื่อกรองผลการค้นหาให้แสดงเฉพาะชื่อไฟล์และรหัสของไฟล์ JPEG ตัวอย่างนี้ใช้ข้อความค้นหา mimeType เพื่อจำกัดผลการค้นหาให้แสดงเฉพาะไฟล์ประเภท image/jpeg นอกจากนี้ ยังตั้งค่า spaces เป็น drive เพื่อจำกัดการค้นหาให้แสดงเฉพาะพื้นที่ไดรฟ์ เมื่อ nextPageToken แสดงผล null แสดงว่าไม่มีผลการค้นหาเพิ่มเติม

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

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()

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
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 query เพื่อกรองตามรหัสของโฟลเดอร์ในคอลเล็กชัน parents ดังนี้

'FOLDER_ID' in parents and trashed = false

เมื่อแสดงไฟล์ในโฟลเดอร์สาธารณะ คุณสามารถตรวจสอบสิทธิ์คำขอโดยใช้ คีย์ API แทนข้อมูลเข้าสู่ระบบผู้ใช้ OAuth 2.0 ได้ หากโฟลเดอร์อยู่ในไดรฟ์ที่แชร์ คุณต้องตั้งค่า supportsAllDrives=true และ includeItemsFromAllDrives=true ในคำขอด้วย

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีแสดงไฟล์ในโฟลเดอร์สาธารณะ

/**
 * 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'

ค้นหาโฟลเดอร์และไฟล์ที่สืบทอดแบบเรียกซ้ำ

ข้อความค้นหา parents จะแสดงผลเฉพาะไฟล์และโฟลเดอร์ย่อยโดยตรงที่อยู่ในโฟลเดอร์ที่ระบุ Drive API ไม่มีโอเปอเรเตอร์การค้นหาหรือพารามิเตอร์สำหรับการค้นหาแบบเรียกซ้ำในโครงสร้างโฟลเดอร์ย่อยที่สืบทอดในการเรียก API ครั้งเดียว

หากต้องการค้นหาโฟลเดอร์และโฟลเดอร์ย่อยและไฟล์ที่สืบทอดทั้งหมด แอปพลิเคชันของคุณต้องทำการข้ามโครงสร้างแบบฝั่งไคลเอ็นต์ ดังนี้

1. ค้นหาไฟล์ย่อยโดยตรงของโฟลเดอร์เป้าหมายโดยใช้ 'FOLDER_ID' in parents and trashed = false
2. ระบุโฟลเดอร์ย่อยโดยกรองผลการค้นหาที่ mimeType = 'application/vnd.google-apps.folder'
3. ค้นหารหัสของโฟลเดอร์ย่อยแต่ละรายการแบบเรียกซ้ำหรือแบบวนซ้ำเพื่อดึงข้อมูลเนื้อหา

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีค้นหาโฟลเดอร์และโฟลเดอร์ย่อยแบบเรียกซ้ำ

/**
 * 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;
  }
}

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 จะไม่มีลำดับการจัดเรียงเริ่มต้นและระบบจะแสดงผลรายการแบบสุ่ม

หัวข้อที่เกี่ยวข้อง

• ค้นหาไดรฟ์ที่แชร์
• คำค้นหาและโอเปอเรเตอร์
• ประเภท MIME ที่ Google Workspace และ Google ไดรฟ์รองรับ
• บทบาทและสิทธิ์
• ค้นหาไฟล์ที่มีป้ายกำกับหรือค่าของช่องที่เฉพาะเจาะจง