Mengelola metadata file

Dokumen ini membahas pertimbangan penting untuk memberi nama file dan menangani metadata seperti teks yang dapat diindeks dan thumbnail. Untuk menyisipkan dan mengambil file, lihat resource files.

Ringkasan metadata

Di Google Drive API, resource files merepresentasikan metadata. Tidak seperti API yang menggunakan metadata sebagai sub-objek, Drive API memperlakukan seluruh resource files sebagai metadata. Anda dapat mengakses metadata secara langsung melalui metode get atau list pada resource files.

Secara default, metode get dan list hanya menampilkan sebagian kolom. Untuk mengambil data tertentu, Anda harus menentukan parameter sistem fields dalam permintaan Anda. Jika tidak disertakan, server akan menampilkan subset kolom default yang 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.

Selain itu, visibilitas metadata bergantung pada peran pengguna pada file. Resource permissions tidak menentukan tindakan yang diizinkan pengguna pada file atau folder. Sebaliknya, resource files berisi kumpulan kolom capabilities boolean. Google Drive API mendapatkan capabilities ini dari resource permissions yang terkait dengan file atau folder. Untuk mengetahui informasi selengkapnya, lihat Memahami kemampuan file.

Drive API menawarkan dua cakupan metadata terbatas: drive.metadata dan drive.metadata.readonly. Cakupan drive.metadata memungkinkan Anda melihat dan mengelola metadata file, sedangkan drive.metadata.readonly bersifat hanya baca. Keduanya melarang keras akses ke konten file. Untuk mengetahui informasi selengkapnya, lihat Memilih cakupan Google Drive API.

Terakhir, selalu verifikasi logika Anda terkait izin dan cakupan. Misalnya, pengguna mungkin memiliki file dengan izin penuh, tetapi Drive API akan memblokir upaya untuk mengubah atau mendownload file jika aplikasi Anda hanya memiliki cakupan drive.metadata.readonly.

Menentukan nama dan ekstensi file

Aplikasi harus menentukan ekstensi file di properti name) saat menyisipkan file dengan Google Drive API. Misalnya, operasi untuk menyisipkan file JPEG harus menentukan sesuatu seperti "name": "cat.jpg" dalam metadata.

Respons GET berikutnya dapat menyertakan properti fileExtension hanya baca yang diisi dengan ekstensi yang awalnya ditentukan dalam properti name. Saat pengguna Google Drive meminta untuk mendownload file, atau saat file didownload melalui klien sinkronisasi, Drive membuat nama file lengkap (dengan ekstensi) berdasarkan nama. Jika ekstensi tidak ada, Drive akan mencoba menentukan ekstensi berdasarkan jenis MIME file.

Menyimpan teks yang dapat diindeks

Drive secara otomatis mengindeks dokumen untuk penelusuran saat mengenali jenis file, termasuk dokumen teks, PDF, gambar dengan teks, dan jenis umum lainnya. Jika aplikasi Anda menyimpan jenis file lain (seperti gambar, video, dan pintasan), Anda dapat meningkatkan penemuan dengan menyediakan teks yang dapat diindeks di kolom contentHints.indexableText file.

Teks yang dapat diindeks diindeks sebagai HTML. Jika Anda menyimpan string teks yang dapat diindeks <section attribute="value1">Here's some text</section>, maka "Here's some text" akan diindeks, tetapi "value1" tidak. Oleh karena itu, menyimpan XML sebagai teks yang dapat diindeks tidak seberguna menyimpan HTML.

Saat menentukan indexableText, perhatikan juga:

  • Batas ukuran untuk contentHints.indexableText adalah 128 KB.
  • Catat istilah dan konsep utama yang Anda harapkan akan ditelusuri pengguna.
  • Jangan mencoba mengurutkan teks berdasarkan urutan kepentingan karena pengindeks akan melakukannya secara efisien untuk Anda.
  • Aplikasi Anda harus memperbarui teks yang dapat diindeks setiap kali disimpan.
  • Pastikan teks terkait dengan konten atau metadata file.

Poin terakhir ini mungkin tampak jelas, tetapi penting. Sebaiknya jangan menambahkan istilah yang umum ditelusuri untuk memaksa file muncul di hasil penelusuran. Hal ini dapat membuat pengguna frustrasi, dan bahkan dapat memotivasi mereka untuk menghapus file.

Mengupload thumbnail

Drive otomatis membuat thumbnail untuk banyak jenis file umum, seperti Google Dokumen, Spreadsheet, dan Slide. Thumbnail membantu pengguna mengidentifikasi file Drive dengan lebih baik.

Untuk jenis file yang tidak dapat dibuat thumbnail standarnya oleh Drive, Anda dapat memberikan gambar thumbnail yang dibuat oleh aplikasi Anda. Selama pembuatan atau pembaruan file, upload thumbnail dengan menyetel kolom contentHints.thumbnail pada resource files.

Khususnya:

  • Tetapkan kolom contentHints.thumbnail.image ke gambar berenkode base64 yang aman bagi URL dan nama file (lihat RFC 4648 bagian 5).
  • Tetapkan kolom contentHints.thumbnail.mimeType ke jenis MIME yang sesuai untuk thumbnail.

Jika Drive dapat membuat thumbnail dari file, Drive akan menggunakan thumbnail yang dibuat secara otomatis dan mengabaikan thumbnail yang mungkin telah Anda upload. Jika tidak dapat membuat thumbnail, video akan menggunakan thumbnail yang Anda berikan.

Thumbnail harus mematuhi aturan berikut:

  • Dapat diupload dalam format PNG, GIF, atau JPG.
  • Lebar yang direkomendasikan adalah 1600 piksel.
  • Lebar minimum adalah 220 piksel.
  • Ukuran file maksimum adalah 2 MB.
  • Data ini harus diperbarui oleh aplikasi Anda setiap kali ada penyimpanan.

Untuk mengetahui informasi selengkapnya, lihat resource files.

Mengambil thumbnail

Anda dapat mengambil metadata, termasuk thumbnail, untuk file Drive. Informasi thumbnail berada di kolom thumbnailLink dari resource files.

Menampilkan thumbnail tertentu

Contoh kode berikut menunjukkan permintaan metode get dengan beberapa kolom sebagai parameter kueri untuk menampilkan metadata thumbnailLink untuk file tertentu. Untuk mengetahui informasi selengkapnya, lihat Menampilkan kolom tertentu untuk file.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink

Ganti FILE_ID dengan fileId file yang ingin Anda temukan.

Jika tersedia, permintaan akan menampilkan URL berumur pendek ke thumbnail file. Biasanya, masa berlaku link adalah beberapa jam. Kolom ini hanya diisi jika aplikasi yang meminta dapat mengakses konten file. Jika file tidak dibagikan secara publik, URL yang ditampilkan di thumbnailLink harus diambil menggunakan permintaan dengan kredensial.

Menampilkan daftar thumbnail

Contoh kode berikut menunjukkan permintaan metode list dengan beberapa kolom sebagai parameter kueri untuk menampilkan metadata thumbnailLink untuk daftar file. Untuk mengetahui informasi selengkapnya, lihat Menelusuri file dan folder.

GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)

Untuk membatasi hasil penelusuran ke jenis file tertentu, terapkan string kueri untuk menetapkan jenis MIME. Misalnya, contoh kode berikut menunjukkan cara membatasi daftar ke file Google Spreadsheet. Untuk mengetahui informasi selengkapnya tentang jenis MIME, lihat Jenis MIME yang didukung Google Workspace dan Google Drive.

GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)