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

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

אפשר להשתמש בשיטה files.list כדי להחזיר את כל הקבצים והתיקיות של המשתמש ב-Drive, או חלק מהם. אפשר גם להשתמש ב-method files.list כדי לאחזר את ה-fileId שנדרש ב-methods מסוימות של משאבים (כמו files.get ו-files.update).

חיפוש כל הקבצים והתיקיות בתיקיית 'האחסון שלי' של המשתמש הנוכחי

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

אתם צריכים גם לסמן את התווים המיוחדים בשמות הקבצים בתו בריחה (escape) כדי לוודא שהשאילתה עובדת כמו שצריך. לדוגמה, אם שם קובץ מכיל גם גרש (') וגם תו לוכסן הפוך ("\"), צריך להשתמש בקו נטוי הפוך כדי לסמן אותם בתו בריחה (escape): 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'
קבצים שמכילים את הביטוי המדויק "שלום עולם"	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
• תפקידים והרשאות
• חיפוש קבצים עם ערך ספציפי של תווית או שדה