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

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

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

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

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

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

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