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

คำแนะนำนี้จะอธิบายวิธีที่ 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'

สิ่งที่ต้องการค้นหา ตัวอย่าง
โอเปอเรเตอร์การจับคู่สตริง (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
ทางลัดที่ชี้ไปยังรหัสไฟล์ที่เฉพาะเจาะจง 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'
ไฟล์ที่มีข้อความ "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
ไฟล์ในโฟลเดอร์ที่เฉพาะเจาะจงซึ่งไม่อยู่ในถังขยะ '1234567' in parents and trashed = false

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

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

Java

drive/snippets/drive_v3/src/main/java/SearchFile.java
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
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
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
<?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 ในคำขอด้วย

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

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 ของโปรเจ็กต์

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

หากต้องการค้นหาไฟล์ที่มีพร็อพเพอร์ตี้ไฟล์ที่กำหนดเอง ให้ใช้ข้อความค้นหา 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 จะไม่มีลำดับการจัดเรียงเริ่มต้นและระบบจะแสดงรายการแบบสุ่ม