Google ชีต API ช่วยให้คุณเขียนค่าและสูตรในเซลล์ ช่วง ชุดของช่วง และทั้งชีตได้ ตัวอย่างในหน้านี้จะแสดงให้เห็นวิธีเขียนทั่วไปเมื่อใช้ทรัพยากร spreadsheets.values
ของ Sheets 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,
}
ชีตผลลัพธ์จะมีลักษณะดังนี้
A | B | C | ว | |
1 | รายการ | ค่าใช้จ่าย | มีสินค้าพร้อมจำหน่าย | วันที่จัดส่ง |
2 | ตั๋วขึ้นชิงช้าสวรรค์ | ฿600.00 | 4 | 1/3/2016 |
3 | ประตู | $15 | 2 | 15/3/2016 |
4 | เครื่องยนต์ | $100 | 1 | 20/3/2016 |
5 | ผลรวม | ฿135.5 | 7 | 20/3/2016 |
เขียนเฉพาะจุดที่ต้องการ
คุณอาจเขียนค่าลงในช่วงเพื่อหลีกเลี่ยงการเปลี่ยนแปลงเซลล์ที่มีอยู่โดยตั้งค่าองค์ประกอบอาร์เรย์ที่เกี่ยวข้องเป็น 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,
}
ชีตผลลัพธ์จะมีลักษณะดังนี้
A | B | C | ว | |
1 | รายการ | ค่าใช้จ่าย | มีสินค้าพร้อมจำหน่าย | วันที่จัดส่ง |
2 | ตั๋วขึ้นชิงช้าสวรรค์ | 30.00 บาท | 4 | 1/4/2016 |
3 | ประตู | 80 บาท | 2 | 15/4/2016 |
4 | เครื่องยนต์ | 1 | ||
5 | ผลรวม | 90.00 บาท | 7 | 15/4/2016 |
โปรดทราบว่าแถว "ผลรวม" แม้จะไม่เปลี่ยนแปลงโดยตรงโดยคำขอนี้ จะเปลี่ยนแปลงเนื่องจากเซลล์มีสูตรที่ขึ้นอยู่กับเซลล์ที่เปลี่ยนแปลง
เขียนไปยังหลายช่วง
เริ่มต้นด้วยชีตเปล่า ตัวอย่างโค้ด 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, } ], }
ชีตผลลัพธ์จะมีลักษณะดังนี้
A | B | C | ว | |
1 | รายการ | ค่าใช้จ่าย | มีสินค้าพร้อมจำหน่าย | วันที่จัดส่ง |
2 | ตั๋วขึ้นชิงช้าสวรรค์ | ฿600.00 | 4 | 1/3/2016 |
3 | ประตู | |||
4 | เครื่องยนต์ | |||
5 |
เขียนค่าโดยไม่ต้องแยกวิเคราะห์
เริ่มต้นด้วยชีตเปล่า ตัวอย่างโค้ด 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,
}
ชีตผลลัพธ์จะมีลักษณะดังนี้
A | B | C | ว | E | |
1 | ข้อมูล | 123.45 | TRUE | =MAX(D2:D4) | 10 |
2 |
โปรดทราบว่า "TRUE" อยู่ตรงกลางและเป็นค่าบูลีน ในขณะที่ "123.45" เป็นค่าที่ถูกต้องเพราะเป็นตัวเลข และ "10" จะชิดขอบเพราะเป็นสตริง สูตรไม่ได้รับการแยกวิเคราะห์และจะปรากฏเป็นสตริงด้วย
ต่อท้ายค่า
เริ่มต้นด้วยชีตตามตารางด้านล่าง
A | B | C | ว | |
1 | รายการ | ค่าใช้จ่าย | มีสินค้าพร้อมจำหน่าย | วันที่จัดส่ง |
2 | ตั๋วขึ้นชิงช้าสวรรค์ | ฿600.00 | 4 | 1/3/2016 |
3 |
ตัวอย่างโค้ด 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, } }
ชีตผลลัพธ์จะมีลักษณะดังนี้
A | B | C | ว | |
1 | รายการ | ค่าใช้จ่าย | มีสินค้าพร้อมจำหน่าย | วันที่จัดส่ง |
2 | ตั๋วขึ้นชิงช้าสวรรค์ | ฿600.00 | 4 | 1/3/2016 |
3 | ประตู | $15 | 2 | 15/3/2016 |
4 | เครื่องยนต์ | $100 | 1 | 20/3/2016 |
5 |