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

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

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

สเปรดชีตอาจมีขนาดใหญ่ และคุณไม่จำเป็นต้องมีส่วนของทรัพยากร Spreadsheet ที่ส่งคืนมาจากคำขออ่าน คุณจำกัดสิ่งที่แสดงผลในคำตอบของชีต API ได้โดยใช้พารามิเตอร์ของ URL fields เพื่อประสิทธิภาพที่ดีที่สุด ให้แสดงเฉพาะช่องที่จำเป็นอย่างชัดเจนในการตอบกลับ

รูปแบบของพารามิเตอร์ช่องจะเหมือนกับการเข้ารหัส JSON ของ FieldMask เราขออธิบายสั้นๆ ว่าช่องต่างๆ หลายช่องมีการคั่นด้วยคอมมา และช่องย่อยจะคั่นด้วยจุด ชื่อช่องระบุได้ใน camelCase หรือ Separat_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
            }
          }
        }
      }
    }
  ]
}