فایل ها و پوشه ها را جستجو کنید

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

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

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

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

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

برای دریافت یک فایل، از متد get روی منبع files به همراه پارامتر مسیر fileId استفاده کنید. اگر ID فایل را نمی‌دانید، می‌توانید با استفاده از متد 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'

برای مشاهده همه اصطلاحات جستجوی فایل، به اصطلاحات جستجوی خاص فایل مراجعه کنید.

برای مشاهده‌ی تمام عملگرهای پرس‌وجویی که می‌توانید برای ساخت یک پرس‌وجو استفاده کنید، به عملگرهای پرس‌وجو مراجعه کنید.

مثال‌های رشته پرس‌وجو

جدول زیر نمونه‌هایی از برخی رشته‌های پرس‌وجوی پایه را فهرست می‌کند. کد واقعی بسته به کتابخانه کلاینتی که برای جستجوی خود استفاده می‌کنید، متفاوت است.

همچنین باید از کاراکترهای ویژه در نام فایل‌های خود escape کنید تا مطمئن شوید که کوئری به درستی کار می‌کند. برای مثال، اگر نام فایلی شامل هر دو کاراکتر آپاستروف ( ' ) و بک‌اسلش ( "\" ) است، از بک‌اسلش برای escape کردن آنها استفاده کنید: name contains 'quinn\'s paper\\essay' .

فیلتر کردن نتایج جستجو با کتابخانه کلاینت

نمونه کد زیر نحوه استفاده از یک کتابخانه کلاینت را برای فیلتر کردن نتایج جستجو به نام فایل‌ها و شناسه‌های فایل‌های JPEG نشان می‌دهد. این نمونه از عبارت پرس‌وجوی mimeType برای محدود کردن نتایج به فایل‌هایی از نوع image/jpeg استفاده می‌کند. همچنین برای محدود کردن بیشتر جستجو به فضای Drive ، 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 که برای فیلتر کردن بر اساس شناسه‌ی پوشه در مجموعه‌ی 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'

جستجوی فایل‌هایی با ویژگی‌های سفارشی

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

شما می‌توانید چندین مجموعه داده را در یک پرس‌وجو جستجو کنید؛ با این حال، اگر مجموعه داده‌های ترکیبی خیلی بزرگ باشد، API ممکن است نتایج ناقصی را برگرداند. فیلد incompleteSearch را در بدنه پاسخ بررسی کنید. اگر مقدار آن true باشد، یعنی برخی از اسناد حذف شده‌اند. برای حل این مشکل، corpora به استفاده از user یا drive محدود کنید.

هنگام استفاده از پارامتر پرس‌وجوی orderBy در متد list ، از استفاده از کلید createdTime برای پرس‌وجوهای مربوط به مجموعه‌های بزرگ اقلام خودداری کنید، زیرا به پردازش اضافی نیاز دارد و ممکن است منجر به وقفه‌های زمانی یا سایر مشکلات شود. برای مرتب‌سازی مرتبط با زمان در مجموعه‌های بزرگ اقلام، می‌توانید به جای آن از modifiedTime استفاده کنید زیرا برای مدیریت این پرس‌وجوها بهینه شده است. به عنوان مثال، orderBy روی modifiedTime (یا modifiedTime desc ) تنظیم کنید.

اگر پارامتر query orderBy را حذف کنید، ترتیب مرتب‌سازی پیش‌فرض وجود ندارد و موارد به صورت دلخواه برگردانده می‌شوند.

مباحث مرتبط

• جستجوی درایوهای اشتراکی
• عبارات و عملگرهای جستجوی پرس و جو
• انواع MIME پشتیبانی‌شده توسط Google Workspace و Google Drive
• نقش‌ها و مجوزها
• جستجوی فایل‌هایی با برچسب یا مقدار فیلد خاص