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

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

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

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

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

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

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

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"
      }
    }
  ]
}