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

Google Sheets 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,
}

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

	ก	B	C	D
1	รายการ	ค่าใช้จ่าย	มีในสต็อก	วันที่จัดส่ง
2	ตั๋วขึ้นชิงช้าสวรรค์	205.00 THB	4	1/3/2016
3	ประตู	$15	2	15/3/2016
4	เครื่องยนต์	$100	1	20/3/2016
5	ผลรวม	135.50 THB	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,
}

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

	ก	B	C	D
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 โดย 1 รายการสำหรับแต่ละช่วงที่อัปเดต เช่น

{
  "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,
    }
  ],
}

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

	ก	B	C	D
1	รายการ	ค่าใช้จ่าย	มีในสต็อก	วันที่จัดส่ง
2	ตั๋วขึ้นชิงช้าสวรรค์	205.00 THB	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,
}

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

	ก	B	C	D	จ.
1	ข้อมูล	123.45	TRUE	=MAX(D2:D4)	10
2

โปรดทราบว่า "TRUE" อยู่ตรงกลางและเป็นค่าบูลีน ส่วน "123.45" อยู่ทางขวาเพราะเป็นตัวเลข และ "10" อยู่ชิดขอบเพราะเป็นสตริง สูตรจะไม่ได้รับการแยกวิเคราะห์และจะปรากฏเป็นสตริงด้วย

ต่อท้ายค่า

เริ่มต้นด้วยชีตที่มีลักษณะเหมือนตารางด้านล่าง

	ก	B	C	D
1	รายการ	ค่าใช้จ่าย	มีในสต็อก	วันที่จัดส่ง
2	ตั๋วขึ้นชิงช้าสวรรค์	205.00 THB	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,
  }
}

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

	ก	B	C	D
1	รายการ	ค่าใช้จ่าย	มีในสต็อก	วันที่จัดส่ง
2	ตั๋วขึ้นชิงช้าสวรรค์	205.00 THB	4	1/3/2016
3	ประตู	$15	2	15/3/2016
4	เครื่องยนต์	$100	1	20/3/2016
5