สเปรดชีตสามารถมีชีตได้หลายรายการ โดยแต่ละแผ่นงานจะมีแถวหรือคอลัมน์กี่แถวก็ได้ 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 นี้ต้องตรงกับช่วงใน 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 นี้ต้องตรงกับช่วงใน URL ใน ValueRange
คุณจะระบุ
majorDimension
หรือไม่ก็ได้
ระบบจะใช้ ROWS
โดยค่าเริ่มต้น หากระบุ COLUMNS
อาร์เรย์ภายในแต่ละรายการจะเขียนเป็นคอลัมน์แทนแถว
ระบบจะใช้ช่วงอินพุตเพื่อค้นหาข้อมูลที่มีอยู่และหา "ตาราง" ภายในช่วงดังกล่าว ระบบจะเพิ่มค่าต่อท้ายแถวถัดไปของตาราง โดยเริ่มจากคอลัมน์แรกของตาราง ตัวอย่างเช่น ลองพิจารณา Sheet1
ที่มีลักษณะดังนี้
A | B | C | ว | 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
เพราะทั้งคู่อยู่ในตาราง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 ไดรฟ์ได้