มาสก์ของช่องเป็นวิธีให้ผู้เรียกใช้ API แสดงช่องที่คำขอควรส่งคืนหรืออัปเดต การใช้ FieldMask ช่วยให้ API หลีกเลี่ยงงานที่ไม่จำเป็นและปรับปรุงประสิทธิภาพได้ ฟิลด์มาสก์ใช้สำหรับทั้งวิธีการอ่านและอัปเดตใน Google เอกสาร API
อ่านด้วยฟิลด์มาสก์
เอกสารอาจมีขนาดใหญ่ และบ่อยครั้งที่คุณไม่จำเป็นต้องใช้ทรัพยากร Document
ทุกส่วนที่ส่งกลับมาตามคำขอให้อ่าน คุณจำกัดสิ่งที่แสดงผลในการตอบกลับ Docs API ได้โดยใช้พารามิเตอร์ของ URL fields
หากต้องการประสิทธิภาพที่ดีที่สุด
ให้แสดงเฉพาะช่องที่คุณต้องการอย่างชัดแจ้งในการตอบกลับ
รูปแบบของพารามิเตอร์ช่องจะเหมือนกับการเข้ารหัส JSON ของ FieldMask กล่าวสั้นๆ คือช่องต่างๆ หลายช่องคั่นด้วยคอมมาและช่องย่อยคั่นด้วยจุด คุณระบุชื่อช่องได้ใน camelCase หรือ Separat_by_underscores เพื่อความสะดวก เราอาจแสดงช่องย่อยหลายช่อง จากประเภทเดียวกันไว้ในวงเล็บ
ตัวอย่างคำขอ documents.get
ต่อไปนี้ใช้มาสก์ของช่อง title,body.content(paragraph),revisionId
เพื่อดึงข้อมูล title
ของเอกสาร, Paragraph
ของออบเจ็กต์ Body
และ revisionId
ของเอกสารภายในเอกสาร
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,body.content(paragraph),revisionId
การตอบสนองต่อการเรียกเมธอดนี้คือออบเจ็กต์ Document
ที่มีคอมโพเนนต์ที่ขอในมาสก์ของช่องข้อมูลดังนี้
{ "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
" }
อัปเดตด้วยฟิลด์มาสก์
บางครั้งคุณต้องอัปเดตช่องบางช่องในออบเจ็กต์โดยที่ไม่เปลี่ยนแปลงช่องอื่นๆ อัปเดตคำขอภายในมาสก์ของช่องใช้การดำเนินการของ documents.batchUpdate
เพื่อบอก API ว่ากำลังมีการเปลี่ยนแปลงช่องใด คำขออัปเดตจะไม่สนใจช่องที่ไม่ได้ระบุไว้ในมาสก์ของช่อง ซึ่งจะปล่อยค่าปัจจุบันไว้ตามเดิม
นอกจากนี้ คุณยังสามารถยกเลิกการตั้งค่าช่องได้โดยไม่ได้ระบุช่องในข้อความที่อัปเดต แต่ให้เพิ่มช่องลงในมาสก์ ซึ่งจะเป็นการล้างค่าของช่อง ที่เคยมีก่อนหน้านี้
ไวยากรณ์สำหรับมาสก์ของช่องการอัปเดตจะเหมือนกับฟิลด์มาสก์ที่อ่านแล้ว
ตัวอย่างต่อไปนี้ใช้ UpdateTextStyleRequest
เพื่อจัดรูปแบบคำว่า "Google เอกสาร API" ในเอกสารให้เป็นตัวหนาภายใน 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
" }