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

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

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

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

รูปแบบของพารามิเตอร์ฟิลด์จะเหมือนกับการเข้ารหัส 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"
      }
    }
  ]
}

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

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