Dịch vụ Tables

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

Lưu ý: Đây là một dịch vụ nâng cao mà bạn phải bật trước khi sử dụ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 dành cho Tables API. Giống như tất cả các dịch vụ nâng cao trong Apps Script, dịch vụ Tables sử dụng cùng đối tượng, phương thức và tham số 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 dịch vụ hỗ trợ khác, hãy xem Hướng dẫn hỗ trợ 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ề phản hồi, bao gồm thông tin về bảng và định nghĩa cột trong 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 thông số page_token và page_size như minh hoạ dưới đây:

// 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 tham số page_size để liệt kê bảng là 100.

Xem thông tin và định nghĩa về các cột của bảng

Mẫu sau đây cho biết 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ã bảng nằm ngay sau /table/.

Mẫu bên dưới cho biết vị trí tìm mã bảng trong các 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 biết cách lấy danh sách hàng của bảng và đọc các giá trị của 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à 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 mỗi 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": "[e-mail]",  // 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 thông số page_token và page_size, như minh hoạ bên dưới:

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 khác, 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 chuyể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 trong bảng

Mẫu sau đây trình bà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 hàng nhằm chỉ nhận được những kết quả mà bạn quan tâm, hãy sử dụng tham số filter. Để biết thêm thông tin chi tiết về các loại cột và cú pháp được 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\"=\"[e-mail]\""})
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 'Point of Contact' được đặt thành '[e-mail]'

{
  “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": "[e-mail]",  // 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 một hàng trong bảng

Mẫu sau đây trình bày 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ị của đối tượng phải khớp chính xác với tiêu đề có phân biệt chữ hoa chữ thường của các cột trong bảng trừ phi loại cột có thể ghi là cột tra cứu hoặc tóm tắt. Bạn đặt giá trị cho các cột tra cứu 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ệ.

Lưu ý: Khi bạn tạo tiêu đề cột, hãy đảm bảo rằng tiêu đề không có dấu cách ở cuối để tránh nhầm lẫn.

Các 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)	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 (ở 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 }	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 nội dung đ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 thả xuống)
Thẻ từ khóa	String[] (mảng tùy chọn thẻ)	String[] (phải khớp với các lựa 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]"
Tra cứu	Tuỳ thuộc vào loại cột nguồn.	Trường này không thể sửa đổi được và sẽ cập nhật bằng 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 Tối đa trên một cột loại ngày: String Giá trị của danh sách: Array	Không thể sửa đổi trường này.
Trường đã 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ụ Tables sẽ cố gắng chuyển đổi các giá trị nhất định để khớp với loại cột. Nếu dữ liệu không khớp, dữ liệu sẽ không đặt giá trị và để trống đối với 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 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)

Lưu ý: Thao tác hàng loạt có thể bao gồm tối đa 500 hàng.

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

Mẫu sau đây cho biết cách cập nhật 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 cho một hàng theo hai cách:

Lấy mã hàng thông qua API

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

Lấy mã hàng trong giao diện người dùng Bảng

1. Mở bảng trong ứng dụng web Tables (Bảng).
2. Nhấp chuột phải vào hàng.
3. Nhấp vào Lấy đường liên kết đến hàng này.
4. Dán URL vào vị trí nào đó để bạn có thể sao chép mã.
5. 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 biết cách cập nhật giá trị của nhiều hàng trong 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));

Lưu ý: Thao tác hàng loạt có thể bao gồm tối đa 500 hàng.

Xoá hàng trong bảng

Mẫu sau đây cho biết cách xoá một hà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 trình bày cách xoá nhiều hàng trong 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 đã xóa

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

1. Trên máy tính, hãy mở ứng dụng web Tables.
2. Mở bảng mà bạn muốn khôi phục hàng.
3. Ở trên cùng, hãy nhấp vào biểu tượng Hiện các hàng và cột đã xoá .
4. Nhấp vào Hàng đã xoá.
5. Ở bên phải của hàng 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 .

Xem 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