חיפוש קבצים ותיקיות

ה-API של Google Drive תומך בכמה דרכים לחיפוש קבצים ותיקיות.

אפשר להשתמש בשיטה files.list כדי להחזיר את כל הקבצים והתיקיות של משתמש ב-Drive או חלק מהם. אפשר להשתמש ב-method 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. חלק משדות המשאבים השתנו בין v2 ל-v3. לדוגמה, files.name מחליף את files.title. אם משתמשים ב- Drive API v2, צריך לשנות את השאילתות האלה כך שישתמשו בשדות של גרסה 2. למידע נוסף, קראו את חומר העזר על השוואה בין Drive API v2 ו-v3.

הערה: בדוגמאות האלה נעשה שימוש בפרמטר q הלא מקודד, שבו name = 'hello' מקודד כ-name+%3d+%27hello%27. ספריות לקוח מטפלות בקידוד הזה באופן אוטומטי.

על מה רוצים להריץ שאילתה	דוגמה
קבצים בשם 'hello'	name = 'hello'
קבצים שהשם שלהם מכיל את המילים 'hello' ו-'goodbye'	name contains 'hello' and name contains 'goodbye'
קבצים בשם שלא מכיל את המילה 'hello'	not name contains 'hello'
קבצים שמכילים את הטקסט 'חשוב' שנמצאים באשפה	fullText contains 'important' and trashed = true
קבצים שמכילים את המילה 'hello'	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'
קבצים שנערכו אחרי תאריך מסוים (אזור הזמן שמוגדר כברירת מחדל הוא UTC)	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
קבצים ששותפו עם משתמש מורשה בשם '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 API v2, תוכלו למצוא דוגמאות קוד ב-GitHub. איך עוברים ל-Drive API v3

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
• תפקידים והרשאות
• חיפוש קבצים עם תווית או ערך בשדה מסוים