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

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

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

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

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

ตัวอย่างคำขอ documents.getต่อไปนี้ใช้ฟิลด์มาสก์title,tabs(documentTab(body.content(paragraph))),revisionId เพื่อดึงข้อมูลtitleของเอกสาร,Paragraph ของออบเจ็กต์Body (จากแท็บทั้งหมด) และrevisionIdของเอกสารภายในเอกสาร

GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(body.content(paragraph))),revisionId

การตอบกลับการเรียกเมธอดนี้จะเป็น Document ออบเจ็กต์ที่มีคอมโพเนนต์ที่ขอในฟิลด์มาสก์

{
  "title": "TITLE",
  "revisionId": "REVISION_ID",
  "tabs": [
    {
      "documentTab": {
        "body": {
          "content": [
            {},
            {
              "paragraph": {
                "elements": [
                  {
                    "startIndex": 1,
                    "endIndex": 59,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  }
                ],
                "paragraphStyle": {
                  "namedStyleType": "NORMAL_TEXT",
                  "direction": "LEFT_TO_RIGHT"
                }
              }
            }
          ]
        }
      }
    }
  ]
}

อัปเดตด้วยฟิลด์มาสก์

บางครั้งคุณต้องอัปเดตเฉพาะบางฟิลด์ในออบเจ็กต์โดยไม่เปลี่ยนแปลงฟิลด์อื่นๆ คำขออัปเดตภายใน documents.batchUpdate การดำเนินการจะใช้ฟิลด์มาสก์เพื่อบอก API ว่าฟิลด์ใดมีการเปลี่ยนแปลง คำขออัปเดตจะละเว้นฟิลด์ที่ไม่ได้ระบุไว้ในฟิลด์มาสก์ โดยจะคงค่าปัจจุบันของฟิลด์เหล่านั้นไว้

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

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

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

ตัวอย่างต่อไปนี้ใช้ UpdateTextStyleRequest เพื่อจัดรูปแบบคำว่า "Google Docs API" ในเอกสารเป็นตัวหนาภายใน range 5–20

POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate

{
  "title": "TITLE",
  "revisionId": "REVISION_ID",
  "suggestionsViewMode": "SUGGESTIONS_INLINE",
  "documentId": "DOCUMENT_ID",
  "tabs": [
    {
      "documentTab": {
        "body": {
          "content": [
            {
              "endIndex": 1,
              "sectionBreak": {
                "sectionStyle": {
                  "columnSeparatorStyle": "NONE",
                  "contentDirection": "LEFT_TO_RIGHT",
                  "sectionType": "CONTINUOUS"
                }
              }
            },
            {
              "startIndex": 1,
              "endIndex": 59,
              "paragraph": {
                "elements": [
                  {
                    "startIndex": 1,
                    "endIndex": 5,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  },
                  {
                    "startIndex": 5,
                    "endIndex": 20,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {
                        "bold": true
                      }
                    }
                  },
                  {
                    "startIndex": 20,
                    "endIndex": 59,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  }
                ],
                "paragraphStyle": {
                  "namedStyleType": "NORMAL_TEXT",
                  "direction": "LEFT_TO_RIGHT"
                }
              }
            }
          ]
        },
        {
          ... // style details
        },
      }
    }
  ],
}