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

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

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

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

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

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

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

अपडेट फ़ील्ड मास्क के सिंटैक्स और पढ़े गए फ़ील्ड मास्क एक ही हैं.

इस उदाहरण में, दस्तावेज़ में "Google Docs API" शब्दों को range 5 से 20 के अंदर बोल्ड के तौर पर स्टाइल करने के लिए, UpdateTextStyleRequest का इस्तेमाल किया गया है:

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"
}