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

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