جستجوی فایل‌ها و پوشه‌ها

این راهنما توضیح می‌دهد که Google Drive API چگونه از چندین روش برای جستجوی فایل‌ها و پوشه‌ها پشتیبانی می‌کند.

می‌توانید از روش list در منبع files برای برگرداندن همه یا برخی از فایل‌ها و پوشه‌های کاربر Drive استفاده کنید. همچنین می‌توانید از روش list برای بازیابی fileId موردنیاز برای برخی روش‌های منبع (مانند روش‌های get و update) استفاده کنید.

استفاده از پارامتر فیلدها

اگر می‌خواهید فیلدهایی را که باید در پاسخ برگردانده شوند مشخص کنید، می‌توانید fields پارامتر سیستم را با هر روشی از منبع files تنظیم کنید. اگر پارامتر fields را حذف کنید، سرور مجموعه‌ای از فیلدهای پیش‌فرض را که مختص آن روش است برمی‌گرداند. برای مثال، روش list فقط فیلدهای kind، id، name، mimeType، و resourceKey را برای هر فایل برمی‌گرداند. برای برگرداندن فیلدهای مختلف، برگرداندن فیلدهای خاص را ببینید.

دریافت فایل با شناسه

برای دریافت فایل، از روش get در منبع files با پارامتر مسیر fileId استفاده کنید. اگر شناسه فایل را نمی‌دانید، می‌توانید بااستفاده از روش list همه فایل‌ها را فهرست کنید.

این روش فایل را به‌عنوان نمونه‌ای از منبع files برمی‌گرداند. اگر پارامتر alt=media را ارائه دهید، پاسخ شامل محتوای فایل در بدنه پاسخ می‌شود. برای بارگیری فایل blob، به بارگیری محتوای فایل blob مراجعه کنید.

برای پذیرفتن خطر بارگیری بدافزارهای شناخته‌شده یا فایل‌های سوءاستفاده‌گرانه دیگر، پارامتر پُرسمان acknowledgeAbuse را روی true تنظیم کنید. این فیلد فقط زمانی قابل‌اعمال است که پارامتر alt=media تنظیم شده باشد و کاربر مالک فایل یا سازمان‌دهنده درایو مشترکی باشد که فایل در آن قرار دارد.

فهرست کردن همه فایل‌ها و پوشه‌ها در My Drive

از روش list بدون هیچ پارامتری برای برگرداندن همه فایل‌ها و پوشه‌ها در My Drive کاربر فعلی استفاده کنید.

فرمان 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 مجاز جایگزین کنید.

جستجوی فایل‌ها و پوشه‌های خاص در My Drive

برای جستجوی مجموعه خاصی از فایل‌ها یا پوشه‌ها در My Drive کاربر فعلی، از فیلد رشته پُرسمان 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'
فایل‌هایی که حاوی عبارت دقیق «سلام دنیا» هستند fullText contains '"hello world"'
فایل‌هایی با پُرسمانی که حاوی نویسه «\» است (برای مثال، «\authors») fullText contains '\\authors'
فایل‌هایی که نامشان حاوی «بودجه» است name contains 'budget'
عملگرهای برابری و نابرابری (=، !=)
فایل‌هایی با نام «سلام» 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'
فایل‌های ایجادشده پس‌از ۱ ژانویه ۲۰۲۳ createdTime > '2023-01-01T00:00:00'
فایل‌هایی که قبل‌از ۱ ژانویه ۲۰۲۳ اصلاح شده‌اند 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)
فایل‌هایی که نامشان حاوی کلمات «سلام» و «خداحافظ» است name contains 'hello' and name contains 'goodbye'
فایل‌هایی که نامشان حاوی کلمه «سلام» نیست 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/')
فایل‌های هم‌رسانی‌شده با کاربر مجاز که کلمه «سلام» در نام آن‌ها وجود دارد 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 محدود کند. همچنین spaces را روی drive تنظیم می‌کند تا جستجو را بیشتر به فضای Drive محدود کند. وقتی nextPageToken مقدار null را برمی‌گرداند، دیگر نتیجه‌ای وجود ندارد.

جاوا

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 تنظیم‌شده برای فیلتر کردن براساس شناسه پوشه در مجموعه 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 -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. شناسه هر پوشه فرزند را به‌صورت بازگشتی یا تکراری پُرسمان کنید تا محتوای آن را بازیابی کنید.

نمونه‌های کد زیر نحوه جستجوی بازگشتی پوشه و فرزندان آن را نشان می‌دهد:

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 را حذف کنید، ترتیب مرتب‌سازی پیش‌فرضی وجود ندارد و موارد به‌صورت دلخواه برگردانده می‌شوند.