API Google Trang tính cho phép bạn đọc các giá trị trong các ô, dải ô, các tập hợp dải ô và toàn bộ trang tính. Các ví dụ trên trang này minh hoạ một số thao tác đọc phổ biến với tài nguyên spreadsheets.values. Bạn cũng có thể đọc các giá trị của ô bằng phương thức spreadsheets.get, nhưng thường thì spreadsheets.values.get hoặc spreadsheets.values.batchGet sẽ dễ dàng hơn.
Những ví dụ này được trình bày dưới dạng các yêu cầu HTTP để đảm bảo trung lập về ngôn ngữ. Để tìm hiểu cách triển khai lượt đọc bằng nhiều ngôn ngữ thông qua thư viện ứng dụng API của Google, hãy xem bài viết Đọc và ghi giá trị của ô.
Trong những ví dụ này, phần giữ chỗ SPREADSHEET_ID cho biết nơi bạn sẽ cung cấp mã nhận dạng bảng tính. Bạn có thể tìm thấy mã này từ URL của bảng tính. Các dải ô để đọc được chỉ định bằng ký hiệu A1 trong URL yêu cầu. Dải ô ví dụ là Sheet1!A1:D5.
Dữ liệu nguồn
Đối với những ví dụ này, giả sử bảng tính đang được đọc có dữ liệu nguồn sau đây trong trang tính đầu tiên ("Sheet1"). Các chuỗi trong hàng đầu tiên là nhãn cho từng cột. Để xem ví dụ về cách đọc từ các trang tính khác trong bảng tính của bạn, hãy xem phần Ký hiệu A1.
| Đáp | B | C | D | |
| 1 | Mục | Chi phí | Còn hàng | Ngày giao hàng |
| 2 | Vòng đu quay | $20,5 | 4 | 1/3/2016 |
| 3 | Cửa ra vào | đô la Hong Kong | 2 | 15/3/2016 |
| 4 | Động cơ | 100 đô la | 1 | Ngày 20 tháng 3 năm 2016 |
| 5 | Tổng số | $135,5 | 7 | Ngày 20 tháng 3 năm 2016 |
Đọc một phạm vi
Mã mẫu spreadsheets.values.get sau đây cho biết cách đọc các giá trị trong dải ô Sheet1!A1:D5 và trả về các giá trị đó trong phản hồi. Các hàng và cột ở cuối sẽ bị loại bỏ.
Giao thức yêu cầu sẽ hiển thị ở đây.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5
Phản hồi bao gồm một đối tượng ValueRange mô tả các giá trị phạm vi. Trường majorDimension cho biết các mảng là danh sách giá trị được sắp xếp theo hàng.
{
"range": "Sheet1!A1:D5",
"majorDimension": "ROWS",
"values": [
["Item", "Cost", "Stocked", "Ship Date"],
["Wheel", "$20.50", "4", "3/1/2016"],
["Door", "$15", "2", "3/15/2016"],
["Engine", "$100", "1", "30/20/2016"],
["Totals", "$135.5", "7", "3/20/2016"]
],
}
Đọc một dải ô được nhóm theo cột
Mã mẫu spreadsheets.values.get sau đây cho biết cách đọc các giá trị trong dải ô Sheet1!A1:D3 và trả về các giá trị đó trong phản hồi, nhưng được nhóm theo cột. Các hàng và cột ở cuối sẽ bị bỏ qua.
Giao thức yêu cầu sẽ hiển thị ở đây.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS
Phản hồi bao gồm một đối tượng ValueRange mô tả các giá trị phạm vi. Trường majorDimension cho biết các mảng là danh sách giá trị được sắp xếp theo cột.
{
"range": "Sheet1!A1:D3",
"majorDimension": "COLUMNS",
"values": [
["Item", "Wheel", "Door"],
["Cost", "$20.50", "$15"],
["Stocked", "4", "2"],
["Ship Date", "3/1/2016", "3/15/2016"]
],
}
Đọc một dải ô có các tuỳ chọn kết xuất
Mã mẫu spreadsheets.values.get sau đây cho biết cách đọc các giá trị từ dải ô Sheet1!A1:D5 và trả về các giá trị đó trong phản hồi, nhưng sử dụng các tuỳ chọn hiển thị để quản lý cách thông tin đó được trả về. Chế độ cài đặt ValueRenderOption của FORMULA cho biết rằng công thức sẽ được trả về thay vì giá trị đã tính và chế độ cài đặt DateTimeRenderOption của SERIAL_NUMBER cho biết rằng ngày sẽ được trả về dưới dạng số.
Bạn cũng có thể sử dụng các chế độ cài đặt khác. Các hàng và cột ở cuối sẽ bị bỏ qua.
Giao thức yêu cầu sẽ hiển thị ở đây.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?
valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER
Phản hồi bao gồm một đối tượng ValueRange mô tả các giá trị phạm vi. Trường majorDimension cho biết các mảng là danh sách giá trị được sắp xếp theo hàng.
{
"range": "Sheet1!A1:D5",
"majorDimension": "ROWS",
"values": [
["Item", "Cost", "Stocked", "Ship Date"],
["Wheel", "$20.50", "4", "42430"],
["Door", "$15", "2", "42444"],
["Engine", "$100", "1", "42449"],
["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
],
}
Đọc nhiều dải ô
Mã mẫu spreadsheets.values.batchGet sau đây cho biết cách đọc các giá trị trong các dải ô Sheet1!B:B và Sheet1!D:D và trả về các giá trị đó trong phản hồi. Chế độ cài đặt ValueRenderOption của UNFORMATTED_VALUE cho biết rằng các giá trị được tính toán nhưng không được định dạng trong phản hồi. Các hàng và cột ở cuối sẽ bị loại bỏ.
Giao thức yêu cầu sẽ hiển thị ở đây.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS
Phản hồi cho lệnh gọi phương thức này bao gồm một đối tượng có mã nhận dạng bảng tính và một mảng các đối tượng ValueRange tương ứng với từng dải ô được yêu cầu, được liệt kê theo thứ tự được yêu cầu. Trường majorDimension cho biết các mảng là danh sách giá trị được sắp xếp theo cột. Ví dụ:
{
"spreadsheetId": SPREADSHEET_ID,
"valueRanges": [
{
"range": "Sheet1!B1:B1000",
"majorDimension": "COLUMNS",
"values": [
["Cost",20.5,15,100,135.5]
]
},
{
"range": "Sheet1!D1:D1000",
"majorDimension": "COLUMNS",
"values": [
["Ship Date",42430,42444,42449,42449]
]s
}
]
}
Đọc nhiều dải ô trên nhiều trang tính
Mã mẫu spreadsheets.values.batchGet sau đây cho biết cách đọc các giá trị từ các dải ô trong các trang tính Sheet1!A1:D5, Sản phẩm!D1:D100 và Sales!E4:F6 và trả về các giá trị đó trong phản hồi. Chế độ cài đặt ValueRenderOption của UNFORMATTED_VALUE cho biết rằng các giá trị được tính toán nhưng không được định dạng trong phản hồi. Các hàng và cột ở cuối sẽ bị loại bỏ.
Giao thức yêu cầu sẽ hiển thị ở đây.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
ranges=Sheet1!A1:D5&ranges=Products!D1:D100&ranges=Sales!E4:F6&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS
Phản hồi cho lệnh gọi phương thức này bao gồm một đối tượng có mã nhận dạng bảng tính và một mảng các đối tượng ValueRange tương ứng với từng dải ô được yêu cầu, được liệt kê theo thứ tự được yêu cầu. Trường majorDimension cho biết các mảng là danh sách giá trị được sắp xếp theo cột. Ví dụ:
{
"spreadsheetId": SPREADSHEET_ID,
"valueRanges": [
{
"range": "Sheet1!A1:D5",
"majorDimension": "COLUMNS",
"values": [
[...],
[...]
]
},
{
"range": "Products!D1:D100",
"majorDimension": "COLUMNS",
"values": [
[...]
]
},
{
"range": "Sales!E4:F6",
"majorDimension": "COLUMNS",
"values": [
[...],
[...]
]
}
]
}