Menampilkan kolom tertentu

Dokumen ini menjelaskan cara menggunakan parameter fields di Google Drive.

Untuk menampilkan kolom yang tepat yang Anda butuhkan, dan untuk meningkatkan performa, gunakan fields parameter sistem dalam panggilan metode Anda.

Untuk mengetahui informasi tentang parameter sistem lain yang berlaku untuk Drive API, lihat Parameter sistem alternatif.

Cara kerja parameter kolom

Parameter fields menggunakan FieldMask untuk pemfilteran respons. Mask kolom digunakan untuk menentukan subset kolom yang harus ditampilkan oleh permintaan. Penggunaan mask kolom merupakan praktik desain yang baik untuk memastikan Anda tidak meminta data yang tidak diperlukan, yang pada gilirannya membantu menghindari waktu pemrosesan yang tidak perlu.

Jika Anda tidak menentukan parameter fields, server akan menampilkan kumpulan kolom default yang khusus untuk metode tersebut. Misalnya, metode list pada resource files hanya menampilkan kolom kind, id, name, dan mimeType. Metode get pada permissions resource menampilkan kumpulan kolom default yang berbeda.

Untuk semua metode resource about, approvals, comments (tidak termasuk delete), dan replies (tidak termasuk delete), Anda harus menetapkan parameter fields. Metode ini tidak menampilkan kumpulan kolom default.

Setelah server memproses permintaan valid yang menyertakan parameter fields, server akan menampilkan kode status HTTP 200 OK, bersama dengan data yang diminta. Jika parameter kolom mengalami error atau tidak valid, server akan menampilkan kode status HTTP 400 Bad Request, bersama dengan pesan error yang menyatakan apa yang salah dengan pemilihan kolom Anda. Misalnya, files.list(fields='files(id,capabilities,canAddChildren)') menghasilkan error "Invalid field selection canAddChildren." Parameter kolom yang benar untuk contoh ini adalah files.list(fields='files(id,capabilities/canAddChildren)').

Untuk menentukan kolom yang dapat Anda tampilkan menggunakan parameter fields, buka halaman dokumentasi resource yang Anda kueri. Misalnya, untuk melihat kolom yang dapat Anda tampilkan untuk file, lihat dokumentasi resource files. Untuk mengetahui istilah kueri yang lebih spesifik untuk file, lihat Istilah dan operator kueri penelusuran.

Aturan format parameter kolom

Format nilai parameter permintaan kolom hanya didasarkan pada sintaksis XPath. Berikut adalah aturan pemformatan untuk parameter fields. Semua aturan ini menggunakan contoh yang terkait dengan metode files.get.

  • Gunakan daftar yang dipisahkan koma untuk memilih beberapa kolom, seperti 'name, mimeType'.

  • Gunakan a/b untuk memilih kolom b yang ditempatkan dalam kolom a, seperti 'capabilities/canDownload'. Untuk mengetahui informasi selengkapnya, lihat Mengambil kolom resource bertingkat.

  • Gunakan sub-selektor untuk meminta kumpulan sub-kolom spesifik dari array atau objek dengan menempatkan ekspresi dalam tanda kurung "()". Misalnya, 'permissions(id)' hanya menampilkan ID izin untuk setiap elemen dalam array izin.

  • Untuk menampilkan semua kolom dalam objek, gunakan tanda bintang (*) sebagai karakter pengganti dalam pemilihan kolom. Misalnya, 'permissions/permissionDetails/*' memilih semua kolom detail izin yang tersedia per izin. Perhatikan bahwa penggunaan karakter pengganti dapat menyebabkan dampak performa negatif pada permintaan.

  • Anda tidak dapat memilih elemen individual peta jika kuncinya berisi karakter khusus (seperti garis miring / atau titik .). Misalnya, mencoba memilih kunci format ekspor tertentu di exportLinks menggunakan fields=exportLinks/application/pdf akan menghasilkan error HTTP 400 Bad Request karena parser jalur menafsirkan / sebagai pembatas properti bertingkat. Untuk mengambil pasangan nilai kunci dengan karakter khusus di kuncinya, minta seluruh peta (seperti fields=exportLinks) dan filter hasil di sisi klien.

Permintaan

Dalam contoh ini, kami menyediakan parameter jalur ID file dan beberapa kolom sebagai parameter kueri dalam permintaan. Respons menampilkan nilai kolom untuk ID file.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

Respons

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

Mengambil kolom resource bertingkat

Jika kolom merujuk ke resource lain, Anda dapat menentukan kolom resource bertingkat mana yang harus diambil.

Misalnya, untuk mengambil kolom role (resource bertingkat) dari resource permissions, gunakan salah satu opsi berikut:

  • permissions.get dengan fields=role.
  • permissions.get dengan fields=* untuk menampilkan semua kolom permissions.
  • files.get dengan fields=permissions(role) atau fields=permissions/role.
  • files.get dengan fields=permissions untuk menampilkan semua kolom permissions.
  • changes.list dengan fields=changes(file(permissions(role))).

Untuk mengambil beberapa kolom, gunakan daftar yang dipisahkan koma. Misalnya, files.list dengan fields=files(id,name,createdTime,modifiedTime,size).

Untuk menentukan kolom bertingkat dalam array atau objek bertingkat, gunakan tanda kurung bertingkat. Misalnya, untuk mencantumkan file dengan ID, nama, dan detail pemilik bertingkat (nama tampilan dan alamat email) sekaligus mengambil token halaman berikutnya untuk penomoran halaman: files.list dengan fields=nextPageToken,files(id,name,owners(displayName,emailAddress)).

Permintaan

Dalam contoh ini, kami menyediakan parameter jalur ID file dan beberapa kolom, termasuk kolom tertentu dari resource izin bertingkat, sebagai parameter kueri dalam permintaan. Respons menampilkan nilai kolom untuk ID file.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)

Respons

{
  "name": "File1",
  "starred": false,
  "shared": true,
  "permissions": [
    {
      "kind": "drive#permission",
      "type": "user",
      "role": "owner"
    }
  ]
}

Parameter sistem alternatif

Parameter kueri yang berlaku untuk semua operasi Google Drive API didokumentasikan di Parameter Sistem.