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

تتيح 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.

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

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

ملاحظة مهمة: تستخدم عبارات البحث التالية حقولاً من Drive API الإصدار 3. تم تغيير بعض حقول الموارد بين الإصدار 2 والإصدار 3. على سبيل المثال، يحلّ الرمز files.name محلّ الرمز files.title. إذا كنت تستخدم الإصدار 2 من Drive API، عدِّل طلبات البحث هذه لاستخدام حقول الإصدار 2. لمزيد من المعلومات، يُرجى الاطّلاع على مرجع مقارنة بين الإصدارَين 2 و3 من Drive API.

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

ملاحظة: تستخدم هذه الأمثلة المَعلمة q غير المشفرة، حيث يتم تشفير name = 'hello' على النحو name+%3d+%27hello%27. تتولّى مكتبات البرامج الترميز تلقائيًا.

ما تريد البحث عنه	مثال
الملفات التي تحمل الاسم "hello"	name = 'hello'
الملفات التي يتضمّن اسمها الكلمتين "مرحبًا" و "وداعًا"	name contains 'hello' and name contains 'goodbye'
الملفات التي لا يتضمّن اسمها الكلمة "hello"	not name contains 'hello'
الملفات التي تحتوي على النص "مهم" والموجودة في المهملات	fullText contains 'important' and trashed = true
الملفات التي تتضمّن الكلمة "مرحبًا"	fullText contains '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
الملفات التي يكون المستخدم "[e-mail]" هو مالكها	'[e-mail]' in owners
الملفات التي يملك المستخدم "[e-mail]" إذن الكتابة فيها	'[e-mail]' in writers
الملفات التي يملك أعضاء المجموعة "[e-mail]" إذن الكتابة فيها	'[e-mail]' 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، يعني ذلك أنّه لم تعُد هناك نتائج أخرى.

ملاحظة: إذا كنت تستخدم الإصدار القديم من Drive API v2، يمكنك العثور على نماذج الرموز في GitHub. تعرَّف على كيفية نقل البيانات إلى الإصدار 3 من Drive API.

Java

drive/snippets/drive_v3/src/main/java/SearchFile.java

عرض على GitHub

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

عرض على GitHub

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

عرض على GitHub

/**
 * 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

عرض على GitHub

<?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.

مواضيع ذات صلة

• البحث عن مساحات تخزين سحابي مشتركة
• عبارات البحث وعوامل التشغيل
• أنواع MIME المتوافقة في Google Workspace وGoogle Drive
• الأدوار والأذونات
• البحث عن الملفات التي تتضمّن تصنيفًا أو قيمة حقل معيّنَين