Menampilkan kolom spesifik

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

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 akhirnya membantu menghindari waktu pemrosesan yang tidak perlu.

Secara default, server menampilkan kumpulan kolom yang spesifik untuk resource yang di-kueri. Misalnya, metode get() pada resource files mungkin hanya menampilkan id, name, dan mimeType. Metode get() pada resource permissions menampilkan kumpulan kolom default yang berbeda.

Setelah server memproses permintaan valid yang menyertakan parameter fields, server akan menampilkan kode status HTTP 200 OK, beserta data yang diminta. Jika parameter kolom mengalami error atau tidak valid, server akan menampilkan kode status HTTP 400 Bad Request, beserta pesan error yang menyatakan masalah pada 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.

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 disusun bertingkat dalam kolom a, seperti 'capabilities/canDownload'. Untuk mengetahui informasi selengkapnya, lihat Mengambil kolom resource bertingkat.

  • Gunakan sub-pemilih 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 negatif pada performa permintaan.

Tampilkan contoh

Permintaan

Dalam contoh ini, kami memberikan 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

Saat kolom merujuk ke resource lain, Anda dapat menentukan kolom resource bertingkat mana yang akan 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).

Tampilkan contoh

Permintaan

Dalam contoh ini, kami memberikan 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"
    }
  ]
}