Menggunakan mask kolom

Mask kolom adalah cara bagi pemanggil API untuk mencantumkan kolom yang harus ditampilkan atau diperbarui oleh permintaan. Dengan menggunakan FieldMask, API dapat menghindari pekerjaan yang tidak perlu dan meningkatkan performa. Mask kolom digunakan untuk metode baca dan update di Google Slides API.

Membaca dengan mask kolom

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

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

Contoh permintaan presentations.get berikut menggunakan mask kolom slides.pageElements(objectId,size,transform) untuk mengambil hanya 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 terhadap panggilan metode ini adalah objek Presentation yang berisi komponen yang diminta di 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 mengupdate kolom tertentu dalam objek sambil mempertahankan kolom lainnya. Permintaan pembaruan di dalam operasi 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 membatalkan setelan kolom dengan tidak menetapkannya di pesan yang diupdate, tetapi menambahkan kolom ke mask. Tindakan ini akan menghapus nilai apa pun yang sebelumnya ada di kolom.

Sintaksis untuk mask kolom update sama dengan mask kolom baca.

Mask kolom * diperlakukan seperti karakter pengganti dan merupakan singkatan untuk menentukan setiap kolom dalam pesan. Sintaksis karakter pengganti dapat menghasilkan hasil yang tidak diinginkan jika API diupdate pada masa mendatang, karena kolom hanya baca dan kolom yang baru ditambahkan dapat menyebabkan error. Untuk aplikasi produksi, selalu cantumkan kolom tertentu yang sedang diperbarui di mask kolom dan hindari penggunaan karakter pengganti *.

Contoh berikut menggunakan UpdateShapePropertiesRequest untuk mengubah isian warna bentuk menjadi warna tema DARK1 dan membatalkan setelan 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"
      }
    }
  ]
}