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

Dịch vụ Tables

Dịch vụ Bảng cho phép tập lệnh đọc và chỉnh sửa hàng theo phương thức lập trình trong Google Bảng.

Tài liệu tham khảo

Để biết thêm thông tin về dịch vụ này, hãy xem tài liệu về API Bảng. Giống như tất cả các dịch vụ nâng cao trong Apps Script, dịch vụ Bảng sử dụng các đối tượng, phương thức và tham số giống như API công khai. Để biết thêm thông tin, hãy xem phần Cách xác định chữ ký phương thức.

Để báo cáo vấn đề và tìm các dịch vụ hỗ trợ khác, hãy xem Hướng dẫn hỗ trợ về bảng.

Mã mẫu

Lấy danh sách bảng

Mẫu sau đây cho biết cách lấy danh sách tất cả các bảng mà người dùng sở hữu.

// Get list of tables the user owns
var response = Area120Tables.Tables.list();
if (response) {
  var tables = response.tables;
  Logger.log(JSON.stringify(tables[0]));
}

Dưới đây là ví dụ về nội dung phản hồi, bao gồm thông tin về bảng và định nghĩa cột bảng:

{
  “tables”: [
    {
      "name": "tables/b6prMlkWyekbsCFeX6IOdu",
      "displayName": "Applicants"
      "columns": [
        {"id": "9qVCMvgh", "name": "Name", "dataType": "text"},
        {"id": "aD8dDXAS", "name": "Email", "dataType": "text"},
        {"id": "9pc0kdNX", "name": "Experience", "dataType": "tags_list",
          "labels": [
            {"id": "aAqi235Q", "name": "Android"},
            {"id": "bULZ4OK3", "name": "iOS"},
          ],
        },
        {"id": "8abYfCyo", "name": "Home Address", "dataType": "location"},
        {"id": "8ccERJ2v", "name": "Doc", "dataType": "file_attachment_list"},
        {"id": "aFb-tXf1", "name": "Stage", "dataType": "dropdown",
          "labels": [
            {"id": "8Hcb-Pxe", "name": "Applied"},
            {"id": "aM3EDGFf", "name": "Phone Screen"},
            {"id": "abyFLVKU", "name": "Onsite Interview"},
          ],
        },
        {"id": "9yKUThTi", "name": "Recruiter", "dataType": "person_list"},
        {"id": "a5c9WPVA", "name": "Interview Date", "dataType": "date"},
        {"id": "bqtbYPtH", "name": "Created", "dataType": "create_timestamp"},
        {"id": "bWR08pBv", "name": "Updated", "dataType": "update_timestamp"}
      ]
    },
    ... // more tables
  ]
}

Theo mặc định, phản hồi bao gồm tối đa 20 bảng. Để truy xuất thêm bảng, hãy phân trang các phản hồi bằng cách sử dụng các thông số page_token và page_size như minh hoạ bên dưới:

// Paginate through a list of tables
var pageSize = 1000;
var pageToken;
var response = Area120Tables.Tables.list({page_size: pageSize});
while (response) {
  var tables = response.tables;

  // get next page of tables
  pageToken = response.nextPageToken;
  if (!pageToken) {
    response = undefined;
  } else {
    response = Area120Tables.Tables.list(tableRequest, {page_size: pageSize, page_token: pageToken});
  }
}

Giá trị tối đa của thông số page_size để liệt kê bảng là 100.

Nhận thông tin và định nghĩa cột của bảng

Mẫu sau đây cho thấy cách lấy thông tin và định nghĩa cột của một bảng cụ thể.

var tableID = "TABLE_ID";  // ID for the table
var tableName = "tables/" + tableID;
var response = Area120Tables.Tables.get(tableName);
Logger.log(JSON.stringify(response));

Tìm mã bảng

Để tìm mã nhận dạng của bảng, hãy mở bảng trong ứng dụng web Bảng. Trong URL ở trên cùng, mã nhận dạng bảng nằm ngay sau /table/.

Mẫu bên dưới cho biết vị trí tìm mã nhận dạng bảng trong nhiều URL của Bảng:

https://tables.area120.google.com/u/0/workspace/abcdefghijklmnop/table/TABLE_ID
https://tables.area120.google.com/u/0/table/TABLE_ID
https://tables.area120.google.com/u/0/table/TABLE_ID/view/abcedfghijk

Đọc các hàng của bảng

Mẫu sau đây cho thấy cách lấy danh sách các hàng của bảng và đọc giá trị trường.

var tableID = "TABLE_ID";  // ID for the table
var pageToken;
var pageSize = 1000;
var tableName = "tables/" + tableID;
var response = Area120Tables.Tables.Rows.list(tableName)
if (response) {
  for (var i = 0, rows = response.rows; i < rows.length; i++) {
    if (!rows[i].values) { // If blank row, keep going
      Logger.log("Empty row");
      continue;
    }
    Logger.log(rows[i].values);
    Logger.log(rows[i].values["Description"]);
  }
}

Dưới đây là một phản hồi mẫu. Phản hồi bao gồm danh sách các hàng trong bảng và giá trị cho từng trường.

{
  “rows”: [
    {
      "name": "tables/TABLE_ID/rows/a6tvEPska7l8rAlHlSdOLb",
      "values": {
        "Thing to do": "First item",  // Text
        "Size": 100,                  // Number
        "ETA":{"month":12,"day":3,"year":2021}  // Date
        "Stage": "Completed",         // Dropdown
        "Checklist": [                // Checklist
          "Do this",
          "then this"
        ],
        "Labels": [                   // Tags
          "Green",
          "Purple"
        ],
        "Address": {                  // Location
          "latitude": 40.740726470947266,
          "longitude": -74.00206756591797,
          "address": "3014 Watson Lane, Sattler, TX 78130, USA"
        },
        "Archive?": true,             // Checkbox
        "ID#": 1,                     // Auto ID
        "Row creator": "liz@gmail.com",  // Creator / Updater / Person
        "Last updated": "October 7, 2020 6:30:38 PM EDT",
        "Created on": "March 2, 2020 1:07:54 PM EST",
      }
    },
    ... // More rows
  ],
}

Theo mặc định, phản hồi bao gồm tối đa 50 hàng. Để truy xuất thêm hàng, hãy phân trang các phản hồi bằng cách sử dụng các tham số page_token và page_size như dưới đây:

var pageToken;
var pageSize = 1000;
var response = Area120Tables.Tables.Rows.list(tableName, {page_size: pageSize});
while (response) {
  var rows = response.rows;

  // read next page of rows
  pageToken = response.nextPageToken;
  if (!pageToken) {
    response = undefined;
  } else {
    response = Area120Tables.Tables.Rows.list(tableName, {page_size: pageSize, page_token: pageToken});
  }
}

Nếu có nhiều trang hơn, phản hồi sẽ cung cấp nextPageToken. Nếu không, phản hồi sẽ không xác định. Để truy xuất trang kết quả tiếp theo, hãy truyền nextPageToken vào lệnh gọi danh sách tiếp theo.

Giá trị tối đa của tham số page_size là 1.000.

Lấy một hàng từ bảng

Mẫu sau đây cho thấy cách đọc giá trị trường của một hàng trong bảng.

var tableID = "TABLE_ID";  // ID for the table
var tableName = "tables/" + tableID;
var rowID = "ROW_ID";  // ID for the row to fetch
var rowName = tableName + "/rows/" + rowID;    // Construct row name
var response = Area120Tables.Tables.Rows.get(rowName)
if (response) {
  Logger.log(response.values);
}

Lọc danh sách hàng

Để lọc danh sách các hàng nhằm chỉ nhận được những kết quả mà bạn quan tâm, hãy sử dụng thông số filter. Để biết thêm thông tin chi tiết về cú pháp và các loại cột mà bộ lọc hỗ trợ, vui lòng xem tài liệu về API lọc.

var tableID = "TABLE_ID";  // ID for the table
var pageToken;
var pageSize = 1000;
var tableName = "tables/" + tableID;
var response = Area120Tables.Tables.Rows.list(tableName, {filter:"values.\"Point of Contact\"=\"john.doe@gmail.com\""})
if (response) {
  for (var i = 0, rows = response.rows; i < rows.length; i++) {
    if (!rows[i].values) { // If blank row, keep going
      Logger.log("Empty row");
      continue;
    }
    Logger.log(rows[i].values);
    Logger.log(rows[i].values["Description"]);
  }
}

Phản hồi bao gồm các hàng có cột "Điểm liên hệ" được đặt thành "john.doe@gmail.com"

{
  “rows”: [
    {
      "name": "tables/TABLE_ID/rows/a6tvEPska7l8rAlHlSdOLb",
      "values": {
        "Thing to do": "Second item",  // Text
        "Size": 110,                  // Number
        "ETA":{"month":12,"day":3,"year":2021}  // Date

        "Stage": "Completed",         // Dropdown
        "Checklist": [                // Checklist
          "Do this",
          "then this",
          "finally this"
        ],
        "Labels": [                   // Tags
          "Green",
          "Orange"
        ],
        "Address": {                  // Location
          "latitude": 45.740726470947266,
          "longitude": -88.00206756591797,
          "address": "6027 Holmes Lane, Sattler, TX 78130, USA"
        },
        "Archive?": false,             // Checkbox
        "ID#": 2,                     // Auto ID
        "Point of Contact": "john.doe@gmail.com",  // Person
        "Last updated": "October 9, 2020 6:35:38 PM EDT",
        "Created on": "March 10, 2020 1:07:54 PM EST",
      }
    },
    ... // More rows
  ],
}

Tạo hàng trong bảng

Mẫu sau đây cho biết cách thêm một hàng vào bảng.

var tableID = "TABLE_ID";  // ID for the table
var tableName = "tables/" + tableID;
var values = {
    "Number Column": 100,
    "Text Column 2": "hello world",
    "Date Column 3": new Date(),
    "Dropdown Col.": "Dropdown value",
};
Area120Tables.Tables.Rows.create({values: values}, tableName);

Khi bạn chỉ định các giá trị cần đặt cho hàng mới, khoá của các cặp khoá-giá trị đối tượng phải khớp chính xác với tiêu đề phân biệt chữ hoa chữ thường của các cột bảng, trừ phi loại của cột có thể ghi là cột truy vấn hoặc tóm tắt. Bạn đặt giá trị cho cột tìm kiếm và tóm tắt bằng cách sử dụng giá trị cho mối quan hệ. Bạn phải cập nhật giá trị cho mối quan hệ bằng cách sử dụng tên mối quan hệ có trong hộp thoại Mối quan hệ.

Giá trị được chấp nhận cho một cột phụ thuộc vào loại dữ liệu của cột đó:

Loại cột	Loại dữ liệu (đọc)	Các loại dữ liệu đầu vào được chấp nhận (ghi)
Dữ liệu chuẩn
Văn bản	`String`	`String`
Number	`Number`	`Number`
Ngày	`Date Object { "year": Number, "month": Number, "day": Number }`	`Date`, `String` (trong hầu hết các định dạng ngày)
Dữ liệu đa dạng thức
Person (Người)	`String` (địa chỉ email)	`String` (phải khớp với người dùng Google)
Tệp đính kèm	`Object[] { "id": String, "name": String, "mimeType": String, "url": String }`	Bạn không thể sửa đổi trường này bằng API.
Vị trí	`Object { "latitude": Number, "longitude": Number, "address": String }`	`Object { "latitude": Number (required), "longitude": Number (required), "address": String }`
Mục nhập đa dạng thức
Trình đơn thả xuống	`String`	`String` (phải khớp với các lựa chọn trong trình đơn thả xuống)
Thẻ từ khóa	`String[]` (mảng các tuỳ chọn thẻ)	`String[]` (phải khớp với các tuỳ chọn thẻ)
Checkbox	`Boolean`	`Boolean`
Danh sách kiểm tra	`String[]` (mảng các mục trong danh sách)	`String[]` (phải khớp với các mục trong danh sách)
Dữ liệu được liên kết
Mối quan hệ	`String`	`String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"`
Tìm kiếm	Tuỳ thuộc vào loại cột nguồn.	Bạn không thể sửa đổi trường này và trường này sẽ cập nhật theo giá trị được liên kết.
Tóm tắt	Tuỳ thuộc vào loại cột nguồn và hàm tóm tắt: Số lượng: `Number` Lớn nhất trên cột loại Ngày: `String` Danh sách giá trị: `Array`	Bạn không thể sửa đổi trường này.
Trường được tính
Mã nhận dạng tự động	`Number`	Bạn không thể sửa đổi trường này.
Metadata
Người tạo	`String`	Bạn không thể sửa đổi trường này.
Thời gian tạo	`Object { “seconds”: Number, “nanos”: Number }`	Bạn không thể sửa đổi trường này.
Trình cập nhật	`String`	Bạn không thể sửa đổi trường này.
Thời gian cập nhật	`Object { “seconds”: Number, “nanos”: Number }`	Bạn không thể sửa đổi trường này.

Dịch vụ Bảng sẽ cố gắng hết sức để chuyển đổi các giá trị đã cho sao cho khớp với loại cột. Nếu dữ liệu không khớp, thì hàm này sẽ không đặt giá trị và để trống giá trị cho các hàng mới.

Thêm nhiều hàng vào bảng

Mẫu sau đây cho biết cách thêm nhiều hàng vào một bảng cùng một lúc.

var tableID = “TABLE_ID”;
var tableName = "tables/" + tableID;
Area120Tables.Tables.Rows.batchCreate({requests: [
  {row:{values:{"Col 1":"Sample",  "Col 2":"One",   "Col 3":"A"}}},
  {row:{values:{"Col 1":"Example", "Col 2":"Two",   "Col 3":"B"}}},
  {row:{values:{"Col 1":"Test",    "Col 2":"Three", "Col 3":"C"}}},
]}, tableName)

Cập nhật một hàng trong bảng

Mẫu sau đây cho thấy cách cập nhật các giá trị của một hàng hiện có trong bảng:

var rowName = "tables/TABLE_ID/rows/ROW_ID";
var values = {"Column": "HELLO"};
var response = Area120Tables.Tables.Rows.patch({values: values}, rowName);
Logger.log("Update row:" + JSON.stringify(response));

Phản hồi trả về hàng đã cập nhật.

Tìm mã hàng

Bạn có thể tìm mã nhận dạng của một hàng theo hai cách:

Lấy mã hàng bằng API

Khi đọc các hàng từ một bảng, bạn có thể sử dụng thuộc tính name cho mỗi hàng, bao gồm mã nhận dạng bảng và mã nhận dạng hàng.

Lấy mã nhận dạng hàng từ giao diện người dùng của Bảng

Mở bảng trong ứng dụng web Bảng.
Nhấp chuột phải vào hàng đó.
Nhấp vào Nhận đường liên kết đến hàng này.
Dán URL vào một nơi nào đó để bạn có thể sao chép mã nhận dạng.
Trong URL, mã nhận dạng nằm sau /row/.

Mẫu bên dưới cho biết vị trí tìm mã hàng trong URL:

https://tables.area120.google.com/table/TABLE_ID/row/ROW_ID

Cập nhật nhiều hàng trong bảng

Mẫu sau đây cho thấy cách cập nhật giá trị của nhiều hàng trong một bảng:

var tableID = “TABLE_ID”;
var tableName = "tables/" + tableID;
var requests = [
  {row: {name: "tables/TABLE_ID/rows/ROW_ID_1", values: {"Column": "WORLD"}}},
  {row: {name: "tables/TABLE_ID/rows/ROW_ID_2", values: {"Column": "WORLD"}}},
  {row: {name: "tables/TABLE_ID/rows/ROW_ID_3", values: {"Column": "WORLD"}}},
];
var response = Area120Tables.Tables.Rows.batchUpdate({requests: requests}, tableName);
Logger.log("Batch update rows:" + JSON.stringify(response));

Xoá một hàng trong bảng

Mẫu sau đây cho biết cách xoá một dòng khỏi bảng:

var rowName = "tables/TABLE_ID/rows/ROW_ID";
var response = Area120Tables.Tables.Rows.remove(rowName);
Logger.log("Delete row:" + JSON.stringify(response));

Xoá nhiều hàng trong bảng

Mẫu sau đây cho biết cách xoá nhiều hàng trong một bảng:

var tableID = “TABLE_ID”;
var tableName = "tables/" + tableID;
var rowNames = [
  "tables/TABLE_ID/rows/ROW_ID_1",
  "tables/TABLE_ID/rows/ROW_ID_2",
  "tables/TABLE_ID/rows/ROW_ID_3",
];
Area120Tables.Tables.Rows.batchDelete({names: rowNames}, tableName);

Khôi phục các hàng đã xoá

Bạn có thể khôi phục các hàng đã xoá từ giao diện người dùng của Bảng. Để khôi phục một hàng đã xoá, hãy làm theo các bước dưới đây:

Trên máy tính, hãy mở ứng dụng web Trang tính.
Mở bảng mà bạn muốn khôi phục hàng.
Ở trên cùng, hãy nhấp vào biểu tượng Hiển thị hàng và cột đã xoá .
Nhấp vào Hàng đã xoá.
Ở bên phải hàng mà bạn muốn khôi phục, hãy nhấp vào biểu tượng Khôi phục từ thùng rác .

Lấy danh sách không gian làm việc

Mẫu sau đây cho biết cách lấy danh sách tất cả không gian làm việc mà người dùng sở hữu.

// Get list of workspaces the user owns and lists the tables in each one:
var response = Area120Tables.Workspaces.list();
if (response) {
  var workspaces = response.workspaces;
  for (var workspace of workspaces){
    Logger.log(workspace.displayName);
    for (var table of workspace.tables) {
      Logger.log('Table: ' + table);
    }
  }
}

Dưới đây là ví dụ về nhật ký đầu ra:

My Workspace
Table: Table 1
Table: Table 2
My TODOs
Table: Tasks