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

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

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

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

รูปแบบของพารามิเตอร์ช่องจะเหมือนกับการเข้ารหัส 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
            }
          }
        }
      }
    }
  ]
}