फ़ील्ड मास्क का इस्तेमाल करना

फ़ील्ड मास्क, एपीआई कॉल करने वालों के लिए एक ऐसा तरीका है जिससे वे उन फ़ील्ड की सूची बना सकते हैं जिन्हें अनुरोध को वापस भेजना या अपडेट करना चाहिए. FieldMask का इस्तेमाल करने से, एपीआई को बेवजह काम करने से रोका जा सकता है और परफ़ॉर्मेंस को बेहतर बनाया जा सकता है. Google Docs API में, फ़ील्ड मास्क का इस्तेमाल पढ़ने और अपडेट करने, दोनों तरीकों के लिए किया जाता है.

फ़ील्ड मास्क के साथ पढ़ना

दस्तावेज़ बड़े हो सकते हैं. साथ ही, अक्सर आपको पढ़ने के अनुरोध से मिले Document संसाधन के हर हिस्से की ज़रूरत नहीं होती. fields यूआरएल पैरामीटर का इस्तेमाल करके, यह तय किया जा सकता है कि Docs API के जवाब में क्या-क्या शामिल किया जाए. बेहतर परफ़ॉर्मेंस के लिए, जवाब में सिर्फ़ उन फ़ील्ड को साफ़ तौर पर शामिल करें जिनकी आपको ज़रूरत है.

fields पैरामीटर का फ़ॉर्मैट, FieldMask के JSON एन्कोडिंग के जैसा ही होता है. संक्षेप में कहें, तो अलग-अलग फ़ील्ड को कॉमा से अलग किया जाता है और सब-फ़ील्ड को बिंदु से अलग किया जाता है. फ़ील्ड के नाम, camelCase या separated_by_underscores में दिए जा सकते हैं. सुविधा के लिए, एक ही तरह के कई सब-फ़ील्ड को ब्रैकेट में लिस्ट किया जा सकता है.

documents.get के अनुरोध का यह उदाहरण, दस्तावेज़ के title, Body ऑब्जेक्ट (सभी टैब से) के Paragraph, और दस्तावेज़ में मौजूद revisionId को फ़ेच करने के लिए, title,tabs(documentTab(body.content(paragraph))),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 ऑपरेशन में अपडेट के अनुरोधों के लिए, फ़ील्ड मास्क का इस्तेमाल किया जाता है. इससे एपीआई को यह पता चलता है कि किन फ़ील्ड में बदलाव किया जा रहा है. अपडेट करने का अनुरोध, फ़ील्ड मास्क में शामिल नहीं किए गए फ़ील्ड को अनदेखा करता है. इसलिए, उनकी मौजूदा वैल्यू में कोई बदलाव नहीं होता.

अपडेट किए गए मैसेज में किसी फ़ील्ड को शामिल न करके भी, उसे अनसेट किया जा सकता है. हालांकि, इसके लिए फ़ील्ड को मास्क में जोड़ना होगा. इससे फ़ील्ड में पहले से मौजूद वैल्यू हट जाती है.

अपडेट फ़ील्ड मास्क का सिंटैक्स, रीड फ़ील्ड मास्क के सिंटैक्स जैसा ही होता है.

का इस्तेमाल न करें.

यहां दिए गए उदाहरण में, दस्तावेज़ में "Google Docs API" शब्दों को बोल्ड के तौर पर स्टाइल करने के लिए, UpdateTextStyleRequest का इस्तेमाल किया गया है. ऐसा 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
        },
      }
    }
  ],
}