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

คุณสามารถใช้ 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,
}

ชีตผลลัพธ์จะมีลักษณะดังนี้

	A	ข	C	D
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 มีค่าของตนเอง อัปเดตแล้ว อาร์เรย์ที่สามทำงานเดียวกันในคอลัมน์ D ขณะที่ อาร์เรย์ว่างค่าที่สองหมายความว่าคอลัมน์ C จะถูกปล่อยไว้ตามเดิม

คำตอบจะประกอบด้วย UpdateValuesResponse เช่นรายการนี้:

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

ชีตผลลัพธ์จะมีลักษณะดังนี้

	A	ข	C	D
1	รายการ	ค่าใช้จ่าย	มีสินค้าพร้อมจำหน่าย	วันที่จัดส่ง
2	ตั๋วขึ้นชิงช้าสวรรค์	$1.00	4	1/4/2016
3	ประตู	80 บาท	2	15/4/2016
4	เครื่องยนต์		1
5	ผลรวม	$3.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	ข	C	D
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	ข	C	D	E
1	ข้อมูล	123.45	จริง	=MAX(D2:D4)	10
2

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

ต่อท้ายค่า

เริ่มต้นด้วยชีตตามตารางด้านล่าง

	A	ข	C	D
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	ข	C	D
1	รายการ	ค่าใช้จ่าย	มีสินค้าพร้อมจำหน่าย	วันที่จัดส่ง
2	ตั๋วขึ้นชิงช้าสวรรค์	฿600.00	4	1/3/2016
3	ประตู	$15	2	15/3/2016
4	เครื่องยนต์	$100	1	20/3/2016
5