Dosya ve klasör arayın

Bu kılavuzda, Google Drive API'nin dosya ve klasör aramak için çeşitli yöntemleri nasıl desteklediği açıklanmaktadır.

Bir Drive kullanıcısının dosyalarının ve klasörlerinin tamamını veya bir kısmını döndürmek için files kaynağında list yöntemini kullanabilirsiniz. Bazı kaynak yöntemleri (ör. get ve update yöntemleri) için gereken fileId değerini almak üzere list yöntemini de kullanabilirsiniz.

Alanlar parametresini kullanma

Yanıtta döndürülecek alanları belirtmek istiyorsanız files kaynağının herhangi bir yöntemiyle fields sistem parametresini ayarlayabilirsiniz. fields parametresini atlarsanız sunucu, yönteme özgü varsayılan bir alan grubu döndürür. Örneğin, list yöntemi her dosya için yalnızca kind, id, name, mimeType ve resourceKey alanlarını döndürür. Farklı alanlar döndürmek için Belirli alanları döndürme başlıklı makaleyi inceleyin.

Kimliğe göre dosya alma

Bir dosyayı almak için files kaynağında fileId yol parametresiyle get yöntemini kullanın. Dosya kimliğini bilmiyorsanız list yöntemini kullanarak tüm dosyaları listeleyebilirsiniz.

Yöntem, dosyayı files kaynağının bir örneği olarak döndürür. alt=media parametresini sağlarsanız yanıt, dosya içeriklerini yanıt gövdesinde içerir. Blob dosyası indirmek için Blob dosyası içeriğini indirme başlıklı makaleyi inceleyin.

Bilinen kötü amaçlı yazılımları veya diğer kötüye kullanım amaçlı dosyaları indirme riskini kabul etmek için acknowledgeAbuse sorgu parametresini true olarak ayarlayın. Bu alan yalnızca alt=media parametresi ayarlandığında ve kullanıcı, dosya sahibi veya dosyanın bulunduğu ortak Drive'ın düzenleyicisi olduğunda geçerlidir.

Drive'ım bölümündeki tüm dosya ve klasörleri listeleme

Geçerli kullanıcının Drive'ım bölümündeki tüm dosya ve klasörleri döndürmek için list yöntemini parametre olmadan kullanın.

Aşağıdaki curl komutunda tüm dosyaların nasıl listeleneceği gösterilmektedir:

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

ACCESS_TOKEN yerine yetkili bir OAuth 2.0 erişim jetonu yerleştirin.

Drive'ım bölümünde belirli dosya ve klasörleri arama

Mevcut kullanıcının Drive'ım klasöründe belirli bir dosya veya klasör grubunu aramak için q sorgu dizesi alanını list yöntemiyle birlikte kullanarak döndürülecek dosyaları filtreleyin. Bu işlem için bir veya daha fazla arama terimini birleştirin.

Sorgu dizesi söz dizimi aşağıdaki üç bölümü içerir:

query_term operator values

Burada:

• query_term, sorgu terimi veya aranacak alandır.

• operator, sorgu teriminin koşulunu belirtir.

• values, arama sonuçlarınızı filtrelemek için kullanmak istediğiniz belirli değerlerdir.

Örneğin, aşağıdaki sorgu dizesi, MIME türü ayarlanarak aramanın yalnızca klasörleri döndürmesi için filtreler:

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

Tüm dosya sorgu terimlerini görüntülemek için Dosyaya özel sorgu terimleri başlıklı makaleyi inceleyin.

Sorgu oluşturmak için kullanabileceğiniz tüm sorgu operatörlerini görüntülemek istiyorsanız Sorgu operatörleri başlıklı makaleyi inceleyin.

Sorgu dizesi örnekleri

Aşağıdaki tabloda, bazı temel sorgu dizeleriyle ilgili örnekler verilmiştir. Gerçek kod, aramanız için kullandığınız istemci kitaplığına göre farklılık gösterir.

Sorgunun doğru çalıştığından emin olmak için dosya adlarınızdaki özel karakterleri de kod dışına almanız gerekir. Örneğin, bir dosya adında hem kesme işareti (') hem de ters eğik çizgi ("\") karakteri varsa bunları çıkış karakteriyle (name contains 'quinn\'s paper\\essay') ayırın.

Arama sonuçlarını istemci kitaplığıyla filtreleme

Aşağıdaki kod örneğinde, arama sonuçlarını JPEG dosyalarının dosya adlarına ve kimliklerine göre filtrelemek için istemci kitaplığının nasıl kullanılacağı gösterilmektedir. Bu örnekte, sonuçları image/jpeg türündeki dosyalarla sınırlandırmak için mimeType sorgu terimi kullanılmaktadır. Ayrıca, aramayı Drive alanına daha da daraltmak için spaces değerini drive olarak ayarlar. nextPageToken, null değerini döndürdüğünde başka sonuç kalmamış demektir.

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

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()

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

Ortak klasördeki dosyaları listeleme

Herkese açık olarak paylaşılan bir klasördeki (erişimin "Bağlantıya sahip olan herkes" veya "Herkese açık" olarak ayarlandığı) dosyaları aramak ya da listelemek için parents koleksiyonundaki klasörün kimliğine göre filtreleme yapmak üzere q sorgu parametresi ayarlanmış files kaynağında list yöntemini kullanın:

'FOLDER_ID' in parents and trashed = false

Herkese açık bir klasördeki dosyaları listelerken, OAuth 2.0 kullanıcı kimlik bilgileri yerine API anahtarı kullanarak isteklerin kimliğini doğrulayabilirsiniz. Klasör bir ortak Drive'da bulunuyorsa istekte supportsAllDrives=true ve includeItemsFromAllDrives=true ayarlarını da yapmanız gerekir.

Aşağıdaki kod örneklerinde, herkese açık bir klasördeki dosyaların nasıl listeleneceği gösterilmektedir:

/**
 * 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 -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'

Alt klasörleri ve dosyaları yinelemeli olarak arama

parents sorgu terimi, yalnızca belirtilen klasörde bulunan doğrudan alt dosya ve klasörleri döndürür. Drive API, tek bir API çağrısında alt klasör ağaçlarını yinelemeli olarak aramak için bir sorgu operatörü veya parametresi sağlamaz.

Bir klasörü ve altındaki tüm alt klasörleri ve dosyaları aramak için uygulamanızın istemci tarafında ağaç geçişi yapması gerekir:

1. 'FOLDER_ID' in parents and trashed = false kullanarak hedef klasörün doğrudan alt öğelerini sorgulayın.
2. Sonuçları mimeType = 'application/vnd.google-apps.folder' ile filtreleyerek alt klasörleri belirleyin.
3. İçeriğini almak için her bir alt klasörün kimliğini yinelemeli veya tekrarlı olarak sorgulayın.

Aşağıdaki kod örneklerinde, bir klasörün ve alt öğelerinin yinelemeli olarak nasıl aranacağı gösterilmektedir:

/**
 * 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;
  }
}

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

Özel özelliklere sahip dosyaları arama

Özel dosya özelliğine sahip dosyaları aramak için anahtar ve değer içeren properties veya appProperties arama sorgusu terimini kullanın. Örneğin, istekte bulunan uygulamaya özel olan, additionalID adlı ve 8e8aceg2af2ge72e78 değerine sahip bir özel dosya özelliğini aramak için:

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

Daha fazla bilgi için Özel dosya özellikleri ekleme başlıklı makaleyi inceleyin.

Dosyaları etikete veya alan değerine göre arama

Belirli etiketlere sahip dosyaları aramak için labels arama sorgusu terimini belirli bir etiket kimliğiyle birlikte kullanın.

Belirli bir etiketin uygulandığı dosyaları aramak için:

'labels/LABEL_ID' in labels

Belirli bir etiketin uygulanmadığı dosyaları aramak için:

not 'labels/LABEL_ID' in labels

Belirli bir etiket alanı değerine göre dosya aramak için:

labels/LABEL_ID.FIELD_ID = 'VALUE'

Başarılı olursa yanıt gövdesi, sorguyla eşleşen tüm dosya örneklerini içerir. Daha fazla bilgi için Belirli bir etikete veya alan değerine sahip dosyaları arama başlıklı makaleyi inceleyin.

Derlemelerde arama yapma

list yöntemi kullanıldığında user öğe koleksiyonu varsayılan olarak corpora sorgu parametresinde ayarlanır. domain ile paylaşılanlar gibi diğer öğe koleksiyonlarında arama yapmak için corpora parametresini açıkça ayarlamanız gerekir.

Tek bir sorguda birden fazla derlemeyi arayabilirsiniz. Ancak birleştirilen derlemeler çok büyükse API eksik sonuçlar döndürebilir. Yanıt gövdesindeki incompleteSearch alanını kontrol edin. true ise bazı belgeler atlanmıştır. Bu sorunu çözmek için corpora değerini user veya drive kullanacak şekilde daraltın.

list yönteminde orderBy sorgu parametresini kullanırken büyük öğe koleksiyonlarındaki sorgular için createdTime anahtarını kullanmaktan kaçının. Bu anahtar ek işlem gerektirir ve zaman aşımlarına veya başka sorunlara neden olabilir. Büyük öğe koleksiyonlarında zamana göre sıralama için bu sorguları işlemek üzere optimize edildiğinden modifiedTime kullanabilirsiniz. Örneğin, orderBy değerini modifiedTime (veya modifiedTime desc) olarak ayarlayın.

orderBy sorgu parametresini atlarsanız varsayılan bir sıralama ölçütü olmaz ve öğeler rastgele döndürülür.

İlgili konular

• Ortak Drive'ları arama
• Arama sorgusu terimleri ve operatörleri
• Google Workspace ve Google Drive'ın desteklediği MIME türleri
• Roller ve izinler
• Belirli bir etikete veya alan değerine sahip dosyaları arama