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 dapat berukuran besar, dan sering kali Anda tidak memerlukan setiap bagian resource Document
yang ditampilkan oleh permintaan baca. Anda dapat membatasi apa yang ditampilkan dalam respons Docs API, menggunakan parameter URL fields
. Untuk mendapatkan performa
terbaik,
cantumkan secara eksplisit kolom yang Anda perlukan
dalam balasan secara eksplisit.
Format parameter kolom sama dengan encoding JSON untuk FieldMask. Singkatnya, beberapa kolom yang berbeda dipisahkan dengan koma, sedangkan subkolomnya dipisahkan dengan 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 documents.get
berikut menggunakan mask kolom title,body.content(paragraph),revisionId
untuk mengambil title
dokumen, Paragraph
objek Body
, dan revisionId
dokumen dalam dokumen:
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,body.content(paragraph),revisionId
Respons terhadap panggilan metode ini adalah
objek Document
yang berisi komponen yang diminta di mask kolom:
{ "title": ""TITLE
", "body": { "content": [ {}, { "paragraph": { "elements": [ { "startIndex": 1, "endIndex": 59, "textRun": { "content": ""CONTENT
", "textStyle": {} } } ], "paragraphStyle": { "namedStyleType": "NORMAL_TEXT", "direction": "LEFT_TO_RIGHT" } } } ] }, "revisionId": "REVISION_ID
" }
Mengupdate dengan mask kolom
Terkadang, Anda hanya perlu memperbarui kolom tertentu dalam suatu objek tanpa mengubah kolom lain. 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 dalam mask kolom, sehingga nilai saat ini tetap sama.
Anda juga dapat membatalkan penetapan kolom dengan tidak menentukannya dalam pesan yang diperbarui, tetapi menambahkan kolom ke mask. Ini akan menghapus nilai yang sebelumnya dimiliki kolom tersebut.
Sintaksis untuk mask kolom update sama dengan mask kolom baca.
Contoh berikut menggunakan
UpdateTextStyleRequest
untuk menata gaya kata "Google Docs API" dalam dokumen menjadi tebal dalam range
5–20:
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{ "title": "TITLE
", "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 }, "revisionId": "REVISION_ID
", "suggestionsViewMode": "SUGGESTIONS_INLINE", "documentId": "DOCUMENT_ID
" }