Bảng tính có thể có nhiều trang tính, mỗi trang tính có số lượng 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ể và có thể chứa 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ả 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 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 dải ô | spreadsheets.values.get |
spreadsheets.values.update |
Nhiều dải ô | 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ầ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 sẽ 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 trong số 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à chú thích 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ẽ 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 bài viết 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:
Thông số định dạng | Giá trị mặc định |
---|---|
majorDimension |
Hàm ROWS |
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 sẽ bị loại bỏ.
Dưới đây là các phương thức nhận số ít và theo lô. Để xem mẫu 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 trên 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 một đối tượng ValueRange
.
Đọc nhiều dải ô
Để đọc nhiều dải ô không liên tục trên một bảng tính, hãy dùng yêu cầu spreadsheets.values.batchGet
cho phép bạn chỉ định một số dải ô cần 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 mà 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ã bảng tính và ký hiệu A1, hãy xem nội dung Tổng quan về API Google Trang tính.
Các 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. Để cập nhật theo lô, bạn phải cung cấp 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 nhập vào không được phân tích cú pháp và chèn vào dưới dạng chuỗi. Ví dụ: giá trị 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ý là RAW .) |
USER_ENTERED |
Dữ liệu đầu vào được phân tích cú pháp chính xác như thể nó được nhập vào giao diện người dùng 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. Bạn cũng có thể suy ra định dạng, vì vậy "$100,15" trở thành số có định dạng tiền tệ. |
Dưới đây là các phương thức cập nhật duy nhất và theo lô. Để biết mẫu về các 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
, thì thuộc tính này phải khớp với dải ô trong URL. Trong ValueRange
, bạn có thể tuỳ ý chỉ định majorDimension
của lớp đó.
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 thành 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 ("").
Viết 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
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 đã ghi). Mỗi đối tượng ValueRange
chỉ định range
, majorDimension
và dữ liệu đầu vào riêng.
Thêm giá trị
Để thêm 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
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
, thì thuộc tính này phải khớp với dải ô trong URL. Trong ValueRange
, bạn có thể tuỳ ý chỉ định majorDimension
của lớp đó.
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 thành một cột thay vì một hàng.
Dải ô nhập dữ liệu đượ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:
Đáp | 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ị được thêm sẽ bắt đầu từ B7
cho tất cả các đầu vào range
sau đây:
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 giá trị nhập 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 viết lúcE4
vì hàm này không nằm trong bất kỳ bảng nào. (A4
cũng sẽ bắt đầu viết lúcA4
vì những 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 bảng hay chèn hàng mới cho dữ liệu mới. Theo mặc định, dữ liệu nhập sẽ ghi đè dữ liệu sau bảng. Để ghi dữ liệu mới vào 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.