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

फ़ील्ड मास्क, एपीआई कॉल करने वालों के लिए एक ऐसा तरीका है जिससे वे उन फ़ील्ड की सूची बना सकते हैं जिन्हें अनुरोध को वापस भेजना या अपडेट करना चाहिए. 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
            }
          }
        }
      }
    }
  ]
}