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

يوضّح هذا الدليل كيف تتيح Google Drive API عدة طرق للبحث عن الملفات والمجلدات.

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

استخدام مَعلمة fields

إذا أردت تحديد الحقول التي سيتم عرضها في الردّ، يمكنك ضبط الـ fields مَعلمة النظام باستخدام أي طريقة من طرق مورد الـfiles. إذا لم تحدّد مَعلمة fields، يعرض الخادم مجموعة تلقائية من الحقول الخاصة بالطريقة. على سبيل المثال، لا تعرض طريقة list سوى الحقول kind وid و name وmimeType وresourceKey لكل ملف. لعرض حقول مختلفة ، يُرجى الاطّلاع على مقالة عرض حقول معيّنة.

الحصول على ملف حسب رقم تعريفه

للحصول على ملف، استخدِم طريقة get في مورد files مع مَعلمة المسار fileId. إذا لم يكن لديك رقم تعريف الملف، يمكنك عرض جميع الملفات باستخدام طريقة list.

تعرض الطريقة الملف كمثال لمورد files. إذا قدّمت المَعلمة alt=media، سيتضمّن الردّ محتوى الملف في نص الردّ. لتنزيل ملف ثنائي كبير، يُرجى الاطّلاع على مقالة تنزيل محتوى ملف ثنائي كبير.

لإقرار خطر تنزيل برامج ضارة معروفة أو ملفات أخرى مسيئة، اضبط مَعلمة طلب البحث acknowledgeAbuse على true. لا ينطبق هذا الحقل إلا عند ضبط المَعلمة alt=media وكان المستخدم إما مالك الملف أو منظِّم مساحة التخزين السحابي المشتركة التي يتوفّر فيها الملف.

عرض جميع الملفات والمجلدات في "ملفاتي"

استخدِم طريقة list بدون أي مَعلمات لعرض جميع الملفات والمجلدات في "ملفاتي" لدى المستخدم الحالي.

يوضّح أمر 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 مُرخَّص .

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

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

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

query_term operator values

المكان:

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

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

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

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

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

للاطّلاع على جميع عبارات طلب البحث عن الملفات، يُرجى الاطّلاع على عبارات طلب البحث الخاصة بالملفات.

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

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

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

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

ما الذي يجب طلبه مثال
عامل تشغيل مطابقة السلسلة (contains)
الملفات التي تحتوي على الكلمة "hello" fullText contains 'hello'
الملفات التي تحتوي على العبارة "hello world" بالضبط fullText contains '"hello world"'
الملفات التي تحتوي على طلب بحث يتضمّن الحرف "\" (على سبيل المثال، "\authors") fullText contains '\\authors'
الملفات التي يحتوي اسمها على "budget" name contains 'budget'
عوامل تشغيل المساواة وعدم المساواة (=، !=)
الملفات التي تحمل الاسم "hello" 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'
عوامل تشغيل المقارنة (>، >=، <، <=)
الملفات التي تم تعديلها بعد تاريخ معيّن (المنطقة الزمنية التلقائية هي التوقيت العالمي المنسَّق) modifiedTime > '2012-06-04T12:00:00'
الملفات التي تم إنشاؤها بعد 1 يناير 2023 createdTime > '2023-01-01T00:00:00'
الملفات التي تم تعديلها قبل 1 يناير 2023 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)
الملفات التي يحتوي اسمها على الكلمتَين "hello" و"goodbye" name contains 'hello' and name contains 'goodbye'
الملفات التي لا يحتوي اسمها على الكلمة "hello" not name contains 'hello'
الملفات التي تحتوي على النص "important" والموجودة في "المهملات" fullText contains 'important' and trashed = true
الملفات التي لا تحتوي على الكلمة "hello" not fullText contains 'hello'
ملفات الصور أو الفيديو التي تم تعديلها بعد تاريخ معيّن modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')
الملفات التي تمت مشاركتها مع المستخدم المفوَّض والتي يحتوي اسمها على "hello" sharedWithMe and name contains 'hello'
الملفات التي هي مجلدات أو اختصارات mimeType = 'application/vnd.google-apps.folder' or mimeType = 'application/vnd.google-apps.shortcut'
الملفات التي تحمل الاسم "Project Plan" وليست في "المهملات" 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

عند عرض الملفات في مجلد علني، يمكنك مصادقة الطلبات باستخدام مفتاح واجهة برمجة التطبيقات بدلاً من بيانات اعتماد مستخدم 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

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 عامل تشغيل أو مَعلمة لطلب البحث للبحث بشكلٍ متكرّر عن أشجار المجلدات الفرعية الفرعية في طلب بيانات من واجهة برمجة التطبيقات واحد.

للبحث عن مجلد وجميع المجلدات والملفات الفرعية الفرعية، يجب أن ينفّذ تطبيقك عملية اجتياز شجرة من جهة العميل:

  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 بشكلٍ صريح.

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

عند استخدام مَعلمة طلب البحث orderBy في طريقة list، تجنَّب استخدام المفتاح createdTime لطلبات البحث في مجموعات العناصر الكبيرة لأنّ ذلك يتطلّب معالجة إضافية وقد يؤدي إلى انتهاء المهلة أو حدوث مشاكل أخرى. لإجراء عملية ترتيب حسب الوقت في مجموعات العناصر الكبيرة، يمكنك استخدام modifiedTime بدلاً من ذلك لأنّه تم تحسينه للتعامل مع طلبات البحث هذه. على سبيل المثال، اضبط orderBy على modifiedTime (أو modifiedTime desc).

إذا لم تحدّد مَعلمة طلب البحث orderBy، لن يكون هناك ترتيب فرز تلقائي وسيتم عرض العناصر بشكلٍ عشوائي.