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

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

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

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

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

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

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

การตอบสนองต่อการเรียกเมธอดนี้คือออบเจ็กต์ Document ที่มีคอมโพเนนต์ที่ขอในมาสก์ของช่องข้อมูลดังนี้

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

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

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

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

ไวยากรณ์สำหรับมาสก์ของช่องการอัปเดตจะเหมือนกับฟิลด์มาสก์ที่อ่านแล้ว

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

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

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

{
  "title": "TITLE",
  "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
   },
  "revisionId": "REVISION_ID",
  "suggestionsViewMode": "SUGGESTIONS_INLINE",
  "documentId": "DOCUMENT_ID"
}