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

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

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

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

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

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

ตัวอย่างต่อไปนี้ใช้ 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
        },
      }
    }
  ],
}