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

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

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

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

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

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

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

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