Trang này được dịch bởi Cloud Translation API.

Viết cơ bản

API Google Trang tính cho phép bạn ghi các giá trị và công thức vào ô, 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ạ một số thao tác ghi phổ biến có thể thực hiện bằng tài nguyên spreadsheets.values của API Trang tính.

Lưu ý rằng bạn cũng có thể ghi các giá trị của ô 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 cập nhật đồng thời đị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 phương thức UpdateCellsRequest bằng spreadsheet.batchUpdate.

Tuy nhiên, đối với việc ghi giá trị đơn giản, bạn sẽ dễ dàng sử dụng phương thức spreadsheets.values.update hoặc phương thức spreadsheets.values.batchUpdate.

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 chức năng ghi bằng nhiều ngôn ngữ nhờ 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 qua URL của bảng tính. Chỉ định các dải ô để ghi bằng ký hiệu A1. Dải ô ví dụ là Sheet1!A1:D5.

Viết một dải ô duy nhất

Bắt đầu bằng một bảng tính trống mới, mã mẫu spreadsheets.values.update sau đây sẽ cho bạn 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 giá trị đã 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).

Phần nội dung yêu cầu là một đối tượng ValueRange mô tả các giá trị dải ô cần ghi. Trường majorDimension cho biết 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 ô mục tiêu sẽ bị ghi đè.

Giao thức yêu cầu được trình bày dưới đây.

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 sau:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

Trang tính thu được sẽ có dạng như sau:

	Đá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

Viết 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 chính dữ liệu do ví dụ ở trên tạo ra, mã mẫu spreadsheets.values.update sau đây cho biết cách ghi các giá trị vào dải ô B1:D4, giữ nguyên một số ô và xoá các ô khác. Tham số truy vấn ValueInputOption là bắt buộc và xác định xem giá trị đã 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).

Phần nội dung yêu cầu là một đối tượng ValueRange mô tả các giá trị dải ô cần ghi. Trường majorDimension cho biết 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 dưới đây.

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 cho từng cột trong dải ô. Mảng đầu tiên cho biết B1 sẽ không được thay đổi (do phần tử mảng null), trong khi B4 sẽ được xoá (chuỗi trống). B2 và B3 được cập nhật giá trị. 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 không được thay đổi.

Phản hồi bao gồm một đối tượng UpdateValuesResponse, chẳng hạn như đối tượng sau:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

Trang tính thu được sẽ có dạng như sau:

	Đáp	B	C	D
1	Mục	Chi phí	Còn hàng	Ngày giao hàng
2	Vòng đu quay	1 đô la	4	Ngày 1 tháng 4 năm 2016
3	Cửa ra vào	2 đô la	2	Ngày 15 tháng 4 năm 2016
4	Động cơ		1
5	Tổng số	3 đô la	7	Ngày 15 tháng 4 năm 2016

Lưu ý rằng mặc dù yêu cầu này không thay đổi trực tiếp hàng "Tổng", nhưng hàng này vẫn thay đổi vì các ô của hàng chứa công thức phụ thuộc vào các ô đã bị thay đổi.

Ghi vào nhiều dải ô

Bắt đầu bằng một trang tính trống, mã mẫu spreadsheets.values.batchUpdate sau đây sẽ 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 ô mục tiêu sẽ bị ghi đè. 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 ô đã ghi. Trường majorDimension xác định xem các mảng được đưa vào có được diễn giải dưới dạng mảng cột hoặc hàng hay không.

Giao thức yêu cầu được trình bày dưới đây.

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ê đã cập nhật về ô và một mảng các đối tượng UpdateValuesResponse, mỗi đối tượng cho một 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 thu được sẽ có dạng như sau:

	Đá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
4	Động cơ
5

Ghi các 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ã mẫu 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 đã viết được phân tích cú pháp dưới dạng công thức, boolean hoặc số. Chúng xuất hiện dưới dạng chuỗi và việc căn chỉnh văn bản được căn chỉnh hợp lý trong trang tính.

Giao thức yêu cầu được trình bày dưới đây.

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 sau:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

Trang tính thu được sẽ có dạng như sau:

	Đáp	B	C	D	E
1	Dữ liệu	123,45	TRUE	=MAX(D2:D4)	10
2

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ì đó 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 chuỗi.

Thêm giá trị

Bắt đầu với một trang tính như bảng dưới đây:

	Đá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

Mã mẫu spreadsheets.values.append sau đây cho biết cách thêm hai hàng giá trị mới bắt đầu bằng hàng 3. Tham số truy vấn ValueInputOption là bắt buộc và xác định xem giá trị đã 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).

Phần nội dung yêu cầu là một đối tượng ValueRange mô tả các giá trị dải ô cần ghi. Trường majorDimension cho biết 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 dưới đây.

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 sau:

{
  "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:

	Đá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