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

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

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

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

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

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

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