มาสก์ของช่องเป็นวิธีให้ผู้เรียกใช้ API แสดงช่องที่คำขอควรส่งคืนหรืออัปเดต การใช้ FieldMask ช่วยให้ API หลีกเลี่ยงงานที่ไม่จำเป็นและปรับปรุงประสิทธิภาพได้ ฟิลด์มาสก์ใช้สำหรับทั้งวิธีการอ่านและอัปเดตใน API ของ Google สไลด์
อ่านด้วยฟิลด์มาสก์
งานนำเสนออาจมีขนาดใหญ่ และบ่อยครั้งที่คุณไม่จำเป็นต้องใช้ทรัพยากร Presentation
ทุกส่วนที่ส่งกลับมาตามคำขอให้อ่าน คุณจำกัดสิ่งที่แสดงผลในการตอบกลับ Slides API ได้โดยใช้พารามิเตอร์ของ URL fields
หากต้องการประสิทธิภาพที่ดีที่สุด
ให้แสดงเฉพาะช่องที่คุณต้องการอย่างชัดแจ้งในการตอบกลับ
รูปแบบของพารามิเตอร์ช่องจะเหมือนกับการเข้ารหัส JSON ของ FieldMask กล่าวสั้นๆ คือช่องต่างๆ หลายช่องคั่นด้วยคอมมาและช่องย่อยคั่นด้วยจุด คุณระบุชื่อช่องได้ใน camelCase หรือ Separat_by_underscores เพื่อความสะดวก เราอาจแสดงช่องย่อยหลายช่อง จากประเภทเดียวกันไว้ในวงเล็บ
ตัวอย่างคำขอ presentations.get
ต่อไปนี้ใช้มาสก์ช่องของ slides.pageElements(objectId,size,transform)
เพื่อดึงข้อมูลเฉพาะรหัสออบเจ็กต์ Size
และการเปลี่ยนรูปแบบของออบเจ็กต์ pageElement
ในสไลด์ทั้งหมดในงานนำเสนอ
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
การตอบสนองต่อการเรียกเมธอดนี้คือออบเจ็กต์ Presentation
ที่มีคอมโพเนนต์ที่ขอในมาสก์ของช่องข้อมูลดังนี้
{ "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" } } ] } ] }
อัปเดตด้วยฟิลด์มาสก์
บางครั้งคุณต้องอัปเดตช่องบางช่องในออบเจ็กต์โดยที่ไม่เปลี่ยนแปลงช่องอื่นๆ อัปเดตคำขอภายในมาสก์ของช่องใช้การดำเนินการของ presentations.batchUpdate
เพื่อบอก API ว่ากำลังมีการเปลี่ยนแปลงช่องใด คำขออัปเดตจะไม่สนใจช่องที่ไม่ได้ระบุไว้ในมาสก์ของช่อง ซึ่งจะปล่อยค่าปัจจุบันไว้ตามเดิม
นอกจากนี้ คุณยังสามารถยกเลิกการตั้งค่าช่องได้โดยไม่ได้ระบุช่องในข้อความที่อัปเดต แต่ให้เพิ่มช่องลงในมาสก์ ซึ่งจะเป็นการล้างค่าของช่อง ที่เคยมีก่อนหน้านี้
ไวยากรณ์สำหรับมาสก์ของช่องการอัปเดตจะเหมือนกับฟิลด์มาสก์ที่อ่านแล้ว
ตัวอย่างต่อไปนี้ใช้ UpdateShapePropertiesRequest
เพื่อเปลี่ยนการเติมสีของรูปร่างเป็นสีธีม DARK1
และยกเลิกการตั้งค่าโครงร่างของรูปร่าง
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"
}
}
]
}