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

มาสก์ช่องเป็นวิธีสำหรับการเรียก 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
            }
          }
        }
      }
    }
  ]
}