Viết cơ bản

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 phương thức UpdateCellsRequest 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.

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 các ví dụ này, phần 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ã nhận dạng này trong URL của bảng tính. Các dải ô cần ghi vào được chỉ định bằng ký hiệu A1. Ví dụ về dải ô: Trang_tính1!A1:D5.

Ghi một dải ô

Bắt đầu với một bảng tính mới, trống, mã mẫu spreadsheets.values.update sau đây cho biết cách ghi các giá trị vào một dải ô. Bạn bắt buộc phải sử dụng tham số truy vấn ValueInputOption và tham số này sẽ 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 tháng hay không).

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 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 hiển thị 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 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:

Viết có chọn lọc vào một dải ô

Khi ghi các 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 với 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, chọn để giữ nguyên một số ô và xoá các ô khác. Bạn bắt buộc phải sử dụng tham số truy vấn ValueInputOption và tham số này sẽ 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 tháng 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 hiển thị 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 đã 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 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:

Xin lưu ý rằng hàng "Tổng" tuy không bị yêu cầu này thay đổi trực tiếp nhưng sẽ 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 với một trang tính trống, mã mẫu spreadsheets.values.batchUpdate sau đây cho biết cách ghi các 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 ô 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ó được diễn giải là mảng cột hay hàng hay không.

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

Viết giá trị mà không 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 các 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 đã ghi được phân tích cú pháp dưới dạng công thức, boolean hoặc số. Các giá trị này xuất hiện dưới dạng chuỗi và văn bản được căn chỉnh chính giữa trong trang tính.

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 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 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 như 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:

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.

Nối thêm giá trị

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

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. Bạn bắt buộc phải sử dụng tham số truy vấn ValueInputOption và tham số này sẽ 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 tháng hay không).

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 hàng.

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