มาสก์ของช่องเป็นวิธีให้ผู้เรียกใช้ API แสดงช่องที่คำขอควรส่งคืนหรืออัปเดต การใช้ FieldMask ช่วยให้ API หลีกเลี่ยงงานที่ไม่จำเป็นและปรับปรุงประสิทธิภาพได้ ฟิลด์มาสก์ใช้สำหรับทั้งวิธีการอ่านและอัปเดตใน Google Sheets API
อ่านด้วยฟิลด์มาสก์
สเปรดชีตอาจมีขนาดใหญ่ และโดยมากแล้วคุณไม่ต้องการใช้ทรัพยากร Spreadsheet
ทุกส่วนที่มีคำขอให้อ่าน คุณจะจำกัดสิ่งที่แสดงในคำตอบของชีต API ได้โดยใช้พารามิเตอร์ fields
ของ URL หากต้องการประสิทธิภาพที่ดีที่สุด
ให้แสดงเฉพาะช่องที่คุณต้องการอย่างชัดแจ้งในการตอบกลับ
รูปแบบของพารามิเตอร์ช่องจะเหมือนกับการเข้ารหัส JSON ของ FieldMask กล่าวสั้นๆ คือช่องต่างๆ หลายช่องคั่นด้วยคอมมาและช่องย่อยคั่นด้วยจุด คุณระบุชื่อช่องได้ใน camelCase หรือ Separat_by_underscores เพื่อความสะดวก เราอาจแสดงช่องย่อยหลายช่อง จากประเภทเดียวกันไว้ในวงเล็บ
ตัวอย่างคำขอ spreadsheets.get
ต่อไปนี้ใช้มาสก์ของช่อง sheets.properties(sheetId,title,sheetType,gridProperties)
เพื่อดึงเฉพาะรหัสชีต ชื่อ SheetType
และGridProperties
ของออบเจ็กต์ SheetProperties
ในชีตทั้งหมดในสเปรดชีต
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)
การตอบสนองต่อการเรียกเมธอดนี้คือออบเจ็กต์ Spreadsheet
ที่มีคอมโพเนนต์ที่ขอในมาสก์ของช่อง โปรดทราบว่า sheetType=OBJECT
ไม่มี gridProperties
:
{ "sheets": [ { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 25 } } }, { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "sheetType": "OBJECT" } } ] }
อัปเดตด้วยฟิลด์มาสก์
บางครั้งคุณต้องอัปเดตช่องบางช่องในออบเจ็กต์โดยที่ไม่เปลี่ยนแปลงช่องอื่นๆ อัปเดตคำขอภายในมาสก์ของช่องใช้การดำเนินการของ spreadsheets.batchUpdate
เพื่อบอก API ว่ากำลังมีการเปลี่ยนแปลงช่องใด คำขออัปเดตจะไม่สนใจช่องที่ไม่ได้ระบุไว้ในมาสก์ของช่อง ซึ่งจะปล่อยค่าปัจจุบันไว้ตามเดิม
นอกจากนี้ คุณยังสามารถยกเลิกการตั้งค่าช่องได้โดยไม่ได้ระบุช่องในข้อความที่อัปเดต แต่ให้เพิ่มช่องลงในมาสก์ ซึ่งจะเป็นการล้างค่าของช่อง ที่เคยมีก่อนหน้านี้
ไวยากรณ์สำหรับมาสก์ของช่องการอัปเดตจะเหมือนกับฟิลด์มาสก์ที่อ่านแล้ว
ตัวอย่างต่อไปนี้ใช้ AddSheetRequest
เพื่อเพิ่มชีตใหม่ประเภท Grid
ตรึงแถวแรก และทำให้แท็บของชีตใหม่เป็นสีแดง
POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate
{ "spreadsheetId": "SPREADSHEET_ID
", "replies": [ { "addSheet": { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "index": 6, "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 26, "frozenRowCount": 1 }, "tabColor": { "red": 0.003921569 }, "tabColorStyle": { "rgbColor": { "red": 0.003921569 } } } } } ] }