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

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

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

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

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