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

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

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

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

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