สเปรดชีตอาจมีหลายชีต โดยแต่ละชีตมีแถวหรือคอลัมน์กี่แถวหรือคอลัมน์ก็ได้ เซลล์คือตําแหน่งที่ตัดกันของแถวและคอลัมน์หนึ่งๆ และอาจมีค่าข้อมูล Google ชีต API มีแหล่งข้อมูล spreadsheets.values
ที่ช่วยในการอ่านและเขียนค่า
หน้านี้อธิบายพื้นฐานในการใช้ทรัพยากร spreadsheets.values
หากต้องการแทรกแถวหรืออัปเดตการจัดรูปแบบและพร็อพเพอร์ตี้อื่นๆ ในชีต คุณต้องใช้วิธี spreadsheets.batchUpdate
ที่อธิบายไว้ในอัปเดตสเปรดชีต
เมธอด
แหล่งข้อมูล spreadsheets.values
มีวิธีการต่อไปนี้สําหรับการอ่านและเขียนค่า โดยแต่ละวิธีมีไว้สําหรับงานเฉพาะ
การเข้าถึงระยะ | การอ่าน | การเขียน |
---|---|---|
ช่วงเดียว | spreadsheets.values.get |
spreadsheets.values.update |
ช่วงหลายช่วง | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
การต่อท้าย | spreadsheets.values.append |
โดยทั่วไปแล้ว คุณควรรวมการอ่านหรือการอัปเดตหลายรายการเข้ากับเมธอด batchGet
และ batchUpdate
(ตามลำดับ) เนื่องจากจะช่วยเพิ่มประสิทธิภาพ
คุณดูตัวอย่างของวิธีการแต่ละวิธีได้ในหน้าตัวอย่างการอ่านพื้นฐานและการเขียนพื้นฐาน หากต้องการดูตัวอย่างทั้งหมด โปรดไปที่หน้าภาพรวมของตัวอย่าง
อ่าน
หากต้องการอ่านค่าข้อมูลจากชีต คุณต้องมีรหัสสเปรดชีตและรูปแบบ A1 สำหรับช่วง การระบุช่วงโดยไม่มีรหัสชีต (A1:B2
) หมายความว่าคําขอจะดําเนินการบนชีตแรกในสเปรดชีต ดูข้อมูลเพิ่มเติมเกี่ยวกับรหัสสเปรดชีตและรูปแบบ A1 ได้ที่ภาพรวมของ Google Sheets API
พารามิเตอร์การค้นหาที่ไม่บังคับหลายรายการควบคุมรูปแบบของเอาต์พุต ดังนี้
พารามิเตอร์รูปแบบ | ค่าเริ่มต้น |
---|---|
majorDimension |
ROWS |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
โปรดทราบว่าคุณควรใช้ dateTimeRenderOption
เฉพาะในกรณีที่ valueRenderOption
ไม่ใช่ FORMATTED_VALUE
ไม่มีการจํากัดที่ชัดเจนเกี่ยวกับจํานวนข้อมูลที่แสดง ข้อผิดพลาดจะไม่แสดงข้อมูล ระบบจะไม่รวมแถวและคอลัมน์ที่ว่างเปล่าต่อท้าย
วิธีการรับแบบเดี่ยวและแบบเป็นกลุ่มจะอธิบายไว้ด้านล่าง ดูตัวอย่างการดำเนินการอ่านขั้นพื้นฐานได้ที่การอ่านขั้นพื้นฐาน
อ่านช่วงเดียว
หากต้องการอ่านช่วงค่าเดียวจากสเปรดชีต ให้ใช้คำขอ spreadsheets.values.get
ดังนี้
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
ระบบจะแสดงการตอบกลับคําขอนี้เป็นออบเจ็กต์ ValueRange
อ่านหลายช่วง
หากต้องการอ่านช่วงค่าที่ไม่ต่อเนื่องหลายช่วงจากสเปรดชีต ให้ใช้คำขอ spreadsheets.values.batchGet
ที่ให้คุณระบุช่วงหลายช่วงเพื่อดึงข้อมูล
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
การตอบกลับคําขอนี้จะแสดงผลเป็นออบเจ็กต์ BatchGetValuesResponse
ที่มี spreadsheetId
และรายการออบเจ็กต์ ValueRange
เขียน
หากต้องการเขียนลงในชีต คุณต้องมีรหัสสเปรดชีต ช่วงของเซลล์ใน A1 และข้อมูลที่ต้องการเขียนภายในออบเจ็กต์เนื้อหาคำขอที่เหมาะสม ดูข้อมูลเพิ่มเติมเกี่ยวกับรหัสสเปรดชีตและรูปแบบ A1 ได้ที่ ภาพรวมของ Google Sheets API
การอัปเดตต้องใช้พารามิเตอร์ ValueInputOption
ที่ถูกต้อง
สำหรับอัปเดตแบบเดี่ยว พารามิเตอร์การค้นหานี้เป็นพารามิเตอร์ที่ต้องระบุ สําหรับการอัปเดตแบบเป็นกลุ่ม คุณต้องใช้พารามิเตอร์นี้ในเนื้อหาคําขอ ValueInputOption
จะควบคุมวิธีตีความข้อมูลอินพุตและจะแยกวิเคราะห์สตริงอินพุตหรือไม่ ตามที่อธิบายไว้ในตารางต่อไปนี้
ValueInputOption |
คำอธิบาย |
---|---|
RAW |
ระบบจะไม่แยกวิเคราะห์ข้อมูลที่ป้อนและจะแทรกเป็นสตริง เช่น อินพุต "=1+2" จะวางสตริง "=1+2" ในเซลล์ ไม่ใช่สูตร (ค่าที่ไม่ใช่สตริง เช่น บูลีนหรือตัวเลขจะถือว่าเป็น RAW เสมอ) |
USER_ENTERED |
ระบบจะแยกวิเคราะห์อินพุตเหมือนกับที่ป้อนลงใน UI ของชีต เช่น "1 มี.ค. 2016" จะกลายเป็นวันที่ และ "=1+2" จะกลายเป็นสูตร ระบบยังอนุมานรูปแบบได้ด้วย ดังนั้น "$100.15" จะกลายเป็นตัวเลขที่มีการจัดรูปแบบสกุลเงิน |
วิธีการอัปเดตแบบเดี่ยวและแบบเป็นกลุ่มจะอธิบายไว้ด้านล่าง ดูตัวอย่างการดำเนินการเขียนขั้นพื้นฐานได้ที่การเขียนขั้นพื้นฐาน
เขียนไปยังช่วงเดียว
หากต้องการเขียนข้อมูลไปยังช่วงเดียว ให้ใช้คำขอ spreadsheets.values.update
ดังนี้
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
เนื้อความของคำขออัปเดตต้องเป็นออบเจ็กต์ ValueRange
แต่มีเพียงช่อง values
เท่านั้นที่ต้องกรอก หากระบุ range
นั้นต้องตรงกับช่วงใน URL ใน ValueRange
คุณระบุmajorDimension
ของไฟล์ได้ (ไม่บังคับ)
โดยค่าเริ่มต้น ระบบจะใช้ ROWS
หากระบุ COLUMNS
ระบบจะเขียนอาร์เรย์ภายในแต่ละรายการลงในคอลัมน์แทนแถว
เมื่ออัปเดต ระบบจะข้ามค่าที่ไม่มีข้อมูล หากต้องการล้างข้อมูล ให้ใช้สตริงเปล่า ("")
พารามิเตอร์เขียนหลายช่วง
หากต้องการเขียนช่วงที่ไม่ต่อเนื่องหลายช่วง ให้ใช้คำขอ spreadsheets.values.batchUpdate
ดังนี้
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
เนื้อความของคำขออัปเดตแบบเป็นกลุ่มต้องเป็นออบเจ็กต์ BatchUpdateValuesRequest
ซึ่งมี ValueInputOption
และรายการออบเจ็กต์ ValueRange
(1 รายการสำหรับแต่ละช่วงการเขียน) ออบเจ็กต์ ValueRange
แต่ละรายการจะระบุ range
, majorDimension
และข้อมูลอินพุตของตัวเอง
ต่อท้ายค่า
หากต้องการเพิ่มข้อมูลต่อจากตารางข้อมูลในชีต ให้ใช้คำขอ spreadsheets.values.append
ดังนี้
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
เนื้อความของคำขออัปเดตต้องเป็นออบเจ็กต์ ValueRange
แต่มีเพียงช่อง values
เท่านั้นที่ต้องกรอก หากระบุ range
นั้นต้องตรงกับช่วงใน URL ใน ValueRange
คุณระบุmajorDimension
ของไฟล์ได้ (ไม่บังคับ)
โดยค่าเริ่มต้น ระบบจะใช้ ROWS
หากระบุ COLUMNS
ระบบจะเขียนอาร์เรย์ภายในแต่ละรายการลงในคอลัมน์แทนแถว
ช่วงอินพุตจะใช้เพื่อค้นหาข้อมูลที่มีอยู่และค้นหา "ตาราง" ภายในช่วงนั้น ระบบจะเพิ่มค่าต่อท้ายแถวถัดไปของตาราง โดยเริ่มจากคอลัมน์แรกของตาราง ตัวอย่างเช่น Sheet1
ที่มีลักษณะดังนี้
A | ข | C | D | E | |
1 | x | y | z | ||
2 | x | y | z | ||
3 | |||||
4 | x | y | |||
5 | y | z | |||
6 | x | y | z | ||
7 |
ชีตมี 2 ตาราง ได้แก่ A1:C2
และ B4:D6
ค่าต่อท้ายจะเริ่มต้นที่ B7
สำหรับอินพุต range
ทั้งหมดต่อไปนี้
Sheet1
เนื่องจากจะตรวจสอบข้อมูลทั้งหมดในสเปรดชีตและพิจารณาว่าตารางที่B4:D6
เป็นตารางสุดท้ายB4
หรือC5:D5
เนื่องจากทั้ง 2 รายการอยู่ในตารางB4:D6
B2:D4
เนื่องจากตารางสุดท้ายในช่วงคือตารางB4:D6
(แม้ว่าจะมีตารางA1:C2
ด้วยก็ตาม)A3:G10
เนื่องจากตารางสุดท้ายในช่วงคือตารางB4:D6
(แม้ว่าจะเริ่มต้นก่อนและสิ้นสุดหลังจากตารางดังกล่าว)
อินพุต range
ต่อไปนี้จะไม่เริ่มเขียนที่ B7
A1
จะเริ่มเขียนที่A3
เนื่องจากอยู่ในตารางA1:C2
E4
จะเริ่มเขียนที่E4
เนื่องจากไม่ได้อยู่ในตารางใดๆ (A4
จะเริ่มเขียนที่A4
ด้วยเหตุผลเดียวกัน)
นอกจากนี้ คุณยังเลือกได้ว่าจะเขียนทับข้อมูลที่มีอยู่หลังจากการอัปเดตตารางหรือแทรกแถวใหม่สำหรับข้อมูลใหม่ โดยค่าเริ่มต้น อินพุตจะเขียนทับข้อมูลหลังจากตาราง หากต้องการเขียนข้อมูลใหม่ลงในแถวใหม่ ให้ใช้ InsertDataOption
แล้วระบุ insertDataOption=INSERT_ROWS
ดูข้อมูลเพิ่มเติมเกี่ยวกับขีดจำกัดของเซลล์และแถวในชีตได้ที่หัวข้อไฟล์ที่เก็บไว้ใน Google ไดรฟ์ได้