表服务

借助 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，请在 Tables Web 应用。 在顶部的网址中，表格 ID 就在 /table/ 后面。

以下示例显示了在不同表格网址中查找表格 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 参数。如需详细了解语法和 列类型，请查看 filtering 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"]);
  }
}

响应包含带有“Point of Contact”（联系人）的行列设置为 “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);

当您指定要为新行设置的值时，对象的键 键值对必须与表中区分大小写的标题完全匹配 列，除非可写列的类型是 lookup 或 summary 列。您 使用 关系。您必须使用 可在 Relationships 对话框中找到的关系名称。

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

列类型 数据类型（读取） 可接受的输入类型（写入）
标准数据
文本 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。

从 Tables 界面获取行 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);

恢复已删除的行

您可以从 Tables 界面恢复已删除的行。要恢复已删除的行，请执行以下操作： 请按以下步骤操作：

  1. 在计算机上，打开 Tables Web 应用。
  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