सामान्य लेखन

Google Sheets API की मदद से, सेल, रेंज, रेंज के सेट, और पूरी शीट में वैल्यू और फ़ॉर्मूला डाले जा सकते हैं. इस पेज पर दिए गए उदाहरणों से पता चलता है कि Sheets API के spreadsheets.values संसाधन की मदद से, डेटा को लिखने के कुछ सामान्य काम कैसे किए जा सकते हैं.

ध्यान दें कि spreadsheet.batchUpdate तरीका इस्तेमाल करके भी सेल वैल्यू लिखी जा सकती हैं. यह तरीका तब काम का हो सकता है, जब आपको सेल फ़ॉर्मैटिंग या ऐसी अन्य प्रॉपर्टी को एक साथ अपडेट करना हो जिन पर spreadsheets.values रिसोर्स का असर न पड़ता हो. उदाहरण के लिए, अगर आपको सेल के फ़ॉर्मूला और सेल के फ़ॉर्मैट, दोनों को बदलते हुए सेल की रेंज को एक शीट से दूसरी शीट पर कॉपी करना है, तो spreadsheet.batchUpdate के साथ UpdateCellsRequest का इस्तेमाल करें.

हालांकि, सामान्य वैल्यू लिखने के लिए, spreadsheets.values.update या spreadsheets.values.batchUpdate वाले तरीके का इस्तेमाल करना आसान होता है.

ये उदाहरण, एचटीटीपी अनुरोधों के तौर पर दिए गए हैं, ताकि ये किसी भी भाषा के लिए काम कर सकें. Google API क्लाइंट लाइब्रेरी का इस्तेमाल करके, अलग-अलग भाषाओं में डेटा लिखने का तरीका जानने के लिए, सेल वैल्यू पढ़ना और उनमें बदलाव करना लेख पढ़ें.

इन उदाहरणों में, प्लेसहोल्डर SPREADSHEET_ID से पता चलता है कि स्प्रेडशीट आईडी कहां डालना है. स्प्रेडशीट आईडी, स्प्रेडशीट के यूआरएल से पता लगाया जा सकता है. डेटा डालने के लिए रेंज, A1 के नोटेशन का इस्तेमाल करके तय की जाती हैं. रेंज का उदाहरण, Sheet1!A1:D5 है.

एक रेंज लिखना

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

अनुरोध का मुख्य हिस्सा एक ऐसा ValueRange ऑब्जेक्ट होता है जिसमें लिखी जाने वाली रेंज की वैल्यू की जानकारी होती है. majorDimension फ़ील्ड से पता चलता है कि ऐरे, लाइनों के हिसाब से व्यवस्थित की गई वैल्यू की सूचियां हैं. टारगेट रेंज में मौजूद वैल्यू, ओवरराइट हो जाती हैं.

अनुरोध का प्रोटोकॉल यहां दिखाया गया है.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "3/1/2016"],
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

रिस्पॉन्स में एक UpdateValuesResponse ऑब्जेक्ट होता है, जैसे कि यह:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

इससे बनी शीट कुछ इस तरह दिखती है:

किसी रेंज में चुनिंदा डेटा डालना

किसी रेंज में वैल्यू लिखते समय, उससे जुड़े ऐरे एलिमेंट को null पर सेट करके, कुछ मौजूदा सेल में बदलाव होने से बचा जा सकता है. किसी सेल को खाली करने के लिए, उसमें खाली स्ट्रिंग ("") लिखी जा सकती है.

ऊपर दिए गए उदाहरण में मौजूद डेटा वाली शीट से शुरू करके, यहां दिए गए spreadsheets.values.update कोड सैंपल में, रेंज B1:D4 में वैल्यू डालने का तरीका बताया गया है. इसमें कुछ सेल में कोई बदलाव नहीं किया गया है और कुछ सेल को खाली छोड़ दिया गया है. ValueInputOption क्वेरी पैरामीटर ज़रूरी है. इससे यह तय होता है कि लिखी गई वैल्यू को पार्स किया गया है या नहीं. उदाहरण के लिए, किसी स्ट्रिंग को तारीख में बदला गया है या नहीं.

अनुरोध का मुख्य हिस्सा एक ऐसा ValueRange ऑब्जेक्ट होता है जिसमें लिखी जाने वाली रेंज की वैल्यू की जानकारी होती है. majorDimension फ़ील्ड से पता चलता है कि ऐरे, कॉलम के हिसाब से व्यवस्थित की गई वैल्यू की सूचियां हैं.

अनुरोध का प्रोटोकॉल यहां दिखाया गया है.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!B1",
  "majorDimension": "COLUMNS",
  "values": [
    [null,"$1","$2", ""],
    [],
    [null,"4/1/2016", "4/15/2016", ""]
  ]
}

यहां values फ़ील्ड में, रेंज के हर कॉलम में किए गए बदलावों की सूची होती है. पहले ऐरे से पता चलता है कि null ऐरे एलिमेंट की वजह से, B1 में कोई बदलाव नहीं किया जाना है. वहीं, B4 को खाली (स्ट्रिंग) किया जाना है. B2 और B3 की वैल्यू अपडेट हो गई हैं. तीसरा ऐरे, कॉलम D पर वही कार्रवाइयां करता है, जबकि दूसरा खाली ऐरे बताता है कि कॉलम C में कोई बदलाव नहीं किया जाना है.

रिस्पॉन्स में, इस तरह का UpdateValuesResponse ऑब्जेक्ट होता है:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

इससे बनी शीट कुछ इस तरह दिखती है:

ध्यान दें कि इस अनुरोध से "कुल" पंक्ति में सीधे तौर पर बदलाव नहीं होता, लेकिन इसमें बदलाव होता है. इसकी वजह यह है कि इस पंक्ति की सेल में ऐसे फ़ॉर्मूले होते हैं जो बदली गई सेल पर निर्भर करते हैं.

एक से ज़्यादा रेंज में लिखना

खाली शीट से शुरू करके, यहां दिया गया spreadsheets.values.batchUpdate कोड सैंपल दिखाता है कि Sheet1!A1:A4 और Sheet1!B1:D2 रेंज में वैल्यू कैसे लिखी जाती हैं. टारगेट रेंज में मौजूद वैल्यू ओवरराइट हो जाती हैं. अनुरोध के मुख्य हिस्से में एक ValueInputOption ऑब्जेक्ट होता है. इसमें इनपुट डेटा को समझने का तरीका बताया जाता है. साथ ही, लिखी गई हर रेंज से जुड़े ValueRange ऑब्जेक्ट का एक कलेक्शन भी होता है. majorDimension फ़ील्ड से यह तय होता है कि शामिल किए गए ऐरे को कॉलम या पंक्तियों के ऐरे के तौर पर समझा जाए.

अनुरोध का प्रोटोकॉल यहां दिखाया गया है.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchUpdate

{
  "valueInputOption": "VALUE_INPUT_OPTION",
  "data": [
    {
      "range": "Sheet1!A1:A4",
      "majorDimension": "COLUMNS",
      "values": [
        ["Item", "Wheel", "Door", "Engine"]
      ]
    },
    {
      "range": "Sheet1!B1:D2",
      "majorDimension": "ROWS",
      "values": [
        ["Cost", "Stocked", "Ship Date"],
        ["$20.50", "4", "3/1/2016"]
      ]
    }
  ]
}

जवाब में एक ऑब्जेक्ट होता है, जिसमें अपडेट की गई सेल के आंकड़ों की सूची होती है. साथ ही, इसमें UpdateValuesResponse ऑब्जेक्ट का एक कलेक्शन होता है. यह कलेक्शन, अपडेट की गई हर रेंज के लिए एक होता है. उदाहरण के लिए:

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 4,
  "totalUpdatedColumns": 4,
  "totalUpdatedCells": 10,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!A1:A4",
      "updatedRows": 4,
      "updatedColumns": 1,
      "updatedCells": 4,
    },
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!B1:D2",
      "updatedRows": 2,
      "updatedColumns": 3,
      "updatedCells": 6,
    }
  ],
}

इससे बनी शीट कुछ इस तरह दिखती है:

पार्स किए बिना वैल्यू लिखना

यहां दिए गए spreadsheets.values.update कोड सैंपल में, खाली शीट से शुरू करके, Sheet1!A1:E1 रेंज में वैल्यू लिखने का तरीका बताया गया है. हालांकि, लिखी गई स्ट्रिंग को फ़ॉर्मूला, बोलियन या संख्या के तौर पर पार्स होने से रोकने के लिए, RAW ValueInputOption क्वेरी पैरामीटर का इस्तेमाल किया गया है. ये स्ट्रिंग के तौर पर दिखते हैं और शीट में टेक्स्ट अलाइनमेंट, जस्टिफ़ाइड होता है.

अनुरोध का मुख्य हिस्सा एक ऐसा ValueRange ऑब्जेक्ट होता है जिसमें लिखी जाने वाली रेंज की वैल्यू की जानकारी होती है. majorDimension फ़ील्ड से पता चलता है कि ऐरे, लाइनों के हिसाब से व्यवस्थित की गई वैल्यू की सूचियां हैं. टारगेट रेंज में मौजूद वैल्यू, ओवरराइट हो जाती हैं.

अनुरोध का प्रोटोकॉल यहां दिखाया गया है.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Data", 123.45, true, "=MAX(D2:D4)", "10"]
  ],
}

रिस्पॉन्स में, इस तरह का UpdateValuesResponse ऑब्जेक्ट होता है:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

इससे बनी शीट कुछ इस तरह दिखती है:

ध्यान दें कि "TRUE" को बीच में रखा गया है और यह एक बूलियन वैल्यू है. वहीं, "123.45" को दाईं ओर अलाइन किया गया है, क्योंकि यह एक संख्या है. साथ ही, "10" को बाईं ओर अलाइन किया गया है, क्योंकि यह एक स्ट्रिंग है. फ़ॉर्मूला को पार्स नहीं किया जाता और यह स्ट्रिंग के तौर पर भी दिखता है.

वैल्यू जोड़ना

नीचे दी गई टेबल जैसी शीट से शुरू करें:

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

अनुरोध का मुख्य हिस्सा एक ऐसा ValueRange ऑब्जेक्ट होता है जिसमें लिखी जाने वाली रेंज की वैल्यू की जानकारी होती है. majorDimension फ़ील्ड से पता चलता है कि ऐरे, लाइनों के हिसाब से व्यवस्थित की गई वैल्यू की सूचियां हैं.

अनुरोध का प्रोटोकॉल यहां दिखाया गया है.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
  ],
}

रिस्पॉन्स में, इस तरह का AppendValuesResponse ऑब्जेक्ट होता है:

{
  "spreadsheetId": SPREADSHEET_ID,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": SPREADSHEET_ID,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

इससे बनी शीट कुछ इस तरह दिखती है: