Bảng tính có thể có nhiều trang tính, mỗi trang tính có số hàng hoặc cột bất kỳ. Ô là một vị trí tại giao điểm của một hàng và cột cụ thể, đồng thời có thể chứa một giá trị dữ liệu. API Google Trang tính cung cấp tài nguyên spreadsheets.values
để cho phép đọc và ghi giá trị.
Trang này mô tả những thông tin cơ bản về cách sử dụng tài nguyên spreadsheets.values
. Nếu cần chèn hàng hoặc cập nhật định dạng và các thuộc tính khác trong một trang tính, bạn phải sử dụng phương thức spreadsheets.batchUpdate
được mô tả trong phần Cập nhật bảng tính.
Phương thức
Tài nguyên spreadsheets.values
cung cấp các phương thức sau để đọc và ghi giá trị, mỗi phương thức cho một tác vụ cụ thể:
Quyền truy cập vào dải ô | Đọc sách | Viết |
---|---|---|
Phạm vi đơn | spreadsheets.values.get |
spreadsheets.values.update |
Nhiều dải ô | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
Thêm vào | spreadsheets.values.append |
Nhìn chung, bạn nên kết hợp nhiều lần đọc hoặc cập nhật với các phương thức batchGet
và batchUpdate
(tương ứng), vì điều này giúp cải thiện hiệu quả.
Bạn có thể tìm thấy ví dụ về từng phương thức này trên các trang mẫu Đọc cơ bản và Viết cơ bản. Để xem tất cả mẫu, hãy tham khảo trang tổng quan về mẫu.
Đọc
Để đọc giá trị dữ liệu từ một trang tính, bạn cần có mã nhận dạng bảng tính và ký hiệu A1 cho dải ô. Việc chỉ định dải ô mà không có mã trang tính (A1:B2
) nghĩa là yêu cầu sẽ thực thi trên trang tính đầu tiên trong bảng tính. Để biết thêm thông tin về mã nhận dạng bảng tính và ký hiệu A1, hãy xem phần Tổng quan về API Google Trang tính.
Một số tham số truy vấn không bắt buộc kiểm soát định dạng của kết quả:
Tham số định dạng | Giá trị mặc định |
---|---|
majorDimension |
HÀNG |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
Xin lưu ý rằng bạn chỉ nên sử dụng dateTimeRenderOption
nếu valueRenderOption
không phải là FORMATTED_VALUE
.
Không có giới hạn rõ ràng về lượng dữ liệu được trả về. Lỗi không trả về dữ liệu. Các hàng và cột cuối cùng trống sẽ bị bỏ qua.
Phương thức lấy số ít và phương thức lấy hàng loạt được mô tả dưới đây. Để xem các mẫu thao tác đọc cơ bản, hãy xem phần Đọc cơ bản.
Đọc một dải ô
Để đọc một dải ô giá trị từ bảng tính, hãy sử dụng yêu cầu spreadsheets.values.get
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Phản hồi cho yêu cầu này được trả về dưới dạng đối tượng ValueRange
.
Đọc nhiều dải ô
Để đọc nhiều dải ô giá trị không liên tục từ một bảng tính, hãy sử dụng yêu cầu spreadsheets.values.batchGet
cho phép bạn chỉ định một số dải ô để truy xuất:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Phản hồi cho yêu cầu này được trả về dưới dạng một đối tượng BatchGetValuesResponse
chứa spreadsheetId
và danh sách các đối tượng ValueRange
.
Viết
Để ghi vào một trang tính, bạn cần có mã nhận dạng bảng tính, dải ô theo ký hiệu A1 và dữ liệu bạn muốn ghi trong đối tượng nội dung yêu cầu thích hợp. Để biết thêm thông tin về mã bảng tính và ký hiệu A1, hãy xem phần Tổng quan về API Google Trang tính.
Bản cập nhật yêu cầu tham số ValueInputOption
hợp lệ.
Đối với các bản cập nhật đơn lẻ, đây là tham số truy vấn bắt buộc. Đối với các bản cập nhật hàng loạt, tham số này là bắt buộc trong phần nội dung yêu cầu. ValueInputOption
kiểm soát cách diễn giải dữ liệu đầu vào và liệu chuỗi đầu vào có được phân tích cú pháp hay không, như mô tả trong bảng sau:
ValueInputOption |
Mô tả |
---|---|
RAW |
Dữ liệu đầu vào không được phân tích cú pháp và được chèn dưới dạng chuỗi. Ví dụ: dữ liệu đầu vào "=1+2" sẽ đặt chuỗi "=1+2" chứ không phải công thức "=1+2" vào ô. (Các giá trị không phải chuỗi như boolean hoặc số luôn được xử lý dưới dạng RAW .) |
USER_ENTERED |
Dữ liệu đầu vào được phân tích cú pháp giống như khi được nhập vào giao diện người dùng của Trang tính. Ví dụ: "Ngày 1 tháng 3 năm 2016" sẽ trở thành một ngày và "=1+2" sẽ trở thành một công thức. Bạn cũng có thể suy luận định dạng, vì vậy "100,15 đô la Mỹ" sẽ trở thành một số có định dạng tiền tệ. |
Phương thức cập nhật đơn và hàng loạt được mô tả bên dưới. Để xem các mẫu thao tác ghi cơ bản, hãy xem phần Ghi cơ bản.
Ghi vào một dải ô
Để ghi dữ liệu vào một dải ô, hãy sử dụng yêu cầu spreadsheets.values.update
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Nội dung của yêu cầu cập nhật phải là đối tượng ValueRange
, mặc dù trường bắt buộc duy nhất là values
. Nếu được chỉ định, range
phải khớp với phạm vi trong URL. Trong ValueRange
, bạn có thể chỉ định majorDimension
một cách tuỳ ý.
Theo mặc định, ROWS
được sử dụng. Nếu bạn chỉ định COLUMNS
, thì mỗi mảng bên trong sẽ được ghi vào một cột thay vì một hàng.
Khi cập nhật, các giá trị không có dữ liệu sẽ bị bỏ qua. Để xoá dữ liệu, hãy sử dụng một chuỗi trống ("").
Ghi nhiều dải ô
Nếu muốn ghi nhiều dải ô không liên tục, bạn có thể sử dụng yêu cầu spreadsheets.values.batchUpdate
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Nội dung của yêu cầu cập nhật hàng loạt phải là một đối tượng BatchUpdateValuesRequest
, trong đó chứa một ValueInputOption
và danh sách các đối tượng ValueRange
(một đối tượng cho mỗi dải ô được ghi). Mỗi đối tượng ValueRange
chỉ định range
, majorDimension
và dữ liệu đầu vào riêng.
Nối thêm giá trị
Để nối dữ liệu sau một bảng dữ liệu trong một trang tính, hãy sử dụng yêu cầu spreadsheets.values.append
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Nội dung của yêu cầu cập nhật phải là đối tượng ValueRange
, mặc dù trường bắt buộc duy nhất là values
. Nếu được chỉ định, range
phải khớp với phạm vi trong URL. Trong ValueRange
, bạn có thể chỉ định majorDimension
một cách tuỳ ý.
Theo mặc định, ROWS
được sử dụng. Nếu bạn chỉ định COLUMNS
, thì mỗi mảng bên trong sẽ được ghi vào một cột thay vì một hàng.
Dải ô đầu vào được dùng để tìm kiếm dữ liệu hiện có và tìm "bảng" trong phạm vi đó. Các giá trị được thêm vào hàng tiếp theo của bảng, bắt đầu bằng cột đầu tiên của bảng. Ví dụ: hãy xem xét Sheet1
có dạng như sau:
A | B | C | D | E | |
1 | x | y | z | ||
2 | x | y | z | ||
3 | |||||
4 | x | y | |||
5 | y | z | |||
6 | x | y | z | ||
7 |
Có 2 bảng trong trang tính: A1:C2
và B4:D6
. Các giá trị được thêm vào sẽ bắt đầu từ B7
cho tất cả các giá trị đầu vào range
sau:
Sheet1
, vì hàm này sẽ kiểm tra tất cả dữ liệu trong trang tính và xác định rằng bảng tạiB4:D6
là bảng cuối cùng.B4
hoặcC5:D5
, vì cả hai đều nằm trong bảngB4:D6
.B2:D4
, vì bảng cuối cùng trong dải ô là bảngB4:D6
(mặc dù bảng này cũng chứa bảngA1:C2
).A3:G10
, vì bảng cuối cùng trong phạm vi là bảngB4:D6
(mặc dù bắt đầu trước và kết thúc sau bảng này).
Dữ liệu đầu vào range
sau đây sẽ không bắt đầu ghi tại B7
:
A1
sẽ bắt đầu ghi tạiA3
, vì đó là trong bảngA1:C2
.E4
sẽ bắt đầu ghi tạiE4
vì không nằm trong bảng nào. (A4
cũng sẽ bắt đầu ghi tạiA4
vì những lý do tương tự.)
Ngoài ra, bạn có thể chọn ghi đè dữ liệu hiện có sau một bảng hoặc chèn hàng mới cho dữ liệu mới. Theo mặc định, dữ liệu đầu vào sẽ ghi đè dữ liệu sau bảng. Để ghi dữ liệu mới vào các hàng mới, hãy sử dụng InsertDataOption
và chỉ định insertDataOption=INSERT_ROWS
.
Để tìm hiểu thêm về giới hạn ô và hàng trong Trang tính, hãy xem bài viết Các tệp bạn có thể lưu trữ trong Google Drive.