Bảng tính có thể có nhiều trang tính, trong đó mỗi trang tính có số lượng hàng hoặc cột bất kỳ. Ô là vị trí tại điểm giao nhau của một hàng và cột cụ thể, và 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 các giá trị.
Trang này mô tả các khái niệm cơ bản về việc 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 dành cho một tác vụ cụ thể:
Quyền truy cập phạm vi | Đọc sách | Viết |
---|---|---|
Một phạm vi | spreadsheets.values.get |
spreadsheets.values.update |
Nhiều phạm vi | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
Đang thêm | spreadsheets.values.append |
Nhìn chung, bạn nên kết hợp nhiều lượt đọc hoặc cập nhật bằng phương thức batchGet
và batchUpdate
(tương ứng) để cải thiện hiệu suất.
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ả các mẫu, hãy tham khảo trang tổng quan về mẫu.
Đã đọc
Để đọc giá trị dữ liệu trên 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
) có nghĩa là yêu cầu sẽ được 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 đầu ra:
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 trống ở cuối bị bỏ qua.
Các phương thức nhận số ít và hàng loạt được mô tả dưới đây. Để xem ví dụ về các thao tác đọc cơ bản, hãy xem phần Đọc cơ bản.
Đọc một phạm vi
Để đọc một dải giá trị duy nhất trong bảng tính, hãy sử dụng yêu cầu spreadsheets.values.get
:
Apps Script
Java
JavaScript
Node.js
1.199
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 phạm vi
Để đọ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
1.199
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 ô trong chú thích A1 và dữ liệu bạn muốn ghi trong một đối tượng nội dung yêu cầu thích hợp. Để 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 bài viết Tổng quan về API Google Trang tính.
Các bản cập nhật cần có một 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, bạn phải sử dụng tham số này trong 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 |
Nội dung 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ụ: nhập "=1+2" đặt chuỗi 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 chính xác như thể 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" trở thành ngày và "=1+2" trở thành công thức. Định dạng cũng có thể được dự đoán, vì vậy "$100,15" trở thành một số có định dạng tiền tệ. |
Các phương thức cập nhật số ít và cập nhật hàng loạt được mô tả dưới đây. Để xem các mẫu về thao tác ghi cơ bản, hãy xem phần Viết 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
1.199
Python
Ruby
Phần 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 bạn chỉ định range
, giá trị này phải khớp với dải ô trong URL. Trong ValueRange
, bạn có thể tuỳ ý chỉ định
majorDimension
của hàm đó.
Theo mặc định, ROWS
sẽ đượ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 viết nhiều phạm vi gián đoạn, bạn có thể sử dụng yêu cầu spreadsheets.values.batchUpdate
:
Apps Script
Java
JavaScript
Node.js
1.199
Python
Ruby
Phần nội dung của yêu cầu cập nhật hàng loạt phải là đối tượng BatchUpdateValuesRequest
, chứa ValueInputOption
và danh sách các đối tượng ValueRange
(một đối tượng cho mỗi phạm vi được ghi). Mỗi đối tượng ValueRange
chỉ định range
, majorDimension
và dữ liệu đầu vào riêng.
Thêm giá trị
Để nối dữ liệu sau một bảng dữ liệu trong trang tính, hãy sử dụng yêu cầu spreadsheets.values.append
:
Apps Script
Java
JavaScript
Node.js
1.199
Python
Ruby
Phần 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 bạn chỉ định range
, giá trị này phải khớp với dải ô trong URL. Trong ValueRange
, bạn có thể tuỳ ý chỉ định
majorDimension
của hàm đó.
Theo mặc định, ROWS
sẽ đượ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 một "bảng" trong dải ô đó. Các giá trị được thêm vào hàng tiếp theo của bảng, bắt đầu từ 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 | năm | z | ||
2 | x | năm | z | ||
3 | |||||
4 | x | năm | |||
5 | năm | z | |||
6 | x | năm | z | ||
7 |
Có 2 bảng trong trang tính: A1:C2
và B4:D6
. Các giá trị đã thêm sẽ bắt đầu từ B7
cho tất cả các giá trị đầu vào range
sau:
Sheet1
, vì công cụ 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 dải ô là bảngB4:D6
(mặc dù bắt đầu trước và kết thúc sau).
Các dữ liệu đầu vào range
sau đây sẽ không bắt đầu ghi lúc B7
:
A1
sẽ bắt đầu viết lúcA3
vì hàm này nằm trong bảngA1:C2
.E4
sẽ bắt đầu ghi tạiE4
vì nó không nằm trong bất kỳ bảng nào. (A4
cũng sẽ bắt đầu viết tạiA4
vì lý do tương tự.)
Ngoài ra, bạn có thể chọn xem bạn muốn ghi đè dữ liệu hiện có sau một bảng hay 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 phần Tệp bạn có thể lưu trữ trong Google Drive.