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

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

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

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

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

غيِّر القيم في السلسلة على الشكل التالي:

البحث عن الملفات التي تتضمّن خصائص مخصّصة

للبحث عن ملفات تتضمّن خاصية ملف مخصّصة، استخدِم عبارة البحث 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، لن يكون هناك ترتيب فرز تلقائي وسيتم عرض العناصر بشكل عشوائي.