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

มาสก์ฟิลด์เป็นวิธีที่ผู้เรียกใช้ 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 ว่าช่องใดมีการเปลี่ยนแปลง คำขออัปเดตจะละเว้นฟิลด์ที่ไม่ได้ระบุในฟิลด์มาสก์ และคงค่าปัจจุบันไว้

นอกจากนี้ คุณยังยกเลิกการตั้งค่าฟิลด์ได้โดยไม่ระบุฟิลด์ในข้อความที่อัปเดต แต่ เพิ่มฟิลด์ลงในมาสก์ ซึ่งจะล้างค่าใดก็ตามที่ฟิลด์มีอยู่ก่อนหน้านี้

ไวยากรณ์สำหรับมาสก์ฟิลด์การอัปเดตจะเหมือนกับมาสก์ฟิลด์การอ่าน

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