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

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

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

ไฟล์นำเสนออาจมีขนาดใหญ่ และบ่อยครั้งที่คุณไม่จำเป็นต้องใช้ทรัพยากรPresentationทั้งหมดที่แสดงผลโดยคำขออ่าน คุณจำกัดสิ่งที่จะแสดงในคำตอบของ Slides API ได้โดยใช้พารามิเตอร์ของ URL 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)

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

{
  "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 ว่าฟิลด์ใดมีการเปลี่ยนแปลง คำขออัปเดตจะไม่สนใจช่องที่ไม่ได้ระบุไว้ในมาสก์ฟิลด์ โดยช่องเหล่านั้นจะยังคงมีค่าปัจจุบัน

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

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

ระบบจะถือว่ามาสก์ฟิลด์ * เป็นไวลด์การ์ด และเป็นอักษรย่อสำหรับการระบุทุกช่องในข้อความ ไวยากรณ์ไวลด์การ์ดอาจให้ผลลัพธ์ที่ไม่ต้องการหากมีการอัปเดต 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"
      }
    }
  ]
}