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

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

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

ค้นหาไฟล์หรือโฟลเดอร์ที่เฉพาะเจาะจงในไดรฟ์ของฉันของผู้ใช้ปัจจุบัน

หากต้องการค้นหาไฟล์หรือโฟลเดอร์ชุดที่เฉพาะเจาะจง ให้ใช้ช่องสตริงการค้นหา q field กับวิธี list เพื่อกรองไฟล์ที่จะ แสดงผลโดยรวมข้อความค้นหาอย่างน้อย 1 รายการ

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

query_term operator values

โดยที่

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

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

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

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

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

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

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

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

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

สำคัญ: ข้อความค้นหาต่อไปนี้ใช้ช่องจาก Drive API v3 ช่องทรัพยากรบางช่องมีการเปลี่ยนแปลงระหว่าง v2 กับ v3 เช่น name จะแทนที่ title หากคุณใช้ Drive API v2 ให้ปรับการค้นหาเหล่านี้เพื่อใช้ช่อง v2 ดูข้อมูลเพิ่มเติมได้ที่ข้อมูลอ้างอิงเปรียบเทียบ Drive API v2 และ v3

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

หมายเหตุ: ตัวอย่างเหล่านี้ใช้พารามิเตอร์ q ที่ไม่ได้เข้ารหัส โดยที่ name = 'hello' จะ เข้ารหัสเป็น name+%3d+%27hello%27 ไลบรารีของไคลเอ็นต์จะจัดการการเข้ารหัสนี้โดยอัตโนมัติ

สิ่งที่คุณต้องการค้นหา	ตัวอย่าง
ไฟล์ที่มีชื่อว่า "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)	'1234567' in parents
ไฟล์ในโฟลเดอร์ข้อมูลแอปพลิเคชันในคอลเล็กชัน	'appDataFolder' in parents
ไฟล์ที่ผู้ใช้ "[e-mail]" เป็นเจ้าของ	'[e-mail]' in owners
ไฟล์ที่ผู้ใช้ "[e-mail]" มีสิทธิ์เขียน	'[e-mail]' in writers
ไฟล์ที่สมาชิกของกลุ่ม "[e-mail]" มีสิทธิ์เขียน	'[e-mail]' 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 ตัวอย่างนี้ใช้ข้อความค้นหา mimeType เพื่อจำกัดผลการค้นหาให้แสดงเฉพาะไฟล์ประเภท image/jpeg นอกจากนี้ยังตั้งค่า spaces เป็น 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;
    }
}

ค้นหาไฟล์ที่มีพร็อพเพอร์ตี้ไฟล์ที่กำหนดเอง

หากต้องการค้นหาไฟล์ที่มีพร็อพเพอร์ตี้ไฟล์ที่กำหนดเอง ให้ใช้ข้อความค้นหา 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.text_field_id ='TEXT'

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

ค้นหาคลังวรรณกรรม

โดยค่าเริ่มต้น ระบบจะตั้งค่าคอลเล็กชันรายการ user ในพารามิเตอร์การค้นหา corpora เมื่อใช้วิธี list หากต้องการค้นหาคอลเล็กชันรายการอื่นๆ เช่น คอลเล็กชันที่แชร์กับ domain คุณต้องตั้งค่าพารามิเตอร์ corpora อย่างชัดเจน

คุณสามารถค้นหาคลังวรรณกรรมหลายรายการในการค้นหาครั้งเดียวได้ แต่หากคลังวรรณกรรมที่รวมกันมีขนาดใหญ่เกินไป API อาจแสดงผลการค้นหาที่ไม่สมบูรณ์ ตรวจสอบช่อง incompleteSearch ในเนื้อหาการตอบกลับ หากช่องนี้มีค่าเป็น true แสดงว่าระบบได้ละเว้นเอกสารบางรายการ หากต้องการแก้ไขปัญหานี้ ให้จำกัด corpora ให้ใช้ user หรือ drive

เมื่อใช้พารามิเตอร์การค้นหา orderBy ในวิธี list ให้หลีกเลี่ยงการใช้คีย์ createdTime สำหรับการค้นหาในคอลเล็กชันรายการขนาดใหญ่ เนื่องจากต้องมีการประมวลผลเพิ่มเติมและอาจทำให้เกิดการหมดเวลาหรือปัญหาอื่นๆ หากต้องการจัดเรียงคอลเล็กชันรายการขนาดใหญ่ตามเวลา คุณสามารถใช้ modifiedTime แทนได้ เนื่องจากระบบได้ปรับให้เหมาะสมเพื่อจัดการการค้นหาเหล่านี้ เช่น ?orderBy=modifiedTime

หากไม่ระบุพารามิเตอร์การค้นหา orderBy จะไม่มีลำดับการจัดเรียงเริ่มต้นและระบบจะแสดงผลรายการตามลำดับใดก็ได้

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

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