API Google Trang tính cho phép bạn tạo và cập nhật biểu đồ trong bảng tính khi cần. Các ví dụ trên trang này minh hoạ cách bạn có thể thực hiện một số thao tác phổ biến trên biểu đồ bằng API Trang tính.
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 tính năng cập nhật theo lô cho nhiều ngôn ngữ bằng thư viện ứng dụng API của Google, hãy xem phần Cập nhật bảng tính.
Trong các ví dụ này, phần giữ chỗ SPREADSHEET_ID và SHEET_ID cho biết nơi bạn sẽ cung cấp các mã nhận dạng đó. Bạn có thể tìm thấy mã
bảng tính trong URL của bảng tính. Bạn có thể lấy mã trang tính bằng cách sử dụng phương thức spreadsheets.get. Các dải ô được chỉ định bằng ký hiệu A1. Dải ô ví dụ là Sheet1!A1:D5.
Ngoài ra, phần giữ chỗ CHART_ID cho biết mã của một biểu đồ nhất định. Bạn có thể đặt mã nhận dạng này khi tạo biểu đồ bằng API Trang tính hoặc cho phép API Trang tính tạo một biểu đồ cho bạn. Bạn có thể lấy mã nhận dạng của các biểu đồ hiện có bằng phương thức spreadsheets.get.
Cuối cùng, phần giữ chỗ SOURCE_SHEET_ID cho biết trang tính của bạn có dữ liệu nguồn. Trong những ví dụ như vậy, đây là bảng được liệt kê trong phần Dữ liệu nguồn trên biểu đồ.
Dữ liệu nguồn trên biểu đồ
Đối với những ví dụ này, giả sử bảng tính đang được sử dụng có dữ liệu nguồn sau đây trong trang tính đầu tiên ("Trang tính1"). 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 | E | |
| 1 | Số mô hình | Doanh số – Tháng 1 | Doanh số – Tháng 2 | Doanh số – Tháng 3 | Tổng doanh số |
| 2 | D–01X | 68 | Tăng 74 | 60 | 202 |
| 3 | FR-0B1 | 97 | 76 | 88 | 261 |
| 4 | P-034 | 27 | 49 | 32 | 108 |
| 5 | P-105 | 46 | 44 | 67 | 157 |
| 6 | W-11 | 75 | 68 | 87 | 230 |
| 7 | W-24 | Tăng 74 | 52 | 62 | 188 |
Thêm biểu đồ cột
Mã mẫu spreadsheets.batchUpdate sau đây cho biết cách sử dụng AddChartRequest để tạo biểu đồ cột từ dữ liệu nguồn, đặt biểu đồ đó vào một trang tính mới. Yêu cầu sẽ thực hiện những việc sau để định cấu hình biểu đồ:
- Đặt loại biểu đồ dưới dạng biểu đồ cột.
- Thêm chú giải vào cuối biểu đồ.
- Đặt tiêu đề trục và biểu đồ.
- Định cấu hình 3 chuỗi dữ liệu, đại diện cho doanh số bán hàng của 3 tháng trong khi sử dụng màu sắc và định dạng mặc định.
Giao thức yêu cầu được trình bày dưới đây.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"addChart": {
"chart": {
"spec": {
"title": "Model Q1 Sales",
"basicChart": {
"chartType": "COLUMN",
"legendPosition": "BOTTOM_LEGEND",
"axis": [
{
"position": "BOTTOM_AXIS",
"title": "Model Numbers"
},
{
"position": "LEFT_AXIS",
"title": "Sales"
}
],
"domains": [
{
"domain": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 0,
"endColumnIndex": 1
}
]
}
}
}
],
"series": [
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 1,
"endColumnIndex": 2
}
]
}
},
"targetAxis": "LEFT_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 2,
"endColumnIndex": 3
}
]
}
},
"targetAxis": "LEFT_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 3,
"endColumnIndex": 4
}
]
}
},
"targetAxis": "LEFT_AXIS"
}
],
"headerCount": 1
}
},
"position": {
"newSheet": true
}
}
}
}
]
}
Yêu cầu sẽ tạo một biểu đồ trong một trang tính mới như sau:
Thêm biểu đồ hình tròn
Mã mẫu spreadsheets.batchUpdate sau đây cho biết cách sử dụng AddChartRequest để tạo biểu đồ hình tròn 3D từ dữ liệu nguồn. Yêu cầu sẽ thực hiện những việc sau để định cấu hình biểu đồ:
- Đặt tiêu đề biểu đồ.
- Thêm chú giải vào bên phải biểu đồ.
- Đặt biểu đồ ở dạng biểu đồ hình tròn 3D. Lưu ý rằng biểu đồ hình tròn 3D không thể có "lỗ vòng" ở giữa như cách của biểu đồ hình tròn phẳng có thể.
- Đặt chuỗi dữ liệu trên biểu đồ làm tổng doanh số bán hàng cho từng số mẫu.
- Cố định biểu đồ trên ô C3 của trang tính do SHEET_ID chỉ định, với độ lệch 50 pixel theo cả hướng X và Y.
Giao thức yêu cầu được trình bày dưới đây.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"addChart": {
"chart": {
"spec": {
"title": "Model Q1 Total Sales",
"pieChart": {
"legendPosition": "RIGHT_LEGEND",
"threeDimensional": true,
"domain": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 0,
"endColumnIndex": 1
}
]
}
},
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 7,
"startColumnIndex": 4,
"endColumnIndex": 5
}
]
}
},
}
},
"position": {
"overlayPosition": {
"anchorCell": {
"sheetId": SHEET_ID,
"rowIndex": 2,
"columnIndex": 2
},
"offsetXPixels": 50,
"offsetYPixels": 50
}
}
}
}
}
]
}
Yêu cầu sẽ tạo một biểu đồ như sau:
Ngoài ra, bạn cũng có thể cập nhật giá trị ưu tiên Position từ RIGHT_LEGEND thành LABELED_LEGEND trong yêu cầu để các giá trị chú giải được kết nối với các lát cắt của biểu đồ hình tròn.
'legendPosition': 'LABELED_LEGEND',
Yêu cầu được cập nhật sẽ tạo một biểu đồ như sau:
Thêm biểu đồ dạng đường bằng cách sử dụng nhiều dải ô không liền nhau
Mã mẫu spreadsheets.batchUpdate sau đây cho biết cách sử dụng AddChartRequest để tạo biểu đồ dạng đường từ dữ liệu nguồn, đặt biểu đồ đó vào trang tính nguồn.
Bạn có thể chọn các dải ô không gần nhau để loại trừ các hàng khỏi ChartSourceRange.
Yêu cầu sẽ thực hiện những việc sau để định cấu hình biểu đồ:
- Đặt loại biểu đồ dưới dạng biểu đồ dạng đường.
- Đặt tiêu đề trục x theo chiều ngang.
- Thiết lập một chuỗi dữ liệu đại diện cho doanh số bán hàng. Thuộc tính này đặt A1:A3 và A6:A7 làm
domain, B1:B3 và B6:B7 làseries, trong khi sử dụng định dạng và màu sắc mặc định. Phạm vi được chỉ định bằng cách sử dụng ký hiệu A1 trong URL yêu cầu. - Cố định biểu đồ trên ô H8 của trang tính do SHEET_ID chỉ định.
Giao thức yêu cầu được trình bày dưới đây.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"addChart": {
"chart": {
"spec": {
"basicChart": {
"chartType": "LINE",
"domains": [
{
"domain": {
"sourceRange": {
"sources": [
{
"startRowIndex": 0,
"endRowIndex": 3,
"startColumnIndex": 0,
"endColumnIndex": 1,
"sheetId": SOURCE_SHEET_ID
},
{
"startRowIndex": 5,
"endRowIndex": 7,
"startColumnIndex": 0,
"endColumnIndex": 1,
"sheetId": SOURCE_SHEET_ID
}
]
}
}
}
],
"series": [
{
"series": {
"sourceRange": {
"sources": [
{
"startRowIndex": 0,
"endRowIndex": 3,
"startColumnIndex": 1,
"endColumnIndex": 2,
"sheetId": SOURCE_SHEET_ID
},
{
"startRowIndex": 5,
"endRowIndex": 7,
"startColumnIndex": 1,
"endColumnIndex": 2,
"sheetId": SOURCE_SHEET_ID
}
]
}
}
}
]
}
},
"position": {
"overlayPosition": {
"anchorCell": {
"sheetId": SOURCE_SHEET_ID,
"rowIndex": 8,
"columnIndex": 8
}
}
}
}
}
}
]
}
Yêu cầu sẽ tạo một biểu đồ trong một trang tính mới như sau:
Xoá biểu đồ
Mã mẫu spreadsheets.batchUpdate sau đây cho biết cách dùng DeleteEmbeddedObjectRequest để xoá biểu đồ do CHART_ID chỉ định.
Giao thức yêu cầu được trình bày dưới đây.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"deleteEmbeddedObject": {
"objectId": CHART_ID
}
}
]
}
Chỉnh sửa thuộc tính của biểu đồ
Mã mẫu spreadsheets.batchUpdate sau đây cho biết cách dùng UpdateChartSpecRequest để chỉnh sửa biểu đồ được tạo trong công thức Thêm biểu đồ cột, sửa đổi dữ liệu, loại và hình thức của biểu đồ. Bạn không thể thay đổi từng tập hợp con gồm các thuộc tính của biểu đồ. Để chỉnh sửa, bạn phải cung cấp toàn bộ trường spec bằng một UpdateChartSpecRequest. Về cơ bản, việc chỉnh sửa thông số kỹ thuật của biểu đồ
đòi hỏi bạn phải thay thế thông số đó bằng một thông số kỹ thuật mới.
Yêu cầu sau đây sẽ cập nhật biểu đồ gốc (do CHART_ID chỉ định):
- Đặt loại biểu đồ thành
BAR. - Di chuyển chú thích sang bên phải biểu đồ.
- Đảo ngược các trục để "Doanh số" ở trục dưới cùng và "Số mô hình" ở trục bên trái.
- Đặt định dạng tiêu đề trục thành phông chữ 24 điểm, in đậm và in nghiêng.
- Xoá dữ liệu "W-24" khỏi biểu đồ (hàng 7 trong dữ liệu nguồn của biểu đồ).
Giao thức yêu cầu được trình bày dưới đây.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"updateChartSpec": {
"chartId": CHART_ID,
"spec": {
"title": "Model Q1 Sales",
"basicChart": {
"chartType": "BAR",
"legendPosition": "RIGHT_LEGEND",
"axis": [
{
"format": {
"bold": true,
"italic": true,
"fontSize": 24
},
"position": "BOTTOM_AXIS",
"title": "Sales"
},
{
"format": {
"bold": true,
"italic": true,
"fontSize": 24
},
"position": "LEFT_AXIS",
"title": "Model Numbers"
}
],
"domains": [
{
"domain": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 6,
"startColumnIndex": 0,
"endColumnIndex": 1
}
]
}
}
}
],
"series": [
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 6,
"startColumnIndex": 1,
"endColumnIndex": 2
}
]
}
},
"targetAxis": "BOTTOM_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 6,
"startColumnIndex": 2,
"endColumnIndex": 3
}
]
}
},
"targetAxis": "BOTTOM_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"sheetId": SOURCE_SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 6,
"startColumnIndex": 3,
"endColumnIndex": 4
}
]
}
},
"targetAxis": "BOTTOM_AXIS"
}
],
"headerCount": 1
}
}
}
}
]
}
Sau khi yêu cầu, biểu đồ sẽ xuất hiện như sau:
Di chuyển hoặc đổi kích thước biểu đồ
Mã mẫu spreadsheets.batchUpdate sau đây cho biết cách sử dụng UpdateEmbeddedObjectPositionRequest để di chuyển và đổi kích thước biểu đồ. Sau yêu cầu, biểu đồ do CHART_ID chỉ định sẽ:
- Đã neo vào ô A5 trên trang tính gốc.
- Bù trừ theo hướng X 100 pixel.
- Được đổi kích thước thành 1200 x 742 pixel (kích thước mặc định cho biểu đồ là 600 x 371 pixel).
Yêu cầu này chỉ thay đổi những thuộc tính được chỉ định bằng tham số fields.
Các thuộc tính khác (chẳng hạn như offsetYPixels) vẫn giữ nguyên giá trị ban đầu.
Giao thức yêu cầu được trình bày dưới đây.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"updateEmbeddedObjectPosition": {
"objectId": CHART_ID,
"newPosition": {
"overlayPosition": {
"anchorCell": {
"rowIndex": 4,
"columnIndex": 0
},
"offsetXPixels": 100,
"widthPixels": 1200,
"heightPixels": 742
}
},
"fields": "anchorCell(rowIndex,columnIndex),offsetXPixels,widthPixels,heightPixels"
}
}
]
}
Đọc dữ liệu biểu đồ
Mã mẫu spreadsheets.get sau đây cho biết cách lấy dữ liệu biểu đồ trong một bảng tính. Tham số truy vấn fields chỉ định rằng chỉ trả về dữ liệu biểu đồ.
Phản hồi cho lệnh gọi phương thức này là một đối tượng spreadsheet, chứa một mảng các đối tượng sheet. Mọi biểu đồ có trên một trang tính đều được biểu thị trong đối tượng sheet. Nếu một trường phản hồi được đặt thành giá trị mặc định, thì trường đó sẽ bị loại khỏi phản hồi.
Trong ví dụ này, trang tính đầu tiên (SOURCE_SHEET_ID) không có biểu đồ nào, vì vậy, một cặp dấu ngoặc nhọn trống sẽ được trả về. Trang tính thứ hai có biểu đồ do phần Thêm biểu đồ cột tạo và không có thông tin nào khác.
Giao thức yêu cầu được trình bày dưới đây.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?fields=sheets(charts)
{
"sheets": [
{},
{
"charts": [
{
"chartId": CHART_ID,
"position": {
"sheetId": SHEET_ID
},
"spec": {
"basicChart": {
"axis": [
{
"format": {
"bold": false,
"italic": false
},
"position": "BOTTOM_AXIS",
"title": "Model Numbers"
},
{
"format": {
"bold": false,
"italic": false
},
"position": "LEFT_AXIS",
"title": "Sales"
}
],
"chartType": "COLUMN",
"domains": [
{
"domain": {
"sourceRange": {
"sources": [
{
"endColumnIndex": 1
"endRowIndex": 7,
"sheetId": SOURCE_SHEET_ID,
"startColumnIndex": 0,
"startRowIndex": 0,
}
]
}
}
}
],
"legendPosition": "BOTTOM_LEGEND",
"series": [
{
"series": {
"sourceRange": {
"sources": [
{
"endColumnIndex": 2,
"endRowIndex": 7,
"sheetId": SOURCE_SHEET_ID,
"startColumnIndex": 1,
"startRowIndex": 0,
}
]
}
},
"targetAxis": "LEFT_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"endColumnIndex": 3,
"endRowIndex": 7,
"sheetId": SOURCE_SHEET_ID,
"startColumnIndex": 2,
"startRowIndex": 0,
}
]
}
},
"targetAxis": "LEFT_AXIS"
},
{
"series": {
"sourceRange": {
"sources": [
{
"endColumnIndex": 4,
"endRowIndex": 7,
"sheetId": SOURCE_SHEET_ID,
"startColumnIndex": 3,
"startRowIndex": 0,
}
]
}
},
"targetAxis": "LEFT_AXIS"
}
]
},
"hiddenDimensionStrategy": "SKIP_HIDDEN_ROWS_AND_COLUMNS",
"title": "Model Q1 Sales",
},
}
]
}
]
}