API Google Trang tính cho phép bạn ghi giá trị và công thức vào các ô, dải ô, tập hợp dải ô và toàn bộ trang tính. Các ví dụ trên trang này minh hoạ cách thực hiện một số
thao tác ghi phổ biến bằng tài nguyên
spreadsheets.values
của API Trang tính.
Xin lưu ý rằng bạn cũng có thể ghi giá trị ô bằng phương thức
spreadsheet.batchUpdate
. Phương thức này có thể hữu ích nếu bạn muốn đồng thời cập nhật định dạng ô
hoặc các thuộc tính khác mà tài nguyên
spreadsheets.values
không ảnh hưởng. Ví dụ: nếu muốn sao chép một dải ô từ
trang tính này sang trang tính khác trong khi ghi đè cả công thức ô và định dạng ô, bạn có thể sử dụng
UpdateCellsRequest
phương thức với
spreadsheet.batchUpdate.
Tuy nhiên, đối với các thao tác ghi giá trị đơn giản, bạn nên sử dụng phương thức
spreadsheets.values.update
hoặc phương thức
spreadsheets.values.batchUpdate.
Các ví dụ này được trình bày dưới dạng yêu cầu HTTP để không phụ thuộc vào ngôn ngữ. Để tìm hiểu cách triển khai thao tác ghi 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ị ô.
Trong các ví dụ này, trình giữ chỗ SPREADSHEET_ID cho biết
vị trí 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 trong URL của bảng tính
. Các dải ô cần ghi được chỉ định bằng ký hiệu A1
notation. Ví dụ về dải ô là Trang tính1!A1:D5.
Ghi một dải ô
Bắt đầu bằng một bảng tính mới, trống, đoạn mã mẫu sau đây
spreadsheets.values.update
cho biết cách ghi giá trị vào một dải ô. Tham số truy vấn
ValueInputOption là bắt buộc và xác định xem các giá trị được ghi có được phân tích cú pháp hay không (ví dụ:
một chuỗi có được chuyển đổi thành ngày hay không).
Nội dung yêu cầu là một
ValueRange
đối tượng mô tả các giá trị dải ô cần ghi. Trường
majorDimension field
cho biết rằng các mảng là danh sách giá trị được sắp xếp theo hàng. Các giá trị hiện có trong dải ô đích sẽ bị ghi đè.
Giao thức yêu cầu được trình bày bên dưới.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION{
"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", "3/20/2016"],
["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
],
}Phản hồi bao gồm một
UpdateValuesResponse
đối tượng, chẳng hạn như đối tượng này:
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A1:D5",
"updatedRows": 5,
"updatedColumns": 4,
"updatedCells": 20,
}Trang tính kết quả sẽ có dạng như sau:
| A | B | C | D | |
| 1 | Mục | Chi phí | Đã nhập kho | Ngày giao hàng |
| 2 | Bánh xe | 20,50 đô la | 4 | 1/3/2016 |
| 3 | Cửa ra vào | 15 đô la | 2 | 15/3/2016 |
| 4 | Công cụ | 100 đô la | 1 | 20/3/2016 |
| 5 | Tổng số | 135,5 đô la | 7 | 20/3/2016 |
Ghi có chọn lọc vào một dải ô
Khi ghi giá trị vào một dải ô, bạn có thể tránh thay đổi một số ô hiện có bằng cách đặt các phần tử mảng tương ứng thành null. Bạn cũng có thể
xoá một ô bằng cách ghi một chuỗi trống ("") vào ô đó.
Bắt đầu bằng một trang tính chứa cùng dữ liệu do ví dụ trên
tạo ra, đoạn mã
spreadsheets.values.update
mẫu sau đây cho biết cách ghi giá trị vào dải ô B1:D4, chọn lọc
để một số ô không thay đổi và xoá các ô khác. Tham số truy vấn
ValueInputOption là bắt buộc và xác định xem các giá trị được ghi có được phân tích cú pháp hay không (ví dụ:
một chuỗi có được chuyển đổi thành ngày hay không).
Nội dung yêu cầu là một
ValueRange
đối tượng mô tả các giá trị dải ô cần ghi. Trường
majorDimension field
cho biết rằng các mảng là danh sách giá trị được sắp xếp theo cột.
Giao thức yêu cầu được trình bày bên dưới.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION{
"range": "Sheet1!B1",
"majorDimension": "COLUMNS",
"values": [
[null,"$1","$2", ""],
[],
[null,"4/1/2016", "4/15/2016", ""]
]
}Trường values ở đây liệt kê các thay đổi được thực hiện đối với từng cột trong dải ô. Mảng đầu tiên cho biết B1 sẽ không thay đổi (do phần tử mảng null), trong khi B4 sẽ bị xoá (chuỗi trống). B2 và B3 có giá trị được cập nhật. Mảng thứ ba thực hiện các thao tác tương tự trên cột D, trong khi mảng trống thứ hai cho biết cột C sẽ không thay đổi.
Phản hồi bao gồm một
UpdateValuesResponse
đối tượng, chẳng hạn như đối tượng này:
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!B1:D5",
"updatedRows": 3,
"updatedColumns": 2,
"updatedCells": 6,
}Trang tính kết quả sẽ có dạng như sau:
| A | B | C | D | |
| 1 | Mục | Chi phí | Đã nhập kho | Ngày giao hàng |
| 2 | Bánh xe | 1 đô la | 4 | 1/4/2016 |
| 3 | Cửa ra vào | 2 đô la | 2 | 15/4/2016 |
| 4 | Công cụ | 1 | ||
| 5 | Tổng số | 3 đô la | 7 | 15/4/2016 |
Xin lưu ý rằng hàng "Tổng số", mặc dù không bị thay đổi trực tiếp bởi yêu cầu này, nhưng vẫn thay đổi vì các ô của hàng này chứa công thức phụ thuộc vào các ô đã thay đổi.
Ghi vào nhiều dải ô
Bắt đầu bằng một trang tính trống, đoạn mã mẫu sau đây
spreadsheets.values.batchUpdate
cho biết cách ghi giá trị vào các dải ô Trang tính1!A1:A4 và
Trang tính1!B1:D2. Các giá trị hiện có trong dải ô đích sẽ bị ghi đè. Nội dung yêu cầu
bao gồm một
ValueInputOption đối tượng cho biết cách diễn giải dữ liệu đầu vào và một mảng các
ValueRange
đối tượng tương ứng với từng dải ô được ghi. Trường
majorDimension xác định xem các mảng được đưa vào có được diễn giải là mảng cột hay mảng hàng hay không.
Giao thức yêu cầu được trình bày bên dưới.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchUpdate{
"valueInputOption": "VALUE_INPUT_OPTION",
"data": [
{
"range": "Sheet1!A1:A4",
"majorDimension": "COLUMNS",
"values": [
["Item", "Wheel", "Door", "Engine"]
]
},
{
"range": "Sheet1!B1:D2",
"majorDimension": "ROWS",
"values": [
["Cost", "Stocked", "Ship Date"],
["$20.50", "4", "3/1/2016"]
]
}
]
}Phản hồi bao gồm một đối tượng liệt kê số liệu thống kê về ô đã cập nhật
và một mảng các
UpdateValuesResponse
đối tượng, một đối tượng cho mỗi dải ô được cập nhật. Ví dụ:
{
"spreadsheetId": SPREADSHEET_ID,
"totalUpdatedRows": 4,
"totalUpdatedColumns": 4,
"totalUpdatedCells": 10,
"totalUpdatedSheets": 1,
"responses": [
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A1:A4",
"updatedRows": 4,
"updatedColumns": 1,
"updatedCells": 4,
},
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!B1:D2",
"updatedRows": 2,
"updatedColumns": 3,
"updatedCells": 6,
}
],
}Trang tính kết quả sẽ có dạng như sau:
| A | B | C | D | |
| 1 | Mục | Chi phí | Đã nhập kho | Ngày giao hàng |
| 2 | Bánh xe | 20,50 đô la | 4 | 1/3/2016 |
| 3 | Cửa ra vào | |||
| 4 | Công cụ | |||
| 5 |
Ghi giá trị mà không cần phân tích cú pháp
Bắt đầu bằng một trang tính trống, đoạn mã mẫu
spreadsheets.values.update
sau đây cho biết cách ghi giá trị vào dải ô Trang tính1!A1:E1, nhưng sử dụng
tham số truy vấn RAW ValueInputOption
để ngăn các chuỗi được ghi phân tích cú pháp dưới dạng công thức,
giá trị boolean hoặc số. Các chuỗi này xuất hiện dưới dạng chuỗi và căn chỉnh văn bản được căn đều trong trang tính.
Nội dung yêu cầu là một
ValueRange
đối tượng mô tả các giá trị dải ô cần ghi. Trường
majorDimension field
cho biết rằng các mảng là danh sách giá trị được sắp xếp theo hàng. Các giá trị hiện có trong dải ô đích sẽ bị ghi đè.
Giao thức yêu cầu được trình bày bên dưới.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW{
"range": "Sheet1!A1:E1",
"majorDimension": "ROWS",
"values": [
["Data", 123.45, true, "=MAX(D2:D4)", "10"]
],
}Phản hồi bao gồm một
UpdateValuesResponse
đối tượng, chẳng hạn như đối tượng này:
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A1:E1",
"updatedRows": 1,
"updatedColumns": 5,
"updatedCells": 5,
}Trang tính kết quả sẽ có dạng như sau:
| A | B | C | D | E | |
| 1 | Dữ liệu | 123.45 | TRUE | =MAX(D2:D4) | 10 |
| 2 |
Xin lưu ý rằng "TRUE" được căn giữa và là giá trị boolean, trong khi "123.45" được căn phải vì đây là một số và "10" được căn trái vì đây là một chuỗi. Công thức không được phân tích cú pháp và cũng xuất hiện dưới dạng chuỗi.
Nối giá trị
Bắt đầu bằng một trang tính như bảng bên dưới:
| A | B | C | D | |
| 1 | Mục | Chi phí | Đã nhập kho | Ngày giao hàng |
| 2 | Bánh xe | 20,50 đô la | 4 | 1/3/2016 |
| 3 |
Đoạn mã mẫu
spreadsheets.values.append
sau đây cho biết cách thêm 2 hàng giá trị mới bắt đầu từ hàng 3. Tham số truy vấn
ValueInputOption là bắt buộc và xác định xem các giá trị được ghi có được phân tích cú pháp hay không (ví dụ:
một chuỗi có được chuyển đổi thành ngày hay không).
Nội dung yêu cầu là một
ValueRange
đối tượng mô tả các giá trị dải ô cần ghi. Trường
majorDimension field
cho biết rằng các mảng là danh sách giá trị được sắp xếp theo hàng.
Giao thức yêu cầu được trình bày bên dưới.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION{
"range": "Sheet1!A1:E1",
"majorDimension": "ROWS",
"values": [
["Door", "$15", "2", "3/15/2016"],
["Engine", "$100", "1", "3/20/2016"],
],
}Phản hồi bao gồm một đối tượng
AppendValuesResponse
, chẳng hạn như đối tượng này:
{
"spreadsheetId": SPREADSHEET_ID,
"tableRange": "Sheet1!A1:D2",
"updates": {
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A3:D4",
"updatedRows": 2,
"updatedColumns": 4,
"updatedCells": 8,
}
}Trang tính kết quả sẽ có dạng như sau:
| A | B | C | D | |
| 1 | Mục | Chi phí | Đã nhập kho | Ngày giao hàng |
| 2 | Bánh xe | 20,50 đô la | 4 | 1/3/2016 |
| 3 | Cửa ra vào | 15 đô la | 2 | 15/3/2016 |
| 4 | Công cụ | 100 đô la | 1 | 20/3/2016 |
| 5 |