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 dosya ve klasörlerinin tamamını veya bir kısmını döndürmek için list yöntemini files kaynağında kullanabilirsiniz. Ayrıca, bazı kaynak yöntemleri (ör. list ve fileIdupdate yöntemleri) için gerekli olan get yöntemini de kullanabilirsiniz.

Alanlar parametresini kullanma

Yanıtla döndürülecek alanları belirtmek istiyorsanız fields system parametresini files kaynağının herhangi bir yöntemiyle ayarlayabilirsiniz. fields parametresini atlarsanız sunucu, yönteme özgü varsayılan bir alan kümesi 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ı makaleye bakın.

Kimliğe göre dosya alma

Bir dosyayı almak için fileId yol parametresiyle files kaynağında 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ı indirmenin riskini kabul etmek için acknowledgeAbuse sorgu parametresini true olarak ayarlayın. Bu alan yalnızca alt=media parametresi ayarlandığında ve kullanıcının dosya sahibi ya da dosyanın bulunduğu ortak Drive'ın düzenleyicisi olması durumunda geçerlidir.

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

Mevcut 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 komutu, tüm dosyaların nasıl listeleneceğini gösterir:

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 terimi için koşulu 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 sorgusu terimlerini görüntülemek için Dosyaya özgü sorgu terimleri başlıklı makaleyi inceleyin.

Sorgu oluşturmak için kullanabileceğiniz tüm sorgu operatörlerini görüntülemek üzere 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 bağlı olarak değişir.

Sorgunun doğru şekilde çalışması 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ı kod dışı bırakmak için ters eğik çizgi kullanın: name contains 'quinn\'s paper\\essay'.

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

Aşağıdaki kod örneğinde, arama sonuçlarını JPEG dosyalarının 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ırlamak için mimeType sorgu terimi kullanılmaktadır. Ayrıca, aramayı Drive alanıyla daha da daraltmak için spaces değerini drive olarak ayarlar. nextPageToken null değerini döndürdüğünde başka sonuç yoktur.

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 "Web'de herkese açık" olarak ayarlandığı) dosyaları aramak ya da listelemek için parents koleksiyonunda klasörün kimliğine göre filtreleme yapmak üzere files kaynağında q sorgu parametresi ayarlanmış 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'

Özel özelliklere sahip dosyaları arama

Özel dosya özelliği içeren dosyaları aramak için anahtar ve değer içeren properties veya appProperties arama sorgusu terimini kullanın. Örneğin, additionalID adlı istekte bulunan uygulamaya özel olan ve değeri 8e8aceg2af2ge72e78 olan 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

Dosyaları belirli bir etiket alanı değerine göre 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

Varsayılan olarak, list yöntemi kullanıldığında user öğe koleksiyonu corpora sorgu parametresinde ayarlanır. Diğer öğe koleksiyonlarını (ör. domain ile paylaşılanlar) aramak için corpora parametresini açıkça ayarlamanız gerekir.

Tek bir sorguda birden fazla derlemeyi arayabilirsiniz. Ancak birleştirilmiş 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'ı daraltarak user veya drive'ı kullanı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 öğesini modifiedTime (veya modifiedTime desc) olarak ayarlayın.

orderBy sorgu parametresini atlarsanız varsayılan sıralama düzeni 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'da desteklenen MIME türleri
• Roller ve izinler
• Belirli bir etikete veya alan değerine sahip dosyaları arama