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

يوضّح هذا الدليل كيف تتيح 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'

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

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

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

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

عليك أيضًا إزالة الأحرف الخاصة في أسماء ملفاتك للتأكّد من أنّ طلب البحث يعمل بشكلٍ صحيح. على سبيل المثال، إذا كان اسم الملف يحتوي على كل من الفاصلة العليا (') والشرطة المائلة للخلف ("\")، استخدِم شرطة مائلة للخلف لإزالتهما: 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. عندما تعرض 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، لن يكون هناك ترتيب فرز تلقائي وسيتم عرض العناصر بشكلٍ عشوائي.