Google Sheets API cho phép bạn ghi các 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 các 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ừ một trang tính sang một trang tính khác trong khi ghi đè cả công thức ô và định dạng ô, bạn có thể sử dụng phương thức UpdateCellsRequest bằng spreadsheet.batchUpdate.
Tuy nhiên, đối với các thao tác ghi giá trị đơn giản, bạn nên 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ữ bằng cách sử dụng thư viện ứng dụng Google API, hãy xem phần Đọc và ghi giá trị ô.
Trong các ví dụ này, phần giữ chỗ SPREADSHEET_ID cho biết vị trí mà 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. Ví dụ về một dải ô là Trang_tính1!A1:D5.
Viết một dải ô
Bắt đầu bằng một bảng tính trống mới, mẫu mã spreadsheets.values.update sau đây cho biết cách ghi các 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ụ: liệu 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 đối tượng ValueRange mô tả các giá trị trong dải ô cần ghi. Trường majorDimension cho biết rằng các mảng là danh sách các giá trị được sắp xếp theo hàng. Các giá trị hiện có trong phạm vi đí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 đối tượng UpdateValuesResponse, 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 thu được sẽ có dạng như sau:
| A | B | C | D | |
| 1 | Mục | Chi phí | Đã lưu trữ | Ngày giao hàng |
| 2 | Bánh xe | 20,5 USD | 4 | 1/3/2016 |
| 3 | Cửa ra vào | đô la Hong Kong | 2 | 15/3/2016 |
| 4 | Động cơ | $100 | 1 | 20/3/2016 |
| 5 | Tổng số | 135,5 USD | 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 sau đây cho thấy cách ghi các 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ụ: liệu 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 đối tượng ValueRange mô tả các giá trị trong dải ô cần ghi. Trường majorDimension cho biết rằng các mảng là danh sách các 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ê những 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). Giá trị của B2 và B3 đã đượ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 đối tượng UpdateValuesResponse, 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 thu được sẽ có dạng như sau:
| A | B | C | D | |
| 1 | Mục | Chi phí | Đã lưu trữ | 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 | Động cơ | 1 | ||
| 5 | Tổng số | 3 đô la | 7 | 15/4/2016 |
Xin lưu ý rằng hàng "Tổng" không thay đổi trực tiếp theo 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, mẫu mã spreadsheets.values.batchUpdate sau đây cho biết cách ghi các giá trị vào các dải ô Sheet1!A1:A4 và Sheet1!B1:D2. Các giá trị hiện có trong dải ô đích sẽ bị ghi đè. Phần nội dung yêu cầu bao gồm một đối tượng ValueInputOption cho biết cách diễn giải dữ liệu đầu vào và một mảng các đối tượng ValueRange 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 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: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 đối tượng UpdateValuesResponse, mỗi đối tượng cho một dải ô đã 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 thu được sẽ có dạng như sau:
| A | B | C | D | |
| 1 | Mục | Chi phí | Đã lưu trữ | Ngày giao hàng |
| 2 | Bánh xe | 20,5 USD | 4 | 1/3/2016 |
| 3 | Cửa ra vào | |||
| 4 | Độ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, mẫu mã spreadsheets.values.update sau đây cho biết cách ghi các giá trị vào dải ô Sheet1!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ố. Chúng xuất hiện dưới dạng chuỗi và văn bản được căn đều trong trang tính.
Nội dung yêu cầu là một đối tượng ValueRange mô tả các giá trị trong dải ô cần ghi. Trường majorDimension cho biết rằng các mảng là danh sách các giá trị được sắp xếp theo hàng. Các giá trị hiện có trong phạm vi đí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 đối tượng UpdateValuesResponse, 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 thu được 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à một giá trị boolean, trong khi "123, 45" được căn phải vì là một số và "10" được căn trái vì 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 một chuỗi.
Thêm giá trị
Bắt đầu bằng một trang tính như bảng dưới đây:
| A | B | C | D | |
| 1 | Mục | Chi phí | Đã lưu trữ | Ngày giao hàng |
| 2 | Bánh xe | 20,5 USD | 4 | 1/3/2016 |
| 3 |
Mẫu mã 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ụ: liệu 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 đối tượng ValueRange mô tả các giá trị trong dải ô cần ghi. Trường majorDimension cho biết rằng các mảng là danh sách các 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 thu được sẽ có dạng như sau:
| A | B | C | D | |
| 1 | Mục | Chi phí | Đã lưu trữ | Ngày giao hàng |
| 2 | Bánh xe | 20,5 USD | 4 | 1/3/2016 |
| 3 | Cửa ra vào | đô la Hong Kong | 2 | 15/3/2016 |
| 4 | Động cơ | $100 | 1 | 20/3/2016 |
| 5 |