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

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

अगर आपको यह जानना है कि फ़ील्ड मास्क का इस्तेमाल न करने पर, जवाब के मुख्य हिस्से में क्या दिखता है और इस्तेमाल करने पर क्या दिखता है, तो आंशिक संसाधनों के साथ काम करना लेख पढ़ें.

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

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

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

नीचे दिए गए presentations.get मेथड के अनुरोध के उदाहरण में, slides.pageElements(objectId,size,transform) फ़ील्ड मास्क का इस्तेमाल किया गया है. इससे सिर्फ़ ऑब्जेक्ट आईडी, Size, और transform को फ़ेच किया जा सकता है. यह किसी प्रज़ेंटेशन की सभी स्लाइड पर मौजूद pageElement ऑब्जेक्ट के लिए किया जाता है:

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

इस तरीके के कॉल का जवाब, presentations ऑब्जेक्ट होता है. इसमें फ़ील्ड मास्क में अनुरोध किए गए कॉम्पोनेंट शामिल होते हैं:

{
  "slides": [
    {
      "pageElements": [
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311708,
            "translateY": 744575,
            "unit": "EMU"
          }
        },
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311700,
            "translateY": 2834125,
            "unit": "EMU"
          }
        }
     ]
    }
  ]
}

फ़ील्ड मास्क की मदद से अपडेट करना

कभी-कभी, आपको किसी ऑब्जेक्ट के सिर्फ़ कुछ फ़ील्ड अपडेट करने होते हैं. वहीं, अन्य फ़ील्ड में कोई बदलाव नहीं करना होता. presentations.batchUpdate तरीके में अपडेट के अनुरोध, फ़ील्ड मास्क का इस्तेमाल करके एपीआई को यह बताते हैं कि किन फ़ील्ड में बदलाव किया जा रहा है. अपडेट करने का अनुरोध, फ़ील्ड मास्क में शामिल नहीं किए गए फ़ील्ड को अनदेखा करता है. इसलिए, उनकी वैल्यू में कोई बदलाव नहीं होता.

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

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

यहां दिए गए उदाहरण में, किसी शेप में भरे गए रंग को DARK1 थीम के रंग में बदलने के लिए, UpdateShapePropertiesRequest तरीके का इस्तेमाल किया गया है. साथ ही, शेप की आउटलाइन को अनसेट किया गया है:

POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate

{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": OBJECT_ID,
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "DARK1"
              }
            }
          }
        },
        "fields": "shapeBackgroundFill.solidFill.color,outline"
      }
    }
  ]
}