Mask kolom adalah cara bagi pemanggil API untuk mencantumkan kolom yang harus disediakan oleh permintaan kembalikan atau perbarui. Menggunakan FieldMask memungkinkan API menghindari pekerjaan yang tidak perlu dan meningkatkan performa. Mask kolom digunakan untuk metode baca dan update di Google Sheets API.
Membaca dengan mask kolom
{i>Spreadsheet<i} bisa berukuran besar, dan sering kali Anda tidak membutuhkan setiap bagian dari
Spreadsheet
yang ditampilkan oleh permintaan baca. Anda dapat membatasi apa yang ditampilkan
Respons Sheets API, menggunakan parameter URL fields
. Untuk yang terbaik
kinerja,
secara eksplisit mencantumkan hanya kolom yang Anda butuhkan
dalam balasannya.
Format parameter kolom sama dengan Encoding JSON untuk FieldMask. Secara singkat, beberapa {i>field<i} yang berbeda dipisahkan dengan tanda koma dan sub-isian yang dipisahkan titik. Nama kolom dapat ditentukan dalam camelCase atau separated_by_underscores. Untuk memudahkan, beberapa sub-isian dari jenis huruf dapat dicantumkan dalam tanda kurung.
Hal berikut
Permintaan spreadsheets.get
contoh menggunakan mask kolom sheets.properties(sheetId,title,sheetType,gridProperties)
untuk
hanya ambil ID sheet, judul,
SheetType
, dan
GridProperties
dari
SheetProperties
objek di semua sheet dalam spreadsheet:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)
Respons terhadap panggilan metode ini adalah
Spreadsheet
yang berisi komponen yang diminta dalam mask kolom. Perlu diketahui bahwa
sheetType=OBJECT
tidak berisi gridProperties
:
{ "sheets": [ { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 25 } } }, { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "sheetType": "OBJECT" } } ] }
Memperbarui dengan mask kolom
Terkadang Anda hanya perlu memperbarui kolom tertentu dalam sebuah objek sambil tetap mempertahankan
{i>field<i} lainnya tidak berubah. Permintaan pembaruan di dalam
spreadsheets.batchUpdate
menggunakan mask kolom untuk memberi tahu API kolom mana yang sedang diubah. Tujuan
permintaan update akan mengabaikan kolom apa pun yang tidak ditentukan dalam mask kolom,
dan membiarkan mereka dengan
nilai-nilai mereka saat ini.
Anda juga dapat membatalkan setelan kolom dengan tidak menentukannya di pesan yang diperbarui, tetapi menambahkan kolom ke mask. Ini akan menghapus nilai apa pun yang ada di {i>field<i} sebelumnya miliki.
Sintaksis untuk mask kolom update sama dengan mask kolom baca.
Contoh berikut menggunakan
AddSheetRequest
untuk menambahkan sheet baru dengan jenis Grid
, membekukan baris pertama, dan mewarnai baris baru
tab pada {i>sheet<i} merah:
POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate
{ "spreadsheetId": "SPREADSHEET_ID
", "replies": [ { "addSheet": { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "index": 6, "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 26, "frozenRowCount": 1 }, "tabColor": { "red": 0.003921569 }, "tabColorStyle": { "rgbColor": { "red": 0.003921569 } } } } } ] }