表服务

借助 Tables 服务，脚本可以通过编程方式读取和修改 Google 表格中的行。

参考

如需详细了解此服务，请参阅 Tables API 的文档。与 Apps 脚本中的所有高级服务一样，Tables 服务使用的对象、方法和参数均与公共 API 相同。如需了解详情，请参阅如何确定方法签名。

如需报告问题和查找其他支持，请参阅“表格”支持指南。

示例代码

获取表的列表

以下示例展示了如何获取用户拥有的所有表的列表。

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

以下是响应的示例，其中包含有关表格和表格列定义的信息：

{
  “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
  ]
}

默认情况下，响应最多包含 20 个表格。如需检索更多表，请使用 page_token 和 page_size 参数对响应进行分页，如下所示：

// 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});
  }
}

商品详情表的 page_size 参数的最大值为 100。

获取表的信息和列定义

以下示例展示了如何获取特定表的信息和列定义。

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

查找表 ID

如需查找表的 ID，请在“表格”Web 应用中打开该表。在顶部的网址中，表 ID 位于 /table/ 后面。

以下示例展示了在各种 Tables 网址中查找表 ID 的位置：

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

读取表的行

以下示例展示了如何获取表的行列表并读取字段值。

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"]);
  }
}

示例响应如下所示。响应包含表格中的行列表以及每个字段的值。

{
  “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
  ],
}

默认情况下，响应最多包含 50 行。如需检索更多行，请使用 page_token 和 page_size 参数对响应进行分页，如下所示：

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});
  }
}

如果还有更多页面可用，响应会提供 nextPageToken。否则，响应将属于未定义响应。如需检索下一页结果，请将 nextPageToken 传入下一个列表调用。

page_size 参数的最大值为 1,000。

从表中获取一行

以下示例展示了如何从表中读取一行的字段值。

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);
}

过滤行列表

如需过滤行列表以仅获取您感兴趣的结果，请使用 filter 参数。如需详细了解过滤器支持的语法和列类型，请参阅过滤 API 文档。

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"]);
  }
}

响应包含“联系人”列设置为“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
  ],
}

在表中创建行

以下示例展示了如何向表中添加行。

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);

指定要为新行设置的值时，对象键值对的键必须与表格列的标题完全一致（区分大小写），除非可写列的类型为查询列或摘要列。您可以使用关系的值为查询列和摘要列设置值。您必须使用关系对话框中找到的关系名称来更新关系的值。

列的可接受值取决于列的数据类型：

列类型 数据类型（读取） 可接受的输入类型（写入）
标准数据
文本 String String
编号 Number Number
日期 Date
Object {
"year": Number,
"month": Number,
"day": Number
} 		Date、String（在大多数日期格式中）
Rich data
Person String（电子邮件地址） String（必须与 Google 用户匹配）
文件附件 Object[] {
"id": String,
"name": String,
"mimeType": String,
"url": String
} 		此字段无法使用 API 进行修改。
位置 Object {
"latitude": Number,
"longitude": Number,
"address": String
} 		Object {
"latitude": Number (required),
"longitude": Number (required),
"address": String
}
富条目
下拉列表 String String（必须与下拉菜单选项一致）
标签 String[]（代码选项数组） String[]（必须与代码选项一致）
复选框 Boolean Boolean
核对清单 String[]（列表项的数组） String[]（必须与列表项匹配）
关联的数据
关系 String String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
查找 取决于来源列类型。 此字段无法修改，并会使用关联的值进行更新。
摘要 取决于来源列类型和汇总函数：
计数：Number
日期类型列上的最大值：String
列表值：Array		 此字段无法修改。
计算字段
自动 ID Number 此字段无法修改。
元数据
创作者 String 此字段无法修改。
创建时间 Object {
“seconds”: Number,
“nanos”: Number
} 		此字段无法修改。
更新程序 String 此字段无法修改。
更新时间 Object {
“seconds”: Number,
“nanos”: Number
}		 此字段无法修改。

Tables 服务会尽最大努力将给定值转换为与列类型相匹配的值。如果数据不匹配，则不会设置该值，并将其留空以供新行使用。

向表格添加多行

以下示例展示了如何同时向表格添加多行。

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)

更新表中的行

以下示例展示了如何更新表中现有行的值：

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));
响应会返回更新后的行。

查找行 ID

您可以通过以下两种方式查找行的 ID：

使用 API 获取行 ID

从表中读取行时，您可以为每行使用 name 属性，其中包含表 ID 和行 ID。

从“表格”界面获取行 ID
  1. 在 Tables Web 应用中打开表格。
  2. 右键点击相应行。
  3. 点击获取此行的链接。
  4. 将网址粘贴到某个位置，以便复制 ID。
  5. 在网址中，该 ID 位于 /row/ 后面。

以下示例展示了如何在网址中找到行 ID：

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

更新表中的多行

以下示例展示了如何更新表中多行的数据：

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));

删除表中的行

以下示例展示了如何从表中删除单行：

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

删除表中的多行

以下示例展示了如何删除表中的多行：

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);

恢复已删除的行

您可以从“表格”界面恢复已删除的行。如需恢复已删除的行，请按以下步骤操作：

  1. 在计算机上，打开 Tables 网页应用。
  2. 打开您要恢复行的表。
  3. 点击顶部的“显示已删除的行和列”图标 。
  4. 点击已删除的行。
  5. 在要恢复的行右侧，点击“从回收站恢复”图标 。

获取工作区列表

以下示例展示了如何获取用户拥有的所有工作区的列表。

// 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);
    }
  }
}

以下是输出日志的示例：

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