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 Slides API.

Untuk perbandingan antara apa yang ditampilkan dalam isi respons saat Anda tidak menggunakan maska kolom dan saat Anda menggunakannya, lihat Menggunakan resource sebagian.

Membaca dengan mask kolom

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

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

Contoh permintaan metode presentations.get berikut menggunakan mask kolom slides.pageElements(objectId,size,transform) untuk hanya mengambil ID objek, Size, dan transformasi objek pageElement di semua slide dalam presentasi:

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

Respons untuk panggilan metode ini adalah objek presentations yang berisi komponen yang diminta dalam mask kolom:

{
  "slides": [
    {
      "pageElements": [
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311708,
            "translateY": 744575,
            "unit": "EMU"
          }
        },
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311700,
            "translateY": 2834125,
            "unit": "EMU"
          }
        }
     ]
    }
  ]
}

Memperbarui dengan mask kolom

Terkadang Anda hanya perlu memperbarui kolom tertentu dalam objek tanpa mengubah kolom lainnya. Permintaan pembaruan di dalam metode presentations.batchUpdate menggunakan mask kolom untuk memberi tahu API kolom mana yang diubah. Permintaan update mengabaikan kolom apa pun yang tidak ditentukan dalam 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 metode UpdateShapePropertiesRequest untuk mengubah isi warna bentuk menjadi warna tema DARK1 dan menetapkan ulang garis batas bentuk:

POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate

{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": OBJECT_ID,
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "DARK1"
              }
            }
          }
        },
        "fields": "shapeBackgroundFill.solidFill.color,outline"
      }
    }
  ]
}