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

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

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

สเปรดชีตอาจมีขนาดใหญ่ และในหลายๆ ครั้งคุณก็ไม่จำเป็นต้องใช้ทุกส่วนของ Spreadsheet ทรัพยากรที่คำขออ่านส่งคืน คุณจำกัดสิ่งที่แสดงผลในคำตอบของ Sheets API ได้โดยใช้พารามิเตอร์ของ URL 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"
      }
    }
  ]
}

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

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