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

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

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

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

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

یک فایل دریافت کنید

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

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

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

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

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

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

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

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

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

query_term operator values

کجا:

  • query_term عبارت یا فیلدی است که باید در آن جستجو کرد.

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

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

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

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

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

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

نمونه های رشته پرس و جو

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

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

چیزی که می خواهید پرس و جو کنید مثال
فایل هایی با نام "سلام" name = 'hello'
فایل هایی با نام حاوی کلمات "سلام" و "خداحافظ" name contains 'hello' and name contains 'goodbye'
فایل هایی با نامی که حاوی کلمه سلام نیست not name contains 'hello'
فایل هایی که حاوی متن "مهم" و در سطل زباله هستند fullText contains 'important' and trashed = true
فایل هایی که حاوی کلمه سلام هستند fullText contains 'hello'
فایل هایی که کلمه سلام را ندارند not fullText contains 'hello'
فایل هایی که حاوی عبارت دقیق "سلام جهان" هستند. 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
فایل‌هایی که با کاربر مجاز به اشتراک گذاشته می‌شوند، در نام «سلام». sharedWithMe and name contains 'hello'
فایل‌هایی با ویژگی فایل سفارشی قابل مشاهده برای همه برنامه‌ها properties has { key='mass' and value='1.3kg' }
فایل‌های دارای ویژگی فایل سفارشی خصوصی در برنامه درخواست‌کننده appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
فایل‌هایی که با هیچ‌کس یا دامنه‌ای به اشتراک گذاشته نشده‌اند (فقط خصوصی، یا به اشتراک گذاشته شده با کاربران یا گروه‌های خاص) visibility = 'limited'

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

نمونه کد زیر نحوه استفاده از کتابخانه سرویس گیرنده برای فیلتر کردن نتایج جستجو به نام فایل ها و شناسه فایل های JPEG را نشان می دهد. این نمونه از عبارت query 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;
  }
}

پایتون

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

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

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