สเปรดชีตมีชีตได้หลายรายการ โดยแต่ละชีตจะมีแถวหรือคอลัมน์กี่แถวก็ได้ cell คือตำแหน่งที่อยู่บริเวณสี่แยกของแถวและคอลัมน์หนึ่งๆ และอาจมีค่าข้อมูล Google Sheets 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 |
แถว |
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
ซึ่งมีลักษณะดังนี้
ก | B | C | D | จ. | |
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
เนื่องจากทั้งคู่อยู่ในตาราง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 ไดรฟ์ได้