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

มาสก์ของช่องเป็นวิธีให้ผู้เรียกใช้ 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"
      }
    }
  ]
}