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 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.

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 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 ô, thì bạn có thể sử dụng phương thức UpdateCellsRequest với spreadsheet.batchUpdate.

Tuy nhiên, để ghi giá trị đơn giản, bạn có thể 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 yêu cầu HTTP để trung lập về ngôn ngữ. Để tìm hiểu cách triển khai hoạt động ghi bằng nhiều ngôn ngữ thông qua thư viện ứng dụng Google API, hãy xem phần Đọ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. Mã này có thể được tìm thấy từ URL của bảng tính. Các dải ô cần ghi được chỉ định bằng ký hiệu A1. Một dải ô ví dụ là Sheet1!A1:D5.

Viết một phạm vi

Bắt đầu bằng một bảng tính trống và mới, mã mẫu spreadsheets.values.update sau đây 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 liệu các 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).

Nội dung yêu cầu là một đối tượng ValueRange mô tả các giá trị phạm vi 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 phạm vi mục tiêu sẽ bị ghi đè.

Giao thức yêu cầu được hiển thị 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:

A B C D
1 Mục Chi phí Còn hàng Ngày giao hàng
2 Vòng đu quay 20,5 USD 4 1/3/2016
3 Cửa ra vào đô la Hong Kong 2 15/3/2016
4 Động cơ 100 đô la 1 20/3/2016
5 Tổng số $135,5 7 20/3/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 cùng 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 liệu các 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).

Nội dung yêu cầu là một đối tượng ValueRange mô tả các giá trị phạm vi 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 hiển thị 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 mỗi cột trong dải ô. Mảng đầu tiên cho biết rằng B1 cần được giữ nguyên (do phần tử mảng null), trong khi B4 phải đượ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 thay đổi.

Phản hồi bao gồm một đối tượng UpdateValuesResponse 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:

A 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 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

Lưu ý rằng hàng "Tổng số", mặc dù không bị yêu cầu này trực tiếp thay đổi, nhưng thay đổi vì các ô trong hàng chứa công thức phụ thuộc vào các ô đã được 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 cho biết cách ghi giá trị vào các dải ô Sheet1!A1:A4 vàSheet1!B1:D2. Các giá trị hiện có trong phạm vi 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 ô được ghi. Trường majorDimension xác định xem các mảng được đưa vào có được hiểu là mảng cột hay hàng hay không.

Giao thức yêu cầu được hiển thị 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 của ô 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:

A B C D
1 Mục Chi phí Còn hàng Ngày giao hàng
2 Vòng đu quay 20,5 USD 4 1/3/2016
3 Cửa ra vào
4 Động cơ
5

Viết giá trị mà không cần phân tích cú pháp

Bắt đầu với một trang tính trống, mã mẫu spreadsheets.values.update sau đây cho biết cách ghi giá trị vào dải ô Trang tính 1!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 là hợp lý trong trang tính.

Nội dung yêu cầu là một đối tượng ValueRange mô tả các giá trị phạm vi 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 phạm vi mục tiêu sẽ bị ghi đè.

Giao thức yêu cầu được hiển thị 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 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:

A 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à 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 chuỗi.

Thêm giá trị

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

A B C D
1 Mục Chi phí Còn hàng Ngày giao hàng
2 Vòng đu quay 20,5 USD 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 từ hàng 3. Tham số truy vấn ValueInputOption là bắt buộc và xác định liệu các 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).

Nội dung yêu cầu là một đối tượng ValueRange mô tả các giá trị phạm vi 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 hiển thị 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 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:

A B C D
1 Mục Chi phí Còn hàng Ngày giao hàng
2 Vòng đu quay 20,5 USD 4 1/3/2016
3 Cửa ra vào đô la Hong Kong 2 15/3/2016
4 Động cơ 100 đô la 1 20/3/2016
5