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

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

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

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

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

अनुरोध के इस उदाहरण में, spreadsheets.get फ़ील्ड मास्क के तौर पर sheets.properties(sheetId,title,sheetType,gridProperties) का इस्तेमाल किया गया है. इससे, स्प्रेडशीट की सभी शीट के SheetProperties ऑब्जेक्ट का सिर्फ़ शीट आईडी, टाइटल, SheetType, और GridProperties फ़ेच किया जाता है:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)

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

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "TITLE",
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 1000,
          "columnCount": 25
        }
      }
    },
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "TITLE",
        "sheetType": "OBJECT"
      }
    }
  ]
}

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

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

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

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

यहां दिए गए उदाहरण में, AddSheetRequest का इस्तेमाल करके, Grid टाइप की नई शीट जोड़ी गई है. साथ ही, पहली लाइन को फ़्रीज़ किया गया है और नई शीट के टैब को लाल रंग दिया गया है:

POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate

{
  "spreadsheetId": "SPREADSHEET_ID",
  "replies": [
    {
      "addSheet": {
        "properties": {
          "sheetId": SHEET_ID,
          "title": "TITLE",
          "index": 6,
          "sheetType": "GRID",
          "gridProperties": {
            "rowCount": 1000,
            "columnCount": 26,
            "frozenRowCount": 1
          },
          "tabColor": {
            "red": 0.003921569
          },
          "tabColorStyle": {
            "rgbColor": {
              "red": 0.003921569
            }
          }
        }
      }
    }
  ]
}