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

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

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

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

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

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

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

برای جستجوی مجموعه‌ای خاص از فایل‌ها یا پوشه‌ها، از فیلد کوئری استرینگ q به همراه متد list استفاده کنید تا با ترکیب یک یا چند عبارت جستجو، فایل‌هایی را که می‌خواهید برگردانید، فیلتر کنید.

سینتکس رشته پرس و جو شامل سه بخش زیر است:

query_term operator values

کجا:

  • query_term عبارت یا فیلد پرس‌وجو برای جستجو است.

  • operator شرط مربوط به عبارت جستجو را مشخص می‌کند.

  • values ، مقادیر خاصی هستند که می‌خواهید برای فیلتر کردن نتایج جستجوی خود از آنها استفاده کنید.

برای مثال، رشته کوئری زیر با تنظیم نوع MIME ، جستجو را فیلتر می‌کند تا فقط پوشه‌ها را برگرداند:

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

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

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

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

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

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

آنچه می‌خواهید استعلام کنید مثال
فایل‌هایی با نام «سلام» name = 'hello'
فایل‌هایی با نام حاوی کلمات "سلام" و "خداحافظ" name contains 'hello' and name contains 'goodbye'
فایل‌هایی با نامی که شامل کلمه "hello" نیست not name contains 'hello'
فایل‌هایی که حاوی متن «مهم» هستند و در سطل زباله قرار دارند fullText contains 'important' and trashed = true
فایل‌هایی که شامل کلمه "سلام" هستند 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
فایل‌هایی که کاربر "test@example.org" مالک آنهاست 'test@example.org' in owners
فایل‌هایی که کاربر "test@example.org" مجوز نوشتن روی آنها را دارد 'test@example.org' in writers
فایل‌هایی که اعضای گروه "group@example.org" مجوز نوشتن روی آنها را دارند 'group@example.org' 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 استفاده می‌کند. همچنین برای محدود کردن بیشتر جستجو به فضای Drive ، spaces برای 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;
  }
}

پایتون

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

نود جی اس

‎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 ?? [];
}

پی اچ پی

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

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

برای جستجوی فایل‌هایی با یک ویژگی فایل سفارشی، از عبارت جستجوی 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 ' .

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

جستجو در پیکره‌ها

جستجوهایی که متد list را فراخوانی می‌کنند، به طور پیش‌فرض از corpora user استفاده می‌کنند. برای جستجوی پیکره‌های دیگر، مانند فایل‌های به اشتراک گذاشته شده با یک domain ، پارامتر corpora را تنظیم کنید.

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