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

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

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

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

फ़ील्ड पैरामीटर का फ़ॉर्मैट, FieldMask की JSON एन्कोडिंग की तरह ही होता है. कम शब्दों में, कई अलग-अलग फ़ील्ड को कॉमा लगाकर अलग किया जाता है और सबफ़ील्ड को बिंदु से अलग किया जाता है. फ़ील्ड के नाम camelCase या Separate_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)

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

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