Bảng tính có thể có nhiều trang tính, mỗi trang tính có số lượng hàng bất kỳ
hoặc cột. Ô là một vị trí ở
giao điểm của một hàng và cột cụ thể, đồng thời có thể chứa giá trị dữ liệu. Chiến lược phát hành đĩa đơn
API Google Trang tính cung cấp
spreadsheets.values
để cho phép đọc và ghi 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
bạn cần phải 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
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 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ượt đọc hoặc cập nhật với
Phương thức batchGet
và batchUpdate
(tương ứng) vì phương thức này được cải thiện
sự hiệu quả.
Bạn có thể tìm thấy ví dụ về từng phương pháp này trên trang Cơ bản đọc và Cơ bản viết mẫu. Để xem tất cả các mẫu, hãy tham khảo và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 và tệp A1
cho dải ô. 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ã bảng tính và ký hiệu A1, hãy xem API Google Trang tính
Tổng quan.
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ô. Đối với các mẫu cơ bản các thao tác đọc, hãy xem phần Đọc cơ bản.
Đọc một phạm vi
Để đọc một khoảng giá trị duy nhất trong bảng tính, hãy sử dụng
spreadsheets.values.get
yêu cầu:
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
ValueRange
.
Đọc nhiều dải ô
Để đọc nhiều dải giá trị gián đoạn trên một bảng tính, hãy sử dụng
spreadsheets.values.batchGet
yêu cầu cho phép bạn chỉ định một số dải ô cần 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
BatchGetValuesResponse
đối tượng chứa spreadsheetId
và danh sách
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 A1 và dữ liệu bạn muốn ghi trong 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 Tổng quan về API Google Trang tính.
Bản cập nhật yêu cầu một thuộc tính hợp lệ
Tham số ValueInputOption
.
Đố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ô,
tham số này là bắt buộc trong nội dung yêu cầu. Chế độ kiểm soát ValueInputOption
cách dữ liệu đầu vào được diễn giải và liệu chuỗi đầu vào có được phân tích cú pháp hay không
không, như được mô tả trong bảng sau:
ValueInputOption |
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, không phải công thức, "=1+2" trong ô. (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" sẽ trở thành một công thức. Định dạng cũng có thể được suy ra, vì vậy "$100,15" sẽ trở thành số có định dạng đơn vị tiền tệ. |
Dưới đây là các phương thức cập nhật duy nhất và theo lô. Đối với các mẫu cơ bản các thao tác ghi, 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
spreadsheets.values.update
yêu cầu:
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à
ValueRange
mặc dù trường bắt buộc duy nhất là values
. Nếu bạn chỉ định range
,
phải khớp với dải ô trong URL. Trong ValueRange
, bạn có thể tuỳ ý chỉ định
của
majorDimension
.
Theo mặc định, ROWS
sẽ được sử dụng. Nếu COLUMNS
được chỉ định, mỗi mảng bên trong sẽ là
đượ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. Để xóa dữ liệu, hãy sử dụng thuộc tính trống chuỗi ("").
Viết nhiều dải ô
Nếu muốn viết nhiều dải ô không liên tục, bạn có thể sử dụng
spreadsheets.values.batchUpdate
yêu cầu:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Phần nội dung của yêu cầu cập nhật hàng loạt phải là
BatchUpdateValuesRequest
đối tượng này, chứa ValueInputOption
và danh sách
ValueRange
(một đối tượng cho mỗi dải ô được viết). Mỗi đối tượng ValueRange
chỉ định một đối tượng riêng
range
, majorDimension
và dữ liệu đầu vào.
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
spreadsheets.values.append
yêu cầu:
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à
ValueRange
mặc dù trường bắt buộc duy nhất là values
. Nếu bạn chỉ định range
,
phải khớp với dải ô trong URL. Trong ValueRange
, bạn có thể tuỳ ý chỉ định
của
majorDimension
.
Theo mặc định, ROWS
sẽ được sử dụng. Nếu COLUMNS
được chỉ định, mỗi mảng bên trong sẽ là
được ghi vào một cột thay vì một hàng.
Dải ô nhập dữ liệu được dùng để tìm dữ liệu hiện có và tìm một "bảng" trong
phạm vi đó. Các giá trị được nối 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 lúc B7
cho tất cả các đầ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ù 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 có muốn ghi đè dữ liệu hiện có sau
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 hàng mới, hãy sử dụng
InsertDataOption
rồi 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 Các tệp bạn có thể lưu trữ trong Google Drive.