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

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

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

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

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

नीचे दिए गए 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
            }
          }
        }
      }
    }
  ]
}