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 các hàng trong Google Bảng theo cách lập trình.

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ề Tables API. 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ùng các đố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 bài viết Cách xác định chữ ký phương thức.

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

Mã mẫu

Lấy danh sách các 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 của 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 tham 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 tham số page_size cho bảng liệt kê là 100.

Nhận thông tin và định nghĩa cột của một 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 một bảng, hãy mở bảng đó trong ứng dụng web Tables. 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 thấy vị trí tìm mã nhận dạng bảng trong nhiều URL của Tables:

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 một bảng

Mẫu sau đây cho biết cách lấy danh sách các hàng của một bảng và đọc cá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ị của 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ư 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ó thêm trang, phản hồi sẽ có biểu tượng 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 biết cách đọc cá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 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 một 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, các khoá của 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 trong bảng, trừ phi loại cột có thể ghi là cột lookup (tra cứu) hoặc summary (tóm tắt). Bạn đặt giá trị cho các cột lookup và summary 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 tên mối quan hệ trong hộp thoại Relationships (Mối quan hệ).

Các giá trị được chấp nhận cho một cột tuỳ 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 tiê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
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ừ khoá)	`String[]` (mảng các lựa chọn về thẻ)	`String[]` (phải khớp với các lựa chọn về 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]"`
Lookup	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` Giá trị tối đa trên cột kiểu Ngày: `String` Liệt kê giá trị: `Array`	Bạn 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ụ Bảng sẽ cố gắng chuyển đổi các giá trị đã cho để khớp với loại cột. Nếu dữ liệu không khớp, thì hệ thống sẽ không đặt giá trị và để trống cho các hàng mới.

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

Ví dụ sau đây cho thấy 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 biết 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 2 cách:

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

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

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

Mở bảng trong ứng dụng web Tables.
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 minh hoạ 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 minh hoạ 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á trong giao diện người dùng Bảng. Để khôi phục một hàng đã bị 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 Tables trên web.
Mở bảng mà bạn muốn khôi phục các hàng.
Ở trên cùng, hãy nhấp vào biểu tượng Hiện các hàng và cột đã xoá .
Nhấp vào Hàng đã xoá.
Ở bên phải 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 .

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