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