البحث عن الملفات والمجلدات

تتيح Google Drive API عدة طرق للبحث في الملفات والمجلدات.

يمكنك استخدام طريقة files.list لإعادة كل الملفات والمجلدات الخاصة بمستخدم Drive أو بعضها. يمكن أيضًا استخدام الطريقة files.list لاسترداد fileId المطلوب لبعض طرق الموارد (مثل files.get و files.update).

البحث عن جميع الملفات والمجلدات في "ملفاتي" للمستخدم الحالي

استخدِم الطريقة files.list بدون أي مَعلمات لعرض جميع الملفات والملفّات المُهمّلة.

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

البحث عن ملفات أو مجلدات معيّنة في "ملفاتي" للمستخدم الحالي

للبحث عن مجموعة معيّنة من الملفات أو المجلدات، استخدِم حقل سلسلة طلب البحث q مع الطريقة files.list لفلترة الملفات التي سيتم عرضها من خلال دمج عبارة بحث واحدة أو أكثر.

تحتوي سلسلة طلب البحث على الأجزاء الثلاثة التالية:

query_term operator values

المكان:

  • query_term هي عبارة طلب البحث أو الحقل الذي يتم البحث فيه.

  • تحدّد operator شرط عبارة الطلب.

  • values هي القيم المحدّدة التي تريد استخدامها لفلترة نتائج البحث.

للاطّلاع على عبارات البحث وعوامل التشغيل التي يمكنك استخدامها لفلترة الملفات والمجلدات، اطّلِع على عبارات وعوامل تشغيل طلبات البحث.

على سبيل المثال، تصفِّر سلسلة طلب البحث التالية عملية البحث لعرض ملفات مجلّدات فقط من خلال ضبط نوع MIME:

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

لمزيد من المعلومات عن أنواع MIME، يُرجى الاطّلاع على أنواع MIME المتوافقة في Google Workspace وGoogle Drive.

أمثلة على سلاسل طلبات البحث

يعرض الجدول التالي أمثلة على بعض سلاسل طلبات البحث الأساسية. يختلف الرمز الفعلي حسب مكتبة العميل التي تستخدمها في عملية البحث.

يجب أيضًا إضافة أحرف إلغاء إلى الأحرف الخاصة في أسماء الملفات للتأكّد من أنّ طلب البحث يعمل بشكل صحيح. على سبيل المثال، إذا كان اسم ملف يتضمّن كلاً من الشرطة المائلة للأمام (') والشرطة المائلة للخلف ("\")، استخدِم الشرطة المائلة للخلف للترميز: name contains 'quinn\'s paper\\essay'.

ما تريد الاستعلام عنه مثال
الملفات التي تحمل الاسم "hello" 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'
الملفات التي تم تعديلها بعد تاريخ معيّن (المنطقة الزمنية التلقائية هي التوقيت العالمي المنسّق) 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. يستخدم هذا العيّنة عبارة الطلب mimeType لحصر النتائج على الملفات من النوع image/jpeg. ويضبط الإجراء أيضًا قيمة spaces على drive لتضييق نطاق البحث أكثر على مساحة تخزين 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, items(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
/**
 * Search file in drive location
 * @return{obj} data file
 * */
async function searchFile() {
  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const service = google.drive({version: 'v3', auth});
  const files = [];
  try {
    const res = await service.files.list({
      q: 'mimeType=\'image/jpeg\'',
      fields: 'nextPageToken, files(id, name)',
      spaces: 'drive',
    });
    Array.prototype.push.apply(files, res.files);
    res.data.files.forEach(function(file) {
      console.log('Found file:', file.name, file.id);
    });
    return res.data.files;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

PHP

drive/snippets/drive_v3/src/DriveSearchFiles.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'.

لمزيد من المعلومات، يُرجى الاطّلاع على البحث عن الملفات التي تحتوي على تصنيف أو قيمة حقل معيّنة.

البحث في مجموعات النصوص

إنّ عمليات البحث التي تستدعي files.list تستخدم corpora من user تلقائيًا. للبحث في ملفّات قاعدة بيانات أخرى، مثل الملفّات التي تمت مشاركتها مع domain، اضبط المَعلمة corpora.

يمكن البحث في عدة مجموعات نصوص في طلب بحث واحد، إلا أنّه قد يتم عرض نتائج غير مكتملة إذا كانت المجموعات المجمّعة كبيرة جدًا. إذا كان incompleteSearch هو true في نص الرد، هذا يعني أنّه لم يتم عرض جميع المستندات. إذا حدث ذلك، يجب تضييق نطاق طلب البحث عن طريق اختيار مجموعات نصوص مختلفة، مثل user أو drive.