Toán tử trang tính

API Google Trang tính cho phép bạn tạo, xoá, sao chép và xoá trang tính, đồng thời kiểm soát các thuộc tính của trang tính. Các ví dụ trên trang này minh hoạ cách bạn có thể thực hiện một số thao tác phổ biến trên Trang tính bằng API Trang tính.

Các ví dụ này được trình bày dưới dạng yêu cầu HTTP để không phân biệt ngôn ngữ. Để tìm hiểu cách triển khai tính năng cập nhật hàng loạt bằng nhiều ngôn ngữ bằng thư viện ứng dụng API của Google, hãy xem phần Cập nhật bảng tính.

Trong các ví dụ này, phần giữ chỗ SPREADSHEET_ID và SHEET_ID cho biết vị trí bạn sẽ cung cấp các mã nhận dạng đó. Bạn có thể tìm thấy mã nhận dạng bảng tính trong URL của bảng tính. Bạn có thể lấy mã nhận dạng trang tính bằng cách sử dụng phương thức spreadsheets.get. Các dải ô được chỉ định bằng ký hiệu A1. Ví dụ về dải ô là Trang_tính1!A1:D5.

Thêm trang tính

Mã mẫu spreadsheets.batchUpdate sau đây cho biết cách sử dụng AddSheetRequest để thêm một trang tính vào bảng tính, đồng thời đặt tiêu đề, kích thước lưới và màu thẻ.

Phản hồi bao gồm một AddSheetResponse, chứa một đối tượng có các thuộc tính của trang tính đã tạo (chẳng hạn như SHEET_ID).

Giao thức yêu cầu được hiển thị bên dưới.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "addSheet": {
        "properties": {
          "title": "Deposits",
          "gridProperties": {
            "rowCount": 20,
            "columnCount": 12
          },
          "tabColor": {
            "red": 1.0,
            "green": 0.3,
            "blue": 0.4
          }
        }
      }
    }
  ]
}

Xoá tất cả giá trị trong một trang tính trong khi vẫn giữ nguyên định dạng

Mã mẫu spreadsheets.batchUpdate sau đây cho biết cách sử dụng UpdateCellsRequest để xoá tất cả giá trị khỏi một trang tính mà không làm thay đổi định dạng.

Việc chỉ định trường userEnteredValue mà không có giá trị tương ứng sẽ được hiểu là hướng dẫn xoá các giá trị trong phạm vi. Bạn cũng có thể sử dụng chế độ cài đặt này với các trường khác. Ví dụ: việc thay đổi giá trị fields thành userEnteredFormat sẽ xoá tất cả định dạng được API Trang tính hỗ trợ khỏi trang tính, nhưng để nguyên giá trị ô.

Giao thức yêu cầu được hiển thị bên dưới.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "updateCells": {
        "range": {
          "sheetId": SHEET_ID
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

Sao chép một trang tính từ bảng tính này sang bảng tính khác

Mẫu mã spreadsheet.sheets.copyTo sau đây cho biết cách sao chép một trang tính do SHEET_ID chỉ định từ bảng tính này sang bảng tính khác.

Biến TARGET_SPREADSHEET_ID trong phần nội dung yêu cầu chỉ định bảng tính đích. Bản sao giữ lại tất cả các giá trị, định dạng, công thức và các thuộc tính khác của bản gốc. Tiêu đề của trang tính đã sao chép được đặt thành "Bản sao của [tiêu đề trang tính gốc]".

Phản hồi bao gồm một đối tượng SheetProperties mô tả các thuộc tính của trang tính đã tạo.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/sheets/SHEET_ID:copyTo

{
  "destinationSpreadsheetId": "TARGET_SPREADSHEET_ID"
}

Xoá trang tính

Mã mẫu spreadsheets.batchUpdate sau đây cho biết cách sử dụng DeleteSheetRequest để xoá một trang tính do SHEET_ID chỉ định.

Giao thức yêu cầu được hiển thị bên dưới.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": SHEET_ID
      }
    }
  ]
}

Đọc dữ liệu trang tính

Mã mẫu spreadsheets.get sau đây cho biết cách lấy thông tin thuộc tính sheet (trang tính) từ một spreadsheet (trang tính lớn), do SHEET_ID và SPREADSHEET_ID chỉ định. Phương thức này thường được dùng để xác định siêu dữ liệu của các trang tính trong một bảng tính cụ thể, nhờ đó các thao tác bổ sung có thể nhắm đến các trang tính đó. Thông số truy vấn fields chỉ định rằng chỉ dữ liệu thuộc tính của trang tính mới được trả về (chứ không phải dữ liệu giá trị ô hoặc dữ liệu liên quan đến toàn bộ bảng tính).

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?&fields=sheets.properties

Phản hồi bao gồm một tài nguyên Spreadsheet, trong đó chứa một đối tượng Sheet có các phần tử SheetProperties. Nếu một trường phản hồi nhất định được đặt thành giá trị mặc định, thì trường đó sẽ bị bỏ qua khỏi phản hồi.

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "Sheet1",
        "index": 0,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 100,
          "columnCount": 20,
          "frozenRowCount": 1
        }
        "tabColor": {
          "blue": 1.0
        }
      },
      ...
  ],
}