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

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

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

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

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

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

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

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

การตอบกลับการเรียกใช้เมธอดนี้คือออบเจ็กต์ presentations ที่มีคอมโพเนนต์ที่ขอใน Field Mask

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