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

ฟิลด์มาสก์เป็นวิธีที่ผู้เรียก 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
            }
          }
        }
      }
    }
  ]
}