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

Membaca dengan mask kolom

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

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

Contoh permintaan documents.get berikut menggunakan mask kolom title,tabs(documentTab(body.content(paragraph))),revisionId untuk mengambil title dokumen, Paragraph objek Body (dari semua tab), dan revisionId dokumen dalam dokumen:

GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(body.content(paragraph))),revisionId

Respons terhadap panggilan metode ini adalah Document objek yang berisi komponen yang diminta dalam mask kolom:

{
  "title": "TITLE",
  "revisionId": "REVISION_ID",
  "tabs": [
    {
      "documentTab": {
        "body": {
          "content": [
            {},
            {
              "paragraph": {
                "elements": [
                  {
                    "startIndex": 1,
                    "endIndex": 59,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  }
                ],
                "paragraphStyle": {
                  "namedStyleType": "NORMAL_TEXT",
                  "direction": "LEFT_TO_RIGHT"
                }
              }
            }
          ]
        }
      }
    }
  ]
}

Memperbarui dengan mask kolom

Terkadang Anda hanya perlu memperbarui kolom tertentu dalam objek dan tidak mengubah kolom lainnya. Permintaan update di dalam operasi documents.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 membatalkan 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 tersebut.

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 diperbarui di masa mendatang, karena kolom hanya baca dan kolom yang baru ditambahkan dapat menyebabkan error. Untuk aplikasi produksi, selalu cantumkan kolom tertentu yang diperbarui dalam mask kolom dan hindari penggunaan karakter pengganti *.

Contoh berikut menggunakan UpdateTextStyleRequest untuk menata gaya kata "Google Docs API" dalam dokumen sebagai tebal dalam range 5–20:

POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate

{
  "title": "TITLE",
  "revisionId": "REVISION_ID",
  "suggestionsViewMode": "SUGGESTIONS_INLINE",
  "documentId": "DOCUMENT_ID",
  "tabs": [
    {
      "documentTab": {
        "body": {
          "content": [
            {
              "endIndex": 1,
              "sectionBreak": {
                "sectionStyle": {
                  "columnSeparatorStyle": "NONE",
                  "contentDirection": "LEFT_TO_RIGHT",
                  "sectionType": "CONTINUOUS"
                }
              }
            },
            {
              "startIndex": 1,
              "endIndex": 59,
              "paragraph": {
                "elements": [
                  {
                    "startIndex": 1,
                    "endIndex": 5,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  },
                  {
                    "startIndex": 5,
                    "endIndex": 20,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {
                        "bold": true
                      }
                    }
                  },
                  {
                    "startIndex": 20,
                    "endIndex": 59,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  }
                ],
                "paragraphStyle": {
                  "namedStyleType": "NORMAL_TEXT",
                  "direction": "LEFT_TO_RIGHT"
                }
              }
            }
          ]
        },
        {
          ... // style details
        },
      }
    }
  ],
}