Toán tử trang tính

Google Trang tính API cho phép bạn tạo, xoá, sao chép và xoá các 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 thường gặp trên Trang tính bằng Sheets API.

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 một bản 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í mà 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 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 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 trình bày 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 mà vẫn giữ nguyên định dạng

Mẫu mã spreadsheets.batchUpdate sau đây cho biết cách sử dụng UpdateCellsRequest để xoá tất cả cá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 được hiểu là một chỉ dẫn để xoá các giá trị trong phạm vi. Bạn cũng có thể 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 mà API Trang tính hỗ trợ khỏi trang tính, nhưng vẫn giữ nguyên giá trị của ô.

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: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 thấy cách sao chép một trang tính duy nhất do SHEET_ID chỉ định từ một bảng tính sang một bảng tính khác.

Biến TARGET_SPREADSHEET_ID trong nội dung yêu cầu chỉ định bảng tính đích. Bản sao giữ lại tất 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 được sao chép sẽ là "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ẫu mã spreadsheets.batchUpdate sau đây cho biết cách sử dụng DeleteSheetRequest để xoá một trang được chỉ định bằng SHEET_ID.

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:batchUpdate
 
{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": SHEET_ID
      }
    }
  ]
}

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

Mã mẫu spreadsheets.get sau đây cho thấy cách lấy thông tin thuộc tính sheet từ một spreadsheet, được chỉ định bằng SHEET_ID và SPREADSHEET_ID. 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 những trang tính đó. Tham số truy vấn fields chỉ định rằng chỉ dữ liệu thuộc tính trang tính mới được trả về (thay vì 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 đó có một đối tượng Sheet với 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 trong 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
        }
      },
      ...
  ],
}