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

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

อ่านโดยใช้มาสก์ฟิลด์

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

รูปแบบของพารามิเตอร์ช่องจะเหมือนกับการเข้ารหัส JSON ของ FieldMask กล่าวโดยสรุปคือช่องต่างๆ มีหลายช่องคั่นด้วยคอมมาและช่องย่อยคั่นด้วยจุด คุณระบุชื่อช่องได้ใน camelCase หรือ Separat_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"
      }
    }
  ]
}