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

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

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

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

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

الحصول على ملف

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

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

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

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

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

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

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

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

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

query_term operator values

المكان:

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

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

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

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

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

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

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

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

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

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

ما تريد طلبه مثال
الملفات التي تحمل الاسم "hello" name = 'hello'
الملفات التي يتضمّن اسمها الكلمتَين "hello" و"goodbye" name contains 'hello' and name contains 'goodbye'
الملفات التي لا يتضمّن اسمها الكلمة "hello" not name contains 'hello'
الملفات التي تحتوي على النص "important" والموجودة في المهملات fullText contains 'important' and trashed = true
الملفات التي تحتوي على الكلمة "hello" 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'
الملفات التي تم تعديلها بعد تاريخ معيّن (المنطقة الزمنية التلقائية هي التوقيت العالمي المنسَّق) 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. يضبط النموذج أيضًا spaces على drive لتضييق نطاق البحث أكثر ليقتصر على مساحة Drive space. عندما تعرض 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;
    }
}

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

للبحث عن الملفات التي تتضمّن سمة ملف مخصّصة، استخدِم إما عبارة البحث 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'.

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

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

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

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

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

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