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

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

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

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

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

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