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

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

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

שימוש בפרמטר fields

אם רוצים לציין את השדות שיוחזרו בתגובה, אפשר להגדיר את fields פרמטר המערכת בכל שיטה של משאב files. אם משמיטים את הפרמטר fields, השרת מחזיר קבוצת ברירת מחדל של שדות שספציפיים לשיטה. לדוגמה, ה-method‏ list מחזירה רק את השדות kind, id, name, mimeType ו-resourceKey לכל קובץ. כדי להחזיר שדות שונים, אפשר לעיין במאמר בנושא החזרת שדות ספציפיים.

אחזור קובץ לפי מזהה

כדי לקבל קובץ, משתמשים ב-method ‏get במשאב files עם פרמטר של הנתיב fileId. אם אתם לא יודעים את מזהה הקובץ, אתם יכולים לרשום את כל הקבצים באמצעות method‏ list.

השיטה מחזירה את הקובץ כמופע של משאב files. אם מציינים את הפרמטר alt=media, התשובה כוללת את תוכן הקובץ בגוף התשובה. כדי להוריד קובץ blob, אפשר לעיין במאמר בנושא הורדת תוכן של קובץ blob.

כדי לאשר את הסיכון בהורדת תוכנות זדוניות מוכרות או קבצים פוגעניים אחרים, צריך להגדיר את פרמטר השאילתה acknowledgeAbuse לערך true. השדה הזה רלוונטי רק אם הפרמטר alt=media מוגדר והמשתמש הוא הבעלים של הקובץ או מארגן של האחסון השיתופי שבו הקובץ נמצא.

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

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

בדוגמת הפקודה הבאה של curl אפשר לראות איך מציגים רשימה של כל הקבצים:

curl -X GET \
  'https://www.googleapis.com/drive/v3/files' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: application/json'

מחליפים את ACCESS_TOKEN באסימון גישה מסוג OAuth 2.0 מורשה.

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

כדי לחפש קבוצה ספציפית של קבצים או תיקיות בתיקיית 'האחסון שלי' של המשתמש הנוכחי, משתמשים בשדה מחרוזת השאילתה q עם השיטה list כדי לסנן את הקבצים שיוחזרו על ידי שילוב של מונח חיפוש אחד או יותר.

התחביר של מחרוזת השאילתה כולל את שלושת החלקים הבאים:

query_term operator values

כאשר:

• ‫query_term הוא מונח השאילתה או השדה לחיפוש.

• ‫operator מציין את התנאי למונח השאילתה.

• ‫values הם הערכים הספציפיים שרוצים להשתמש בהם כדי לסנן את תוצאות החיפוש.

לדוגמה, מחרוזת השאילתה הבאה מסננת את החיפוש כך שיוחזרו רק תיקיות על ידי הגדרת סוג MIME:

mimeType = 'application/vnd.google-apps.folder'

כדי לראות את כל מונחי השאילתה של הקובץ, אפשר לעיין במאמר בנושא מונחי שאילתה ספציפיים לקובץ.

כדי לראות את כל האופרטורים של השאילתות שאפשר להשתמש בהם כדי ליצור שאילתה, אפשר לעיין במאמר אופרטורים של שאילתות.

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

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

חשוב: מונחי השאילתה הבאים משתמשים בשדות מ-Drive API v3. חלק משדות המשאבים השתנו בין גרסה 2 לגרסה 3. לדוגמה, name מחליף את title. אם אתם משתמשים ב-Drive API v2, אתם צריכים לשנות את השאילתות האלה כדי להשתמש בשדות של גרסה 2. מידע נוסף זמין במאמר השוואה בין גרסה 2 לגרסה 3 של Drive API.

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

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

מה לשאול	דוגמה
אופרטור להתאמת מחרוזות (contains)
קבצים שמכילים את המילה hello	fullText contains 'hello'
קבצים שמכילים את הביטוי המדויק 'hello world'	fullText contains '"hello world"'
קובצים עם שאילתה שמכילה את התו '\' (לדוגמה, '\authors')	fullText contains '\\authors'
קבצים שהשם שלהם מכיל את המילה budget	name contains 'budget'
אופרטורים של שוויון ואי-שוויון (=, !=)
קבצים עם השם hello	name = 'hello'
קבצים שהם תיקיות	mimeType = 'application/vnd.google-apps.folder'
קבצים שהם לא תיקיות	mimeType != 'application/vnd.google-apps.folder'
קבצים שמסומנים בכוכב	starred = true
קבצים שנמצאים באשפה	trashed = true
קבצים שלא נמצאים באשפה	trashed = false
קיצורי דרך שמפנים למזהה קובץ ספציפי	shortcutDetails.targetId = '1987654321'
קבצים שלא שותפו עם אף אחד או עם אף דומיין (פרטיים, או ששותפו עם משתמשים או קבוצות ספציפיים)	visibility = 'limited'
קבצים שנגישים לכל מי שיש לו את הקישור	visibility = 'anyoneWithLink'
קבצים שגלויים לכולם באינטרנט	visibility = 'anyoneCanFind'
אופרטורים להשוואה (>, ‏ >=, ‏ <, ‏ <=)
קבצים שעברו שינוי אחרי תאריך מסוים (אזור הזמן שמוגדר כברירת מחדל הוא UTC)	modifiedTime > '2012-06-04T12:00:00'
קבצים שנוצרו אחרי 1 בינואר 2023	createdTime > '2023-01-01T00:00:00'
קבצים ששונו לפני 1 בינואר 2023	modifiedTime < '2023-01-01T00:00:00'
אופרטור של חברות באוסף (in)
קבצים באוסף (לדוגמה, מזהה התיקייה באוסף 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
קבצים שלמשתמש [e-mail] יש הרשאת קריאה לגביהם	'[e-mail]' in readers
אופרטור התאמה של אוסף (has)
קבצים עם מאפיין קובץ בהתאמה אישית שגלוי לכל האפליקציות	properties has { key='mass' and value='1.3kg' }
קבצים עם מאפיין קובץ בהתאמה אישית שפרטי לאפליקציה ששולחת את הבקשה	appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
קבצים שיש להם מאפיין קובץ מותאם אישית עם המפתח 'department' (ללא קשר לערך)	properties has { key='department' }
אופרטורים לוגיים (and, ‏ or, ‏ not)
קבצים שהשם שלהם מכיל את המילים hello ו-goodbye	name contains 'hello' and name contains 'goodbye'
קבצים שהשם שלהם לא מכיל את המילה hello	not name contains 'hello'
קבצים שמכילים את הטקסט 'חשוב' ונמצאים באשפה	fullText contains 'important' and trashed = true
קבצים שלא מכילים את המילה hello	not fullText contains 'hello'
קבצים של תמונות או סרטונים ששונו אחרי תאריך מסוים	modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')
קבצים ששותפו עם המשתמש המורשה ושכוללים את המילה hello בשם שלהם	sharedWithMe and name contains 'hello'
קבצים שהם תיקיות או קיצורי דרך	mimeType = 'application/vnd.google-apps.folder' or mimeType = 'application/vnd.google-apps.shortcut'
קבצים בשם Project Plan שלא נמצאים באשפה	name = 'Project Plan' and trashed = false
קבצים בתיקייה ספציפית שלא נמצאים באשפה	'1234567' in parents and trashed = false

סינון תוצאות חיפוש באמצעות ספריית לקוח

בדוגמת הקוד הבאה מוצג איך להשתמש בספריית לקוח כדי לסנן את תוצאות החיפוש לפי שמות קבצים ומזהים של קובצי 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, files(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

import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Searches for files in Google Drive.
 * @return {Promise<object[]>} A list of files.
 */
async function searchFile() {
  // Authenticate with Google and get an authorized client.
  // TODO (developer): Use an appropriate auth mechanism for your app.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Drive API client (v3).
  const service = google.drive({version: 'v3', auth});

  // Search for files with the specified query.
  const result = await service.files.list({
    q: "mimeType='image/jpeg'",
    fields: 'nextPageToken, files(id, name)',
    spaces: 'drive',
  });

  // Print the name and ID of each found file.
  (result.data.files ?? []).forEach((file) => {
    console.log('Found file:', file.name, file.id);
  });

  return result.data.files ?? [];
}

PHP

drive/snippets/drive_v3/src/DriveSearchFiles.php

הצגת הקוד ב-GitHub

<?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;
    }
}

הצגת רשימת קבצים בתיקייה ציבורית

כדי לחפש או לרשום קבצים בתיקייה ששותפה באופן ציבורי (כשהגישה מוגדרת ל'כל מי שיש לו את הקישור' או ל'ציבורי באינטרנט'), משתמשים בשיטה list במשאב files עם פרמטר השאילתה q שמוגדר לסינון לפי מזהה התיקייה באוסף parents:

'FOLDER_ID' in parents and trashed = false

כשמציגים רשימה של קבצים בתיקייה ציבורית, אפשר לאמת בקשות באמצעות מפתח API במקום פרטי כניסה של משתמש ב-OAuth 2.0. אם התיקייה נמצאת באחסון שיתופי, צריך להגדיר גם את supportsAllDrives=true וגם את includeItemsFromAllDrives=true בבקשה.

בדוגמאות הקוד הבאות אפשר לראות איך מציגים רשימה של קבצים בתיקייה ציבורית:

Node.js

/**
 * List files in a public folder using an API key.
 * @param {string} folderId The ID of the public folder.
 * @param {string} apiKey Your Google Cloud API key.
 * @return {Promise<Array>} The list of files.
 */
async function listPublicFolder(folderId, apiKey) {
  const {google} = require('googleapis');
  const service = google.drive({version: 'v3', auth: apiKey});

  try {
    const response = await service.files.list({
      q: `'${folderId}' in parents and trashed = false`,
      fields: 'nextPageToken, files(id, name, mimeType)',
      supportsAllDrives: true,
      includeItemsFromAllDrives: true,
    });
    const files = response.data.files;
    console.log('Files:');
    for (const file of files) {
      console.log(`${file.name} (${file.id})`);
    }
    return files;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
  }
}

curl

curl -G \
  'https://www.googleapis.com/drive/v3/files' \
  --data-urlencode "q='FOLDER_ID' in parents and trashed = false" \
  --data-urlencode 'supportsAllDrives=true' \
  --data-urlencode 'includeItemsFromAllDrives=true' \
  --data-urlencode 'fields=nextPageToken,files(id,name,mimeType)' \
  --data-urlencode 'key=API_KEY' \
  -H 'Accept: application/json'

מחליפים את מה שכתוב בשדות הבאים:

• ‫FOLDER_ID: המזהה של התיקייה הציבורית.
• ‫API_KEY: מפתח ה-API של הפרויקט.

חיפוש קבצים באמצעות מאפיינים מותאמים אישית

כדי לחפש קבצים עם מאפיין קובץ מותאם אישית, משתמשים במונח השאילתה 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.FIELD_ID = 'VALUE'

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

חיפוש בכל מקורות המידע

כברירת מחדל, אוסף הפריטים user מוגדר בפרמטר השאילתה corpora כשמשתמשים ב-method ‏list. כדי לחפש באוספים אחרים של פריטים, כמו אלה ששותפו עם domain, צריך להגדיר במפורש את הפרמטר corpora.

אפשר לחפש בכמה מאגרי מידע בשאילתה אחת, אבל אם השילוב של מאגרי המידע גדול מדי, יכול להיות שה-API יחזיר תוצאות חלקיות. בודקים את השדה incompleteSearch בגוף התשובה. אם התוצאה היא true, סימן שחלק מהמסמכים לא נכללו. כדי לפתור את הבעיה, צריך לצמצם את corpora כך שישתמש ב-user או ב-drive.

כשמשתמשים בפרמטר השאילתה orderBy בשיטה list, מומלץ להימנע משימוש במפתח createdTime לשאילתות באוספים גדולים של פריטים, כי הוא דורש עיבוד נוסף ועלול לגרום לפסק זמן או לבעיות אחרות. כדי למיין לפי זמן אוסף גדול של פריטים, אפשר להשתמש ב-modifiedTime במקום זאת, כי הוא מותאם לטיפול בשאילתות האלה. לדוגמה, מגדירים את orderBy לערך modifiedTime (או modifiedTime desc).

אם משמיטים את פרמטר השאילתה orderBy, לא מוגדר סדר מיון כברירת מחדל והפריטים מוחזרים באופן שרירותי.

נושאים קשורים

• חיפוש תיקיות אחסון שיתופי
• מונחים ואופרטורים של שאילתות חיפוש
• סוגי MIME שנתמכים ב-Google Workspace וב-Google Drive
• תפקידים והרשאות
• חיפוש קבצים עם תווית או ערך שדה ספציפיים