ใช้มาสก์ช่อง

ฟิลด์มาสก์เป็นวิธีให้ผู้เรียก API แสดงรายการฟิลด์ที่คำขอควรแสดงผลหรืออัปเดต การใช้ FieldMask ช่วยให้ API หลีกเลี่ยงการทำงานที่ไม่จำเป็นและปรับปรุงประสิทธิภาพ ระบบจะใช้ฟิลด์มาสก์สำหรับทั้งเมธอดอ่านและอัปเดตใน Google Sheets API

อ่านด้วยฟิลด์มาสก์

สเปรดชีตอาจมีขนาดใหญ่ และบ่อยครั้งที่คุณไม่จำเป็นต้องใช้ทุกส่วนของ Spreadsheet ที่คำขออ่านแสดงผล คุณสามารถจำกัดสิ่งที่แสดงผลในการตอบกลับของ Sheets API ได้โดยใช้พารามิเตอร์ URL fields เพื่อประสิทธิภาพที่ดีที่สุด ให้ระบุเฉพาะฟิลด์ที่ต้องการ ในคำตอบอย่างชัดเจน

รูปแบบของพารามิเตอร์ fields จะเหมือนกับการเข้ารหัส JSON ของ FieldMask กล่าวโดยย่อคือ ฟิลด์ต่างๆ จะที่คั่นด้วยคอมมา และฟิลด์ย่อยจะคั่นด้วยจุด คุณสามารถระบุชื่อฟิลด์ในรูปแบบ camelCase หรือ separated_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"
      }
    }
  ]
}

อัปเดตด้วยฟิลด์มาสก์

บางครั้งคุณต้องอัปเดตเฉพาะบางฟิลด์ในออบเจ็กต์โดยไม่เปลี่ยนแปลงฟิลด์อื่นๆ คำขออัปเดตภายในa 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
            }
          }
        }
      }
    }
  ]
}