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

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

ดูการเปรียบเทียบสิ่งที่แสดงในเนื้อหาการตอบกลับเมื่อคุณไม่ได้ใช้มาสก์ฟิลด์กับเมื่อใช้มาสก์ฟิลด์ได้ที่การทํางานกับทรัพยากรบางส่วน

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

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

รูปแบบของพารามิเตอร์ฟิลด์เหมือนกับการเข้ารหัส JSON ของ FieldMask กล่าวโดยย่อคือ ช่องต่างๆ หลายช่องจะคั่นด้วยคอมมา และช่องย่อยจะคั่นด้วยจุด คุณสามารถระบุชื่อช่องเป็น camelCase หรือ separated_by_underscores คุณสามารถใส่ช่องย่อยหลายช่องจากประเภทเดียวกันไว้ในวงเล็บเพื่อความสะดวก

ตัวอย่างคำขอเมธอดต่อไปนี้ใช้มาสก์ฟิลด์ของ slides.pageElements(objectId,size,transform) เพื่อดึงข้อมูลเฉพาะรหัสออบเจ็กต์ Size และ เปลี่ยนรูปแบบ ออบเจ็กต์ pageElement ในสไลด์ทั้งหมดในงานนำเสนอpresentations.get

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

การตอบสนองต่อการเรียกใช้เมธอดนี้คือออบเจ็กต์ presentations ซึ่งมีคอมโพเนนต์ที่ขอในมาสก์ฟิลด์ ดังนี้

{
  "slides": [
    {
      "pageElements": [
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311708,
            "translateY": 744575,
            "unit": "EMU"
          }
        },
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311700,
            "translateY": 2834125,
            "unit": "EMU"
          }
        }
     ]
    }
  ]
}

อัปเดตด้วยมาสก์ช่อง

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

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

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

ตัวอย่างต่อไปนี้ใช้เมธอด UpdateShapePropertiesRequest เพื่อเปลี่ยนสีเติมของรูปร่างเป็นสีธีม DARK1 และยกเลิกการตั้งค่าเส้นขอบของรูปร่าง

POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate
 
{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": OBJECT_ID,
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "DARK1"
              }
            }
          }
        },
        "fields": "shapeBackgroundFill.solidFill.color,outline"
      }
    }
  ]
}