Menggunakan mask kolom

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.

Mask kolom * diperlakukan sebagai karakter pengganti dan merupakan singkatan untuk menentukan setiap {i>field<i} dalam pesan. Sintaksis karakter pengganti dapat memberikan hasil yang tidak diinginkan jika API diupdate di masa mendatang, karena hanya dan kolom yang baru ditambahkan dapat menyebabkan error. Untuk aplikasi produksi, selalu mencantumkan kolom tertentu yang diperbarui di mask kolom dan hindari penggunaan * karakter pengganti.

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
            }
          }
        }
      }
    }
  ]
}