การเขียนพื้นฐาน

Google ชีต API ช่วยให้คุณเขียนค่าและสูตรลงในเซลล์ ช่วง ชุดช่วง และทั้งชีตได้ ตัวอย่างในหน้านี้แสดงให้เห็นว่าการดำเนินการเขียนทั่วไปบางอย่างสามารถทำได้ด้วยทรัพยากร spreadsheets.values ของชีต API

โปรดทราบว่าคุณยังเขียนค่าเซลล์โดยใช้เมธอด spreadsheet.batchUpdate ได้ด้วย ซึ่งอาจมีประโยชน์หากต้องการอัปเดตรูปแบบเซลล์พร้อมกัน หรือพร็อพเพอร์ตี้อื่นๆ ที่ทรัพยากร spreadsheets.values ไม่ส่งผล เช่น หากต้องการคัดลอกช่วงของเซลล์จาก ชีตหนึ่งไปยังอีกชีตหนึ่งขณะเขียนทับทั้งสูตรเซลล์และการจัดรูปแบบเซลล์ คุณสามารถใช้วิธีUpdateCellsRequest กับ spreadsheet.batchUpdate

อย่างไรก็ตาม สำหรับการเขียนค่าอย่างง่าย การใช้เมธอด spreadsheets.values.update หรือเมธอด spreadsheets.values.batchUpdate จะง่ายกว่า

ตัวอย่างเหล่านี้จะแสดงในรูปแบบคำขอ HTTP เพื่อให้เป็นกลางทางภาษา ดูวิธีใช้การเขียนในภาษาต่างๆ โดยใช้ไลบรารีของไคลเอ็นต์ Google API ได้ที่อ่านและเขียนค่า เซลล์

ในตัวอย่างเหล่านี้ ตัวยึดตำแหน่ง SPREADSHEET_ID จะระบุ ตำแหน่งที่คุณจะระบุรหัส สเปรดชีต ซึ่งดูได้จาก URL ของสเปรดชีต คุณระบุช่วงที่จะเขียนได้โดยใช้รูปแบบ 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 ฟิลด์ที่นี่จะแสดงการเปลี่ยนแปลงที่เกิดขึ้นกับแต่ละคอลัมน์ในช่วง อาร์เรย์แรกระบุว่า B1 จะไม่เปลี่ยนแปลง (เนื่องจากองค์ประกอบอาร์เรย์ null) ส่วน B4 จะล้าง (สตริงว่าง) B2 และ B3 มีการอัปเดตค่า อาร์เรย์ที่ 3 จะดำเนินการเดียวกันกับคอลัมน์ D ส่วนอาร์เรย์ว่างที่ 2 จะระบุว่าคอลัมน์ 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 แสดงวิธีเพิ่มค่า 2 แถวใหม่โดยเริ่มจากแถวที่ 3 ต้องระบุพารามิเตอร์การค้นหา 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,   } }

ชีตที่ได้จะมีลักษณะดังนี้