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

تتيح واجهة برمجة التطبيقات 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.

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

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

ملاحظة مهمة: تستخدم عبارات طلب البحث التالية حقولاً من الإصدار 3 من Drive API. تم تغيير بعض حقول الموارد بين الإصدار 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
الملفات التي تحتوي على كلمة "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
الملفات التي يملكها المستخدم "[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 القديم، يمكنك العثور على عيّنات من الرموز البرمجية في 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

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
• الأدوار والأذونات
• البحث عن ملفات باستخدام تصنيف أو قيمة حقل محدّدَين