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à 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. Google Sheets API cung cấp tài nguyên spreadsheets.values để cho phép đọc và ghi các 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 |
|---|---|---|
| Một dải | spreadsheets.values.get |
spreadsheets.values.update |
| Nhiều dải | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
| Nối | 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 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à Ghi cơ bản. Để xem tất cả các mẫu, hãy tham khảo trang tổng quan về các mẫu.
Đọc
Để đọc 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ã nhận dạng 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 sẽ 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 sẽ bị bỏ qua.
Các phương thức lấy đơn lẻ và theo lô được mô tả dưới đây. Để xem các mẫu về 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ị duy nhất từ bảng tính, hãy 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 một đố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. Yêu cầu này 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 một đối tượng BatchGetValuesResponse chứa spreadsheetId và một 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 ký hiệu 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.
Bản cập nhật yêu cầu một tham số ValueInputOption hợp lệ.
Đối với các bản cập nhật đơn lẻ, đây là một 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 có 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 các 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 một chuỗi. Ví dụ: đầu vào "=1+2" sẽ đặt chuỗi "=1+2" chứ không phải công thức vào ô. (Các giá trị không phải là chuỗi như giá trị 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ể được nhập vào giao diện người dùng của Trang tính. Ví dụ: "1/3/2016" sẽ trở thành ngày và "=1+2" sẽ trở thành công thức. Bạn cũng có thể suy luận định dạng, vì vậy "100,15 USD" sẽ trở thành một số có định dạng tiền tệ. |
Các phương thức cập nhật đơn lẻ và hàng loạt được mô tả bên dưới. Để xem các mẫu về thao tác ghi cơ bản, hãy xem phần Thao tác 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à một đố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ì thông số này phải khớp với phạm vi trong URL. Trong ValueRange, bạn có thể tuỳ ý chỉ định majorDimension của nó.
Theo mặc định, ROWS sẽ được dùng. Nếu COLUMNS được chỉ định, 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 dùng một chuỗi trống ("").
Ghi nhiều dải ô
Nếu muốn viết nhiều dải ô không liên tục, bạn có thể 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 đó có một ValueInputOption và một 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.
Thêm giá trị
Để thêm 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
PHP
Python
Ruby
Nội dung của yêu cầu cập nhật phải là một đố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ì thông số này phải khớp với phạm vi trong URL. Trong ValueRange, bạn có thể tuỳ ý chỉ định majorDimension của nó.
Theo mặc định, ROWS sẽ được dùng. Nếu COLUMNS được chỉ định, mỗi mảng bên trong sẽ được ghi vào một cột thay vì một hàng.
Phạm vi đầ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 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ị được thêm vào sẽ bắt đầu từ B7 cho tất cả các đầu vào range sau đây:
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:D6là bảng cuối cùng.B4hoặ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 bảng này).
Các dữ liệu đầu vào range sau đây sẽ không bắt đầu ghi vào lúc B7:
A1sẽ bắt đầu viết tạiA3, vì đó là trong bảngA1:C2.E4sẽ bắt đầu viết tạiE4vì không có trong bảng nào. (A4cũng sẽ bắt đầu viết ởA4vì những lý do tương tự.)
Ngoài ra, bạn có thể chọn ghi đè dữ liệu hiện có sau khi có một bảng hoặc chèn các 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 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.