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

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

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

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

รูปแบบของพารามิเตอร์ฟิลด์จะเหมือนกับ การเข้ารหัส 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
        },
      }
    }
  ],
}