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

تتيح واجهة برمجة التطبيقات 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، يُرجى الاطّلاع على Google Workspace وGoogle Drive. أنواع MIME المتوافقة.

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

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

ملاحظة مهمة: تستخدم عبارات طلب البحث التالية حقولاً من 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
الملفات التي تحتوي على كلمة "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، لم يتم العثور على أي نتائج أخرى.

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