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

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

אפשר להשתמש בשיטה files.list כדי להחזיר כל הקבצים והתיקיות של המשתמש ב-Drive או חלק מהם. files.list אפשר להשתמש ב-method גם כדי לאחזר את ה-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 נתמכים.

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

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

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

מה ברצונך לשלוח שאילתה? דוגמה
קבצים בשם "hello" name = 'hello'
קבצים עם שם שמכיל את המילים "hello" ו'להתראות' name contains 'hello' and name contains 'goodbye'
קבצים שהשם שלהם לא מכיל את המילה "hello" not name contains 'hello'
קבצים שמכילים את הטקסט "important" באשפה 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
קבצים של המשתמש 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.