Wyszukiwanie plików i folderów

Z tego przewodnika dowiesz się, jak Google Drive API obsługuje kilka sposobów wyszukiwania plików i folderów.

Możesz użyć metody list w zasobie files, aby zwrócić wszystkie lub niektóre pliki i foldery użytkownika Dysku. Metoda list może też służyć do pobierania parametru fileId wymaganego w przypadku niektórych metod zasobów (np. metody get i metody update).

Używanie parametru fields

Jeśli chcesz określić pola, które mają być zwracane w odpowiedzi, możesz ustawić fields parametr systemfields w dowolnej metodzie zasobu files. Jeśli pominiesz parametr fields, serwer zwróci domyślny zestaw pól specyficznych dla danej metody. Na przykład metoda list zwraca tylko pola kind, id, name, mimeTyperesourceKey dla każdego pliku. Aby zwrócić inne pola, zobacz Zwracanie określonych pól.

Pobieranie pliku

Aby pobrać plik, użyj metody get w zasobie files z parametrem ścieżki fileId. Jeśli nie znasz identyfikatora pliku, możesz wyświetlić listę wszystkich plików za pomocą metody list.

Metoda zwraca plik jako instancję zasobu files. Jeśli podasz parametr zapytania alt=media, odpowiedź będzie zawierać treść pliku w treści odpowiedzi. Aby pobrać lub wyeksportować plik, przeczytaj artykuł Pobieranie i eksportowanie plików.

Aby potwierdzić ryzyko pobrania znanego złośliwego oprogramowania lub innych szkodliwych plików, ustaw parametr zapytania acknowledgeAbuse na true. To pole ma zastosowanie tylko wtedy, gdy ustawiony jest parametr alt=media, a użytkownik jest właścicielem pliku lub organizatorem dysku współdzielonego, na którym znajduje się plik.

Wyszukiwanie wszystkich plików i folderów na Moim dysku bieżącego użytkownika

Aby zwrócić wszystkie pliki i foldery, użyj metody list bez parametrów.

GET https://www.googleapis.com/drive/v3/files

wyszukiwanie konkretnych plików lub folderów na Moim dysku bieżącego użytkownika,

Aby wyszukać określony zestaw plików lub folderów, użyj ciągu zapytania q field z metodą list, aby odfiltrować pliki do zwrócenia przez połączenie co najmniej jednego terminu wyszukiwania.

Składnia ciągu zapytania składa się z tych 3 części:

query_term operator values

Gdzie:

  • query_term to wyszukiwane hasło lub pole, w którym ma być przeprowadzone wyszukiwanie.

  • operator określa warunek dla terminu zapytania.

  • values to konkretne wartości, których chcesz użyć do filtrowania wyników wyszukiwania.

Na przykład ten ciąg zapytania filtruje wyszukiwanie, aby zwracać tylko foldery, ustawiając typ MIME:

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

Aby wyświetlić wszystkie terminy zapytań dotyczące plików, zobacz Terminy zapytań dotyczące plików.

Aby wyświetlić wszystkie operatory zapytań, których możesz użyć do utworzenia zapytania, zobacz Operatory zapytań.

Przykłady ciągów zapytania

W tabeli poniżej znajdziesz przykłady podstawowych ciągów zapytania. Rzeczywisty kod zależy od biblioteki klienta używanej do wyszukiwania.

Musisz też użyć znaków zmiany znaczenia w nazwach plików, aby mieć pewność, że zapytanie działa prawidłowo. Jeśli na przykład nazwa pliku zawiera zarówno apostrof ('), jak i ukośnik lewy ("\"), poprzedź je ukośnikiem lewym: name contains 'quinn\'s paper\\essay'.

Co chcesz wyszukać Przykład
Pliki o nazwie „hello” name = 'hello'
Pliki, których nazwa zawiera słowa „hello” i „goodbye” name contains 'hello' and name contains 'goodbye'
Pliki, których nazwa nie zawiera słowa „hello” not name contains 'hello'
Pliki zawierające tekst „ważne” i znajdujące się w koszu fullText contains 'important' and trashed = true
Pliki zawierające słowo „hello” fullText contains 'hello'
Pliki, które nie zawierają słowa „hello” not fullText contains 'hello'
Pliki zawierające dokładnie wyrażenie „hello world” fullText contains '"hello world"'
Pliki z zapytaniem zawierającym znak „\” (np. „\authors”) fullText contains '\\authors'
Pliki, które są folderami mimeType = 'application/vnd.google-apps.folder'
Pliki, które nie są folderami mimeType != 'application/vnd.google-apps.folder'
Pliki zmodyfikowane po określonej dacie (domyślna strefa czasowa to UTC) modifiedTime > '2012-06-04T12:00:00'
pliki obrazów lub filmów zmodyfikowane po określonej dacie; modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')
Pliki oznaczone gwiazdką starred = true
pliki w kolekcji (np. identyfikator folderu w kolekcji parents); '1234567' in parents
Pliki w folderze danych aplikacji w kolekcji 'appDataFolder' in parents
Pliki, których właścicielem jest użytkownik „test@example.org” 'test@example.org' in owners
Pliki, do których użytkownik „test@example.org” ma uprawnienia do zapisu 'test@example.org' in writers
Pliki, do których członkowie grupy „grupa@example.org” mają uprawnienia do zapisu 'group@example.org' in writers
Pliki udostępnione autoryzowanemu użytkownikowi, które mają w nazwie słowo „hello”. sharedWithMe and name contains 'hello'
Pliki z niestandardową właściwością pliku widoczną dla wszystkich aplikacji properties has { key='mass' and value='1.3kg' }
Pliki z niestandardową właściwością pliku prywatną dla aplikacji wysyłającej prośbę appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
Pliki, które nie zostały udostępnione żadnym osobom ani domenom (tylko prywatne lub udostępnione określonym użytkownikom lub grupom). visibility = 'limited'

Filtrowanie wyników wyszukiwania za pomocą biblioteki klienta

Poniższy przykładowy kod pokazuje, jak używać biblioteki klienta do filtrowania wyników wyszukiwania według nazw plików i identyfikatorów plików JPEG. W tym przykładzie używamy terminu mimeType, aby zawęzić wyniki do plików typu image/jpeg. Ustawia też wartość spaces na drive, aby jeszcze bardziej zawęzić wyszukiwanie do przestrzeni na Dysku. Gdy nextPageToken zwróci null, nie będzie więcej wyników.

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

Wyszukiwanie plików z niestandardową właściwością

Aby wyszukać pliki z niestandardową właściwością pliku, użyj terminu wyszukiwania properties lub appProperties z kluczem i wartością. Aby na przykład wyszukać niestandardową właściwość pliku, która jest prywatna dla aplikacji wysyłającej żądanie, o nazwie additionalID i wartości 8e8aceg2af2ge72e78:

appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }

Więcej informacji znajdziesz w artykule Dodawanie niestandardowych właściwości pliku.

Wyszukiwanie plików z określoną etykietą lub wartością pola

Aby wyszukać pliki z określonymi etykietami, użyj terminu wyszukiwania labels z konkretnym identyfikatorem etykiety. Na przykład: 'labels/LABEL_ID' in labels. Jeśli operacja się uda, treść odpowiedzi będzie zawierała wszystkie instancje plików, do których zastosowano etykietę.

Aby wyszukać pliki bez określonego identyfikatora etykiety: Not 'labels/LABEL_ID' in labels.

Możesz też wyszukiwać pliki na podstawie wartości określonych pól. Aby na przykład wyszukać pliki z wartością tekstową:labels/LABEL_ID.text_field_id ='TEXT'

Więcej informacji znajdziesz w artykule Wyszukiwanie plików z konkretną etykietą lub wartością pola.

Wyszukiwanie w korpusach

Wyszukiwania, które wywołują metodę list, domyślnie używają corpora user. Aby wyszukać inne korpusy, np. pliki udostępnione domain, ustaw parametr corpora.

W ramach jednego zapytania można przeszukiwać wiele korpusów, ale jeśli połączone korpusy są zbyt duże, mogą zostać zwrócone niepełne wyniki. Jeśli w treści odpowiedzi występuje incompleteSearch,true oznacza to, że nie zwrócono wszystkich dokumentów. W takim przypadku zawęź zapytanie, wybierając inny korpus, np. user lub drive.