Menelusuri file dan folder

Panduan ini menjelaskan cara Google Drive API mendukung beberapa cara untuk menelusuri file dan folder.

Anda dapat menggunakan metode list pada resource files untuk menampilkan semua atau sebagian file dan folder pengguna Drive. Anda juga dapat menggunakan metode list untuk mengambil fileId yang diperlukan untuk beberapa metode resource (seperti metode get dan update).

Menggunakan parameter fields

Jika ingin menentukan kolom yang akan ditampilkan dalam respons, Anda dapat menyetel parameter sistem fields dengan metode apa pun dari resource files. Jika Anda menghapus parameter fields, server akan menampilkan kumpulan kolom default khusus untuk metode tersebut. Misalnya, metode list hanya menampilkan kolom kind, id, name, mimeType, dan resourceKey untuk setiap file. Untuk menampilkan kolom yang berbeda, lihat Menampilkan kolom tertentu.

Mendapatkan file menurut ID

Untuk mendapatkan file, gunakan metode get pada resource files dengan parameter jalur fileId. Jika tidak mengetahui ID file, Anda dapat mencantumkan semua file menggunakan metode list.

Metode ini menampilkan file sebagai instance resource files. Jika Anda memberikan parameter alt=media, respons akan menyertakan isi file dalam isi respons. Untuk mendownload file blob, lihat Mendownload konten file blob.

Untuk mengonfirmasi risiko mendownload malware yang diketahui atau file berbahaya lainnya, tetapkan parameter kueri acknowledgeAbuse ke true. Kolom ini hanya berlaku jika parameter alt=media ditetapkan dan pengguna adalah pemilik file atau pengelola drive bersama tempat file berada.

Mencantumkan semua file dan folder di Drive Saya

Gunakan metode list tanpa parameter apa pun untuk menampilkan semua file dan folder di Drive Saya milik pengguna saat ini.

Perintah curl berikut menunjukkan cara mencantumkan semua file:

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

Ganti ACCESS_TOKEN dengan token akses OAuth 2.0 yang diizinkan.

Menelusuri file dan folder tertentu di Drive Saya

Untuk menelusuri kumpulan file atau folder tertentu di Drive Saya milik pengguna saat ini, gunakan kolom string kueri q dengan metode list untuk memfilter file yang akan ditampilkan dengan menggabungkan satu atau beberapa istilah penelusuran.

Sintaksis string kueri berisi tiga bagian berikut:

query_term operator values

Dengan:

• query_term adalah istilah atau kolom kueri yang akan ditelusuri.

• operator menentukan kondisi untuk istilah kueri.

• values adalah nilai spesifik yang ingin Anda gunakan untuk memfilter hasil penelusuran.

Misalnya, string kueri berikut memfilter penelusuran agar hanya menampilkan folder dengan menetapkan jenis MIME:

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

Untuk melihat semua istilah kueri file, lihat Istilah kueri khusus file.

Untuk melihat semua operator kueri yang dapat Anda gunakan untuk membuat kueri, lihat Operator kueri.

Contoh string kueri

Tabel berikut mencantumkan contoh beberapa string kueri dasar. Kode sebenarnya berbeda-beda, bergantung pada library klien yang Anda gunakan untuk penelusuran.

Penting: Istilah kueri berikut menggunakan kolom dari Drive API v3. Beberapa kolom resource berubah antara v2 dan v3. Misalnya, name menggantikan title. Jika Anda menggunakan Drive API v2, sesuaikan kueri ini untuk menggunakan kolom v2. Untuk mengetahui informasi selengkapnya, lihat referensi perbandingan Drive API v2 dan v3.

Anda juga harus meng-escape karakter khusus dalam nama file untuk memastikan kueri berfungsi dengan benar. Misalnya, jika nama file berisi karakter apostrof (') dan garis miring terbalik ("\"), gunakan garis miring terbalik untuk meng-escape-nya: name contains 'quinn\'s paper\\essay'.

Catatan: Contoh ini menggunakan parameter q yang tidak di-encode, dengan name = 'hello' di-encode sebagai name+%3d+%27hello%27. Library klien menangani encoding ini secara otomatis.

Yang perlu dikueri	Contoh
Operator pencocokan string (contains)
File yang berisi kata "hello"	fullText contains 'hello'
File yang berisi frasa persis "halo dunia"	fullText contains '"hello world"'
File dengan kueri yang berisi karakter "\" (misalnya, "\authors")	fullText contains '\\authors'
File dengan nama yang berisi "anggaran"	name contains 'budget'
Operator kesetaraan dan ketidaksetaraan (=, !=)
File dengan nama "hello"	name = 'hello'
File yang berupa folder	mimeType = 'application/vnd.google-apps.folder'
File yang bukan folder	mimeType != 'application/vnd.google-apps.folder'
File yang diberi bintang	starred = true
File yang ada di sampah	trashed = true
File yang tidak ada di sampah	trashed = false
Pintasan yang mengarah ke ID file tertentu	shortcutDetails.targetId = '1987654321'
File yang belum dibagikan kepada siapa pun atau domain (pribadi, atau dibagikan kepada pengguna atau grup tertentu)	visibility = 'limited'
File yang dapat diakses oleh siapa saja yang memiliki link	visibility = 'anyoneWithLink'
File yang dapat ditemukan secara publik di web	visibility = 'anyoneCanFind'
Operator perbandingan (>, >=, <, <=)
File yang diubah setelah tanggal tertentu (zona waktu default adalah UTC)	modifiedTime > '2012-06-04T12:00:00'
File yang dibuat setelah 1 Januari 2023	createdTime > '2023-01-01T00:00:00'
File yang diubah sebelum 1 Januari 2023	modifiedTime < '2023-01-01T00:00:00'
Operator keanggotaan koleksi (in)
File turunan langsung dalam koleksi (misalnya, ID folder dalam koleksi parents)	'1234567' in parents
File di folder data aplikasi	'appDataFolder' in parents
File yang dimiliki oleh pengguna "[e-mail]"	'[e-mail]' in owners
File yang izin tulisnya dimiliki oleh pengguna "[e-mail]"	'[e-mail]' in writers
File yang memiliki izin tulis untuk anggota grup "[e-mail]"	'[e-mail]' in writers
File yang izin bacanya dimiliki oleh pengguna "[e-mail]"	'[e-mail]' in readers
Operator pencocokan koleksi (has)
File dengan properti file kustom yang dapat dilihat oleh semua aplikasi	properties has { key='mass' and value='1.3kg' }
File dengan properti file kustom yang bersifat pribadi untuk aplikasi yang meminta	appProperties has { key='additionalID' and value='8e8aceg2af2ge72e78' }
File yang memiliki properti file kustom dengan kunci "department" (terlepas dari nilainya)	properties has { key='department' }
Operator logika (and, or, not)
File dengan nama yang berisi kata "hello" dan "goodbye"	name contains 'hello' and name contains 'goodbye'
File dengan nama yang tidak berisi kata "halo"	not name contains 'hello'
File yang berisi teks "penting" dan berada di sampah	fullText contains 'important' and trashed = true
File yang tidak berisi kata "halo"	not fullText contains 'hello'
File gambar atau video yang diubah setelah tanggal tertentu	modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')
File yang dibagikan kepada pengguna yang diberi otorisasi yang memiliki kata "halo" dalam namanya	sharedWithMe and name contains 'hello'
File yang berupa folder atau pintasan	mimeType = 'application/vnd.google-apps.folder' or mimeType = 'application/vnd.google-apps.shortcut'
File dengan nama "Project Plan" yang tidak ada di sampah	name = 'Project Plan' and trashed = false
File turunan langsung di folder tertentu yang tidak ada di sampah	'1234567' in parents and trashed = false

Memfilter hasil penelusuran dengan library klien

Contoh kode berikut menunjukkan cara menggunakan library klien untuk memfilter hasil penelusuran ke nama file dan ID file JPEG. Contoh ini menggunakan istilah kueri mimeType untuk mempersempit hasil ke file jenis image/jpeg. Parameter ini juga menetapkan spaces ke drive untuk mempersempit penelusuran ke ruang Drive. Jika nextPageToken menampilkan null, tidak ada lagi hasil.

Catatan: Jika Anda menggunakan Drive API v2 yang lebih lama, Anda dapat menemukan contoh kode di GitHub. Pelajari cara bermigrasi ke Drive API v3.

Java

drive/snippets/drive_v3/src/main/java/SearchFile.java

Lihat di 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

Lihat di 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

Lihat di 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

Lihat di 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;
    }
}

Mencantumkan file dalam folder publik

Untuk menelusuri atau mencantumkan file dalam folder yang dibagikan secara publik (dengan akses yang ditetapkan ke "Siapa saja yang memiliki link" atau "Publik di web"), gunakan metode list pada resource files dengan parameter kueri q yang ditetapkan untuk memfilter menurut ID folder dalam koleksi parents:

'FOLDER_ID' in parents and trashed = false

Saat mencantumkan file dalam folder publik, Anda dapat mengautentikasi permintaan menggunakan kunci API, bukan kredensial pengguna OAuth 2.0. Jika folder berada dalam drive bersama, Anda juga harus menetapkan supportsAllDrives=true dan includeItemsFromAllDrives=true pada permintaan.

Contoh kode berikut menunjukkan cara mencantumkan file dalam folder publik:

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'

Ganti kode berikut:

• FOLDER_ID: ID folder publik.
• API_KEY: Kunci API project Anda.

Menelusuri folder dan file turunan secara rekursif

Istilah kueri parents hanya menampilkan file dan folder turunan langsung yang berada dalam folder yang ditentukan. Drive API tidak menyediakan operator atau parameter kueri untuk menelusuri hierarki subfolder turunan secara rekursif dalam satu panggilan API.

Untuk menelusuri folder dan semua subfolder serta file turunannya, aplikasi Anda harus melakukan penjelajahan hierarki sisi klien:

1. Buat kueri turunan langsung dari folder target menggunakan 'FOLDER_ID' in parents and trashed = false.
2. Identifikasi subfolder dengan memfilter hasil yang berisi mimeType = 'application/vnd.google-apps.folder'.
3. Buat kueri ID setiap folder turunan secara rekursif atau iteratif untuk mengambil isinya.

Contoh kode berikut menunjukkan cara menelusuri folder dan turunannya secara rekursif:

Node.js

/**
 * Recursively searches a folder and all descendant subfolders for files.
 * @param {string} folderId The ID of the starting folder.
 * @param {Object} authClient An authorized OAuth 2.0 client.
 * @return {Promise<Array>} The list of all descendant files.
 */
async function searchFolderRecursively(folderId, authClient) {
  const {google} = require('googleapis');
  const service = google.drive({version: 'v3', auth: authClient});
  const allFiles = [];
  const foldersToSearch = [folderId];

  try {
    while (foldersToSearch.length > 0) {
      const currentFolderId = foldersToSearch.pop();
      let pageToken = null;

      do {
        const response = await service.files.list({
          q: `'${currentFolderId}' in parents and trashed = false`,
          fields: 'nextPageToken, files(id, name, mimeType)',
          pageSize: 1000,
          supportsAllDrives: true,
          includeItemsFromAllDrives: true,
          pageToken: pageToken,
        });

        const files = response.data.files || [];
        for (const file of files) {
          if (file.mimeType === 'application/vnd.google-apps.folder') {
            foldersToSearch.push(file.id);
          } else {
            allFiles.push(file);
          }
        }

        pageToken = response.data.nextPageToken;
      } while (pageToken);
    }
    return allFiles;
  } catch (err) {
    // TODO(developer): Handle error
    console.error(err);
    throw err;
  }
}

Python

from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

def search_folder_recursively(folder_id, creds):
    """Recursively searches a folder and all descendant subfolders for
    files.

    Args:
        folder_id: The ID of the starting folder.
        creds: An authorized OAuth 2.0 credentials object.

    Returns:
        A list of all descendant file resources.
    """
    service = build("drive", "v3", credentials=creds)
    all_files = []
    folders_to_search = [folder_id]

    try:
        while folders_to_search:
            current_folder_id = folders_to_search.pop()
            page_token = None

            while True:
                response = (
                    service.files()
                    .list(
                        q=f"'{current_folder_id}' in parents and trashed = false",
                        fields="nextPageToken, files(id, name, mimeType)",
                        pageSize=1000,
                        supportsAllDrives=True,
                        includeItemsFromAllDrives=True,
                        pageToken=page_token,
                    )
                    .execute()
                )

                for item in response.get("files", []):
                    if (
                        item.get("mimeType")
                        == "application/vnd.google-apps.folder"
                    ):
                        folders_to_search.append(item.get("id"))
                    else:
                        all_files.append(item)

                page_token = response.get("nextPageToken")
                if not page_token:
                    break

        return all_files
    except HttpError as error:
        # TODO(developer): Handle error
        print(f"An error occurred: {error}")
        return None

Menelusuri file dengan properti kustom

Untuk menelusuri file dengan properti file kustom, gunakan istilah kueri penelusuran properties atau appProperties dengan kunci dan nilai. Misalnya, untuk menelusuri properti file kustom yang bersifat pribadi untuk aplikasi yang meminta bernama additionalID dengan nilai 8e8aceg2af2ge72e78:

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

Untuk mengetahui informasi selengkapnya, lihat Menambahkan properti file kustom.

Menelusuri file berdasarkan label atau nilai kolom

Untuk menelusuri file dengan label tertentu, gunakan istilah kueri penelusuran labels dengan ID label tertentu.

Untuk menelusuri file yang memiliki label tertentu:

'labels/LABEL_ID' in labels

Untuk menelusuri file yang tidak menerapkan label tertentu:

not 'labels/LABEL_ID' in labels

Untuk menelusuri file berdasarkan nilai kolom label tertentu:

labels/LABEL_ID.FIELD_ID = 'VALUE'

Jika berhasil, isi respons akan berisi semua instance file yang cocok dengan kueri. Untuk mengetahui informasi selengkapnya, lihat Menelusuri file dengan label atau nilai kolom tertentu.

Menelusuri di seluruh korpus

Secara default, koleksi item user ditetapkan pada parameter kueri corpora saat metode list digunakan. Untuk menelusuri koleksi item lainnya, seperti yang dibagikan dengan domain, Anda harus menetapkan parameter corpora secara eksplisit.

Anda dapat menelusuri beberapa korpus dalam satu kueri; namun, jika gabungan korpus terlalu besar, API mungkin menampilkan hasil yang tidak lengkap. Periksa kolom incompleteSearch dalam isi respons. Jika nilainya true, berarti beberapa dokumen telah dihilangkan. Untuk mengatasinya, persempit corpora untuk menggunakan user atau drive.

Saat menggunakan parameter kueri orderBy pada metode list, hindari penggunaan kunci createdTime untuk kueri pada kumpulan item besar karena memerlukan pemrosesan tambahan dan dapat menyebabkan waktu tunggu habis atau masalah lainnya. Untuk pengurutan terkait waktu pada koleksi item yang besar, Anda dapat menggunakan modifiedTime karena dioptimalkan untuk menangani kueri ini. Misalnya, tetapkan orderBy ke modifiedTime (atau modifiedTime desc).

Jika Anda menghilangkan parameter kueri orderBy, tidak ada tata urutan default dan item ditampilkan secara arbitrer.

Topik terkait

• Menelusuri drive bersama
• Istilah dan operator kueri penelusuran
• Jenis MIME yang didukung Google Workspace dan Google Drive
• Peran dan izin
• Menelusuri file dengan label atau nilai kolom tertentu