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

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

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

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

फ़ील्ड पैरामीटर का फ़ॉर्मैट, 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 ऑपरेशन में अपडेट के अनुरोध, एपीआई को यह बताने के लिए फ़ील्ड मास्क का इस्तेमाल करते हैं कि किन फ़ील्ड में बदलाव किया जा रहा है. अपडेट करने का अनुरोध, उन फ़ील्ड को अनदेखा कर देता है जो फ़ील्ड मास्क में नहीं बताए गए हैं. साथ ही, उन फ़ील्ड की मौजूदा वैल्यू में कोई बदलाव नहीं करता.

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

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

का इस्तेमाल करने से बचें.

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

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