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

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

דוגמאות למחרוזות שאילתה

בטבלה הבאה מפורטות דוגמאות למחרוזות שאילתה בסיסיות. הקוד בפועל משתנה בהתאם לספריית הלקוח שבה אתם משתמשים בחיפוש.

צריך גם להשתמש בתווי בריחה (escape) בתווים המיוחדים בשמות הקבצים כדי לוודא שהשאילתה פועלת כמו שצריך. לדוגמה, אם שם קובץ מכיל גם תו גרש (') וגם קו נטוי לאחור ("\"), צריך להשתמש בקווי נטוי לאחור כדי להימלט מהם: name contains 'quinn\'s paper\\essay'.

מה רוצים לשלוח כשאוספים נתונים דוגמה
קבצים בשם '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'
קבצים ששונו אחרי תאריך נתון (אזור הזמן שמוגדר כברירת מחדל הוא 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
קבצים שהמשתמש test@example.org הוא הבעלים שלהם 'test@example.org' in owners
קבצים שלמשתמש test@example.org יש הרשאת כתיבה אליהם 'test@example.org' in writers
קבצים שלחברי הקבוצה 'group@example.org' יש הרשאת כתיבה אליהם 'group@example.org' 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, אין יותר תוצאות.

Java

drive/snippets/drive_v3/src/main/java/SearchFile.java
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
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
/**
 * 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
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.