Menggunakan mask kolom

Mask kolom adalah cara bagi pemanggil API untuk mencantumkan kolom yang harus ditampilkan atau diperbarui oleh permintaan. Penggunaan 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

Spreadsheet bisa berukuran besar, dan sering kali Anda tidak memerlukan setiap bagian dari Spreadsheet resource yang ditampilkan oleh permintaan baca. Anda dapat membatasi apa yang ditampilkan dalam respons Sheets API, menggunakan parameter URL fields. Untuk mendapatkan performa terbaik, cantumkan secara eksplisit hanya kolom yang Anda perlukan dalam balasan.

Format parameter kolom sama dengan encoding JSON dari FieldMask. Singkatnya, beberapa kolom yang berbeda dipisahkan dengan koma dan sub-kolom dipisahkan dengan titik. Nama kolom dapat ditentukan dalam camelCase atau separated_by_underscores. Untuk memudahkan, beberapa sub-kolom dari jenis yang sama dapat dicantumkan dalam tanda kurung.

Contoh permintaan spreadsheets.get berikut menggunakan mask kolom sheets.properties(sheetId,title,sheetType,gridProperties) untuk mengambil hanya ID, judul, SheetType, dan GridProperties objek SheetProperties 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 objek Spreadsheet yang berisi komponen yang diminta dalam mask kolom. Perhatikan 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 objek dan tidak mengubah kolom lainnya. Permintaan update dalam operasi spreadsheets.batchUpdate menggunakan mask kolom untuk memberi tahu API kolom mana yang diubah. Permintaan update mengabaikan kolom apa pun yang tidak ditentukan di mask kolom, sehingga nilai saat ini tidak berubah.

Anda juga dapat menghapus setelan kolom dengan tidak menentukannya dalam pesan yang diperbarui, tetapi menambahkan kolom ke mask. Tindakan ini akan menghapus nilai apa pun yang sebelumnya dimiliki kolom.

Sintaksis untuk mask kolom update sama dengan mask kolom baca.

Contoh berikut menggunakan AddSheetRequest untuk menambahkan sheet baru berjenis Grid, membekukan baris pertama, dan mewarnai tab sheet baru menjadi 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
            }
          }
        }
      }
    }
  ]
}