डेवलपर मेटाडेटा पढ़ें और लिखें

'डेवलपर मेटाडेटा' सुविधा की मदद से, मेटाडेटा को स्प्रेडशीट में अलग-अलग इकाइयों और जगहों से जोड़ा जा सकता है. इसके बाद आप इस मेटाडेटा पर क्वेरी कर सकते हैं और इसका इस्तेमाल उन ऑब्जेक्ट को ढूंढने के लिए कर सकते हैं जिनसे यह जुड़ा है.

मेटाडेटा को पंक्तियों, कॉलम, शीट या स्प्रेडशीट से जोड़ा जा सकता है.

डेवलपर मेटाडेटा से इस तरह के काम किए जा सकते हैं:

  • किसी स्प्रेडशीट में मौजूद अलग-अलग इकाइयों और जगहों के साथ आर्बिट्रेरी डेटा को जोड़ना—उदाहरण के लिए, totals को कॉलम D से या responseId = 1234 को पंक्ति 7 से जोड़ें.

  • किसी खास मेटाडेटा कुंजी या एट्रिब्यूट से जुड़ी सभी जगहें और डेटा ढूंढें—उदाहरण के लिए, कॉलम D से जुड़ी totals कुंजी या responseId देने पर, responseId मेटाडेटा और उनसे जुड़ी मेटाडेटा वैल्यू वाली सभी लाइनें दिखती हैं.

  • किसी खास इकाई या जगह से जुड़ा पूरा डेटा ढूंढें—उदाहरण के लिए, दिए गए कॉलम D में उस जगह से जुड़ा पूरा मेटाडेटा दिखाया जा सकता है.

  • किसी जगह से जुड़े मेटाडेटा की जानकारी देकर वैल्यू पाना—उदाहरण के लिए, दिए गए totals से जुड़े कॉलम या लाइन में मौजूद वैल्यू दिखती हैं या summary दी गई है, जिससे शीट के संसाधन से जुड़ा डेटा दिखता है.

  • किसी जगह से जुड़े मेटाडेटा की जानकारी देकर वैल्यू अपडेट करना—उदाहरण के लिए, A1 नोटेशन की मदद से लाइन में वैल्यू अपडेट करने के बजाय, मेटाडेटा आईडी की जानकारी देकर वैल्यू अपडेट करें.

पढ़ने और लिखने का मेटाडेटा

spreadsheets.developerMetadata संसाधन की मदद से, स्प्रेडशीट में मौजूद जगह या ऑब्जेक्ट से जुड़े डेवलपर मेटाडेटा को ऐक्सेस किया जा सकता है.

डेवलपर मेटाडेटा के बारे में जानकारी

इस सेक्शन में डेवलपर मेटाडेटा के कुछ अहम पहलुओं के बारे में बताया गया है. इन्हें Sheets API के साथ काम करते समय ध्यान में रखना चाहिए.

टैग के तौर पर मेटाडेटा

डेवलपर मेटाडेटा का एक इस्तेमाल ऐसा टैग है जिसमें सिर्फ़ एक कुंजी और जगह का इस्तेमाल करके, स्प्रेडशीट में किसी जगह का नाम दिया जाता है. उदाहरण के लिए, आपके पास headerRow को किसी खास लाइन या totals को शीट के किसी खास कॉलम से जोड़ने का विकल्प होता है. टैग का इस्तेमाल, स्प्रेडशीट के कुछ हिस्सों को तीसरे पक्ष के टूल या डेटाबेस के फ़ील्ड से सिमैंटिक तौर पर बाइंड करने के लिए किया जा सकता है. इसलिए, स्प्रेडशीट में किए जाने वाले बदलावों से आपका ऐप्लिकेशन काम नहीं करेगा.

प्रॉपर्टी के तौर पर मेटाडेटा

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

  • पंक्ति के साथ formResponseId = resp123
  • कॉलम के साथ lastUpdated = 1477369882.

इसकी मदद से, किसी स्प्रेडशीट में खास जगहों या डेटा से जुड़ी, नाम वाली प्रॉपर्टी को स्टोर और ऐक्सेस किया जा सकता है.

प्रोजेक्ट बनाम दस्तावेज़ दिखने वाला मेटाडेटा

किसी डेवलपर प्रोजेक्ट को दूसरे के मेटाडेटा में रुकावट डालने से रोकने के लिए, visibility मेटाडेटा की दो सेटिंग होती हैं: project और document. Sheets API का इस्तेमाल करके, प्रोजेक्ट मेटाडेटा सिर्फ़ उस डेवलपर प्रोजेक्ट से दिखता और ऐक्सेस किया जा सकता है जिसने उसे बनाया था. दस्तावेज़ के मेटाडेटा को ऐसे किसी भी डेवलपर प्रोजेक्ट से ऐक्सेस किया जा सकता है जिसके पास दस्तावेज़ का ऐक्सेस होता है.

ऐसी क्वेरी जिनमें यह साफ़ तौर पर नहीं बताया जाता कि उनके दिखने की जानकारी देने वाला दस्तावेज़ मेटाडेटा और प्रोजेक्ट से मेल खाने वाला प्रोजेक्ट मेटाडेटा, अनुरोध करने वाले डेवलपर प्रोजेक्ट से कितना मेल खाता है.

खासियत

यह ज़रूरी नहीं है कि मेटाडेटा की कुंजियां यूनीक हों, लेकिन metadataId हर एक में अलग-अलग होने चाहिए. अगर मेटाडेटा बनाया जाता है और उसके आईडी फ़ील्ड को खाली छोड़ दिया जाता है, तो एपीआई एक मेटाडेटा असाइन करता है. इस आईडी का इस्तेमाल मेटाडेटा की पहचान करने के लिए किया जा सकता है. वहीं दूसरी ओर, कुंजियों और दूसरे एट्रिब्यूट का इस्तेमाल मेटाडेटा के सेट की पहचान करने के लिए किया जा सकता है.

मेटाडेटा बनाएं

मेटाडेटा बनाने के लिए, batchUpdate तरीके का इस्तेमाल करें. साथ ही, metadataKey, location, और visibility की मदद से createDeveloperMetadataRequest का इस्तेमाल करें. आपके पास metadataValue या metadataId को अलग से बताने का विकल्प भी होता है.

अगर किसी ऐसे आईडी का इस्तेमाल किया जाता है जिसे पहले से इस्तेमाल किया जा रहा है, तो अनुरोध पूरा नहीं किया जा सकेगा. अगर आप कोई आईडी नहीं देते, तो एपीआई एक आईडी असाइन करता है.

एक उदाहरण दिखाएं

इस उदाहरण में, हमने अनुरोध में एक कुंजी, वैल्यू, और एक पंक्ति दी है. जवाब में, डेवलपर मेटाडेटा की ये वैल्यू और असाइन किया गया मेटाडेटा आईडी दिखाया जाता है.

अनुरोध करें

{
  "requests": [
    {
      "createDeveloperMetadata": {
        "developerMetadata": {
          "location": {
            "dimensionRange": {
              "sheetId": sheetId,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT",
          "metadataKey": "Sales",
          "metadataValue": "2022"
        }
      }
    }
  ]
}

जवाब

{
  "spreadsheetId": spreadsheetId,
  "replies": [
    {
      "createDeveloperMetadata": {
        "developerMetadata": {
          "metadataId": metadataId,
          "metadataKey": "Sales",
          "metadataValue": "2022",
          "location": {
            "locationType": "ROW",
            "dimensionRange": {
              "sheetId": sheetId,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT"
        }
      }
    }
  ]
}

कोई एक मेटाडेटा आइटम पढ़ना

किसी एक अलग डेवलपर मेटाडेटा को वापस पाने के लिए, spreadsheets.developerMetadata.get तरीके का इस्तेमाल करें. इसमें, ऐसे spreadsheetId के बारे में बताएं जिसमें मेटाडेटा और डेवलपर मेटाडेटा का यूनीक metadataId शामिल हो.

एक उदाहरण दिखाएं

अनुरोध करें

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

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId

जवाब

{
  "metadataId": metadataId,
  "metadataKey": "Sales",
  "metadataValue": "2022",
  "location": {
    "locationType": "ROW",
    "dimensionRange": {
      "sheetId": sheetId,
      "dimension": "ROWS",
      "startIndex": 6,
      "endIndex": 7
    }
  },
  "visibility": "DOCUMENT"
}

एक से ज़्यादा मेटाडेटा आइटम पढ़ना

डेवलपर मेटाडेटा के एक से ज़्यादा आइटम वापस पाने के लिए, spreadsheets.developerMetadata.search तरीके का इस्तेमाल करें. आपको DataFilter के बारे में बताना होगा, जो कुंजी, वैल्यू, जगह या 'किसको दिखे' जैसी प्रॉपर्टी के किसी भी कॉम्बिनेशन के किसी भी मौजूदा मेटाडेटा से मेल खाता हो.

एक उदाहरण दिखाएं

इस उदाहरण में, हमने अनुरोध में कई मेटाडेटा आईडी दिए हैं. रिस्पॉन्स, हर मेटाडेटा आईडी के लिए डेवलपर मेटाडेटा की वैल्यू दिखाता है.

अनुरोध करें

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    },
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ]
}

जवाब

{
  "matchedDeveloperMetadata": [
    {
      "developerMetadata": {
        "metadataId": metadataId,
        "metadataKey": "Revenue",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": sheetId
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    },
    {
      "developerMetadata": {
        "metadataId": metadataId,
        "metadataKey": "Sales",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": sheetId
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    }
  ]
}

मेटाडेटा अपडेट करें

डेवलपर मेटाडेटा को अपडेट करने के लिए, spreadsheets.batchUpdate तरीका इस्तेमाल करें और UpdateDeveloperMetadataRequest की जानकारी दें. आपको अपडेट किए जाने वाले मेटाडेटा को टारगेट करने वाले DataFilter, नई वैल्यू वाले DeveloperMetadata ऑब्जेक्ट, और अपडेट किए जाने वाले फ़ील्ड के बारे में जानकारी देने वाला फ़ील्ड मास्क तय करना होगा.

एक उदाहरण दिखाएं

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

अनुरोध करें

{
  "requests": [
    {
      "updateDeveloperMetadata": {
        "dataFilters": [
          {
            "developerMetadataLookup": {
              "metadataId": metadataId
            }
          }
        ],
        "developerMetadata": {
          "location": {
            "sheetId": sheetId
          },
          "metadataKey": "SalesUpdated"
        },
        "fields": "location,metadataKey"
      }
    }
  ]
}

जवाब

{
  "spreadsheetId": spreadsheetId,
  "replies": [
    {
      "updateDeveloperMetadata": {
        "developerMetadata": [
          {
            "metadataId": metadataId,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": sheetId
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

मेटाडेटा मिटाएं

डेवलपर मेटाडेटा मिटाने के लिए, batchUpdate तरीके का इस्तेमाल करें और DeleteDeveloperMetadataRequest का इस्तेमाल करें. आपको जो मेटाडेटा मिटाना है उसे चुनने के लिए, आपको DataFilter तय करना होगा.

एक उदाहरण दिखाएं

इस उदाहरण में, हम अनुरोध में मेटाडेटा आईडी देते हैं. रिस्पॉन्स, मेटाडेटा आईडी के लिए डेवलपर मेटाडेटा की वैल्यू दिखाता है.

डेवलपर मेटाडेटा हटाए जाने की पुष्टि करने के लिए, spreadsheets.developerMetadata.get का इस्तेमाल करें. इसमें मिटाए गए मेटाडेटा आईडी की जानकारी दें. आपको 404: Not Found एचटीटीपी स्टेटस कोड रिस्पॉन्स मिलेगा. इसमें यह मैसेज होगा, "metadataId आईडी वाला कोई डेवलपर मेटाडेटा नहीं है.

अनुरोध करें

{
  "requests": [
    {
      "deleteDeveloperMetadata": {
        "dataFilter": {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      }
    }
  ]
}

जवाब

{
  "spreadsheetId": spreadsheetId,
  "replies": [
    {
      "deleteDeveloperMetadata": {
        "deletedDeveloperMetadata": [
          {
            "metadataId": metadataId,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": sheetId
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

मेटाडेटा से जुड़ी वैल्यू पढ़ना और उनमें बदलाव करना

पंक्तियों और कॉलम में सेल की वैल्यू वापस पाई जा सकती हैं और उन्हें अपडेट किया जा सकता है. इसके लिए, उनसे जुड़े डेवलपर मेटाडेटा और अपडेट की जाने वाली वैल्यू तय करें. ऐसा करने के लिए, नीचे दिए गए तरीके का इस्तेमाल करके, इससे मेल खाने वाले DataFilter का इस्तेमाल करें.

मेटाडेटा के हिसाब से सेल की वैल्यू पाएं

मेटाडेटा के हिसाब से सेल की वैल्यू पाने के लिए, spreadsheets.values.batchGetByDataFilter तरीके का इस्तेमाल करें. आपको स्प्रेडशीट आईडी और मेटाडेटा से मैच करने वाले एक या ज़्यादा डेटा फ़िल्टर तय करने होंगे.

एक उदाहरण दिखाएं

इस उदाहरण में, हम अनुरोध में मेटाडेटा आईडी देते हैं. रिस्पॉन्स, मेटाडेटा आईडी के लिए पंक्ति की सेल की वैल्यू (मॉडल नंबर, हर महीने की बिक्री) दिखाता है.

अनुरोध करें

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ],
  "majorDimension": "ROWS"
}

जवाब

{
  "spreadsheetId": spreadsheetId,
  "valueRanges": [
    {
      "valueRange": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "74"
          ]
        ]
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    }
  ]
}

मेटाडेटा के हिसाब से स्प्रेडशीट पाना

किसी स्प्रेडशीट को वापस पाने के लिए, spreadsheets.getByDataFilter तरीके का इस्तेमाल करके डेटा का सबसेट दिखाया जा सकता है. आपको स्प्रेडशीट आईडी और मेटाडेटा से मैच करने वाले एक या ज़्यादा डेटा फ़िल्टर तय करने होंगे.

यह अनुरोध सामान्य "स्प्रेडशीट GET" अनुरोध की तरह काम करता है. हालांकि, तय किए गए डेटा फ़िल्टर से मेल खाने वाले मेटाडेटा की सूची से यह तय होता है कि मेटाडेटा के साथ कौनसी शीट, ग्रिड डेटा, और दूसरे ऑब्जेक्ट संसाधन दिखाए जाएंगे. अगर includeGridData को 'सही है' पर सेट किया जाता है, तो तय की गई ग्रिड रेंज को इंटरसेक्ट करने वाला ग्रिड डेटा भी शीट में दिखाया जाता है.

एक उदाहरण दिखाएं

इस उदाहरण में, हम मेटाडेटा आईडी देते हैं और अनुरोध में includeGridData को 'गलत' पर सेट करते हैं. रिस्पॉन्स, स्प्रेडशीट और शीट प्रॉपर्टी, दोनों को दिखाता है.

अनुरोध करें

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ],
  "includeGridData": false
}

जवाब

{
  "spreadsheetId": spreadsheetId,
  "properties": {
    "title": "Sales Sheet",
    "locale": "en_US",
    "autoRecalc": "ON_CHANGE",
    "timeZone": "America/Los_Angeles",
    "defaultFormat": {
      "backgroundColor": {
        "red": 1,
        "green": 1,
        "blue": 1
      },
      "padding": {
        "top": 2,
        "right": 3,
        "bottom": 2,
        "left": 3
      },
      "verticalAlignment": "BOTTOM",
      "wrapStrategy": "OVERFLOW_CELL",
      "textFormat": {
        "foregroundColor": {},
        "fontFamily": "arial,sans,sans-serif",
        "fontSize": 10,
        "bold": false,
        "italic": false,
        "strikethrough": false,
        "underline": false,
        "foregroundColorStyle": {
          "rgbColor": {}
        }
      },
      "backgroundColorStyle": {
        "rgbColor": {
          "red": 1,
          "green": 1,
          "blue": 1
        }
      }
    },
    "spreadsheetTheme": {
      "primaryFontFamily": "Arial",
      "themeColors": [
        {
          "colorType": "TEXT",
          "color": {
            "rgbColor": {}
          }
        },
        {
          "colorType": "BACKGROUND",
          "color": {
            "rgbColor": {
              "red": 1,
              "green": 1,
              "blue": 1
            }
          }
        },
        {
          "colorType": "ACCENT1",
          "color": {
            "rgbColor": {
              "red": 0.25882354,
              "green": 0.52156866,
              "blue": 0.95686275
            }
          }
        },
        {
          "colorType": "ACCENT2",
          "color": {
            "rgbColor": {
              "red": 0.91764706,
              "green": 0.2627451,
              "blue": 0.20784314
            }
          }
        },
        {
          "colorType": "ACCENT3",
          "color": {
            "rgbColor": {
              "red": 0.9843137,
              "green": 0.7372549,
              "blue": 0.015686275
            }
          }
        },
        {
          "colorType": "ACCENT4",
          "color": {
            "rgbColor": {
              "red": 0.20392157,
              "green": 0.65882355,
              "blue": 0.3254902
            }
          }
        },
        {
          "colorType": "ACCENT5",
          "color": {
            "rgbColor": {
              "red": 1,
              "green": 0.42745098,
              "blue": 0.003921569
            }
          }
        },
        {
          "colorType": "ACCENT6",
          "color": {
            "rgbColor": {
              "red": 0.27450982,
              "green": 0.7411765,
              "blue": 0.7764706
            }
          }
        },
        {
          "colorType": "LINK",
          "color": {
            "rgbColor": {
              "red": 0.06666667,
              "green": 0.33333334,
              "blue": 0.8
            }
          }
        }
      ]
    }
  },
  "sheets": [
    {
      "properties": {
        "sheetId": sheetId,
        "title": "Sheet7",
        "index": 7,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 1000,
          "columnCount": 26
        }
      }
    }
  ],
  "spreadsheetUrl": spreadsheetUrl
}

मेटाडेटा के हिसाब से वैल्यू अपडेट करना

किसी खास मेटाडेटा से मेल खाने वाली सेल की वैल्यू को अपडेट करने के लिए, spreadsheets.values.batchUpdateByDataFilter तरीके का इस्तेमाल करें. आपको स्प्रेडशीट आईडी valueInputOption के साथ-साथ, मेटाडेटा से मेल खाने वाली एक या एक से ज़्यादा DataFilterValueRange की जानकारी देनी होगी.

एक उदाहरण दिखाएं

इस उदाहरण में, हम अनुरोध में मेटाडेटा आईडी और अपडेट की गई लाइन की वैल्यू देते हैं. रिस्पॉन्स, अपडेट की गई प्रॉपर्टी और मेटाडेटा आईडी के डेटा, दोनों को दिखाता है.

अनुरोध करें

{
  "data": [
    {
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": metadataId
        }
      },
      "majorDimension": "ROWS",
      "values": [
        [
          "W-24",
          "84"
        ]
      ]
    }
  ],
  "includeValuesInResponse": true,
  "valueInputOption": "USER_ENTERED"
}

जवाब

{
  "spreadsheetId": spreadsheetId,
  "totalUpdatedRows": 1,
  "totalUpdatedColumns": 2,
  "totalUpdatedCells": 2,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "updatedRange": "Sheet7!A7:B7",
      "updatedRows": 1,
      "updatedColumns": 2,
      "updatedCells": 2,
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": metadataId
        }
      },
      "updatedData": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "84"
          ]
        ]
      }
    }
  ]
}

मेटाडेटा के हिसाब से वैल्यू हटाएं

किसी खास मेटाडेटा से मेल खाने वाली सेल की वैल्यू मिटाने के लिए, spreadsheets.values.batchClearByDataFilter तरीके का इस्तेमाल करें. आपको जो मेटाडेटा हटाना है उसे चुनने के लिए, आपको डेटा फ़िल्टर तय करना होगा.

एक उदाहरण दिखाएं

अनुरोध करें

इस उदाहरण में, हम अनुरोध में मेटाडेटा आईडी देते हैं. जवाब, स्प्रेडशीट आईडी और मिटाई गई रेंज दिखाता है.

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ]
}

जवाब

{
  "spreadsheetId": spreadsheetId,
  "clearedRanges": [
    "Sheet7!A7:Z7"
  ]
}

मेटाडेटा को सेव करने की सीमाएं

स्प्रेडशीट में एक तय सीमा तक ही मेटाडेटा सेव किया जा सकता है. इस सीमा को वर्णों में मापा जाता है और इसमें दो कॉम्पोनेंट होते हैं:

आइटम स्टोरेज की सीमा तय करना
स्प्रेडशीट 30,000 वर्ण
किसी स्प्रेडशीट में हर शीट 30,000 वर्ण

स्प्रेडशीट में ज़्यादा से ज़्यादा 30,000 वर्ण सेव किए जा सकते हैं. इसके अलावा, आपके पास स्प्रेडशीट में हर शीट के लिए 30,000 वर्ण (शीट एक के लिए 30,000, शीट 2 के लिए 30,000 वगैरह) के लिए 30, 000 वर्ण सेव करने का विकल्प है. तीन पेजों वाली स्प्रेडशीट में, डेवलपर मेटाडेटा के ज़्यादा से ज़्यादा 1,20,000 वर्ण हो सकते हैं.

किसी developerMetadata ऑब्जेक्ट के कुंजी और वैल्यू एट्रिब्यूट के हर वर्ण को इस सीमा में गिना जाता है.