Tables 服务允许脚本以编程方式读取和修改 Google Tables 中的行。
参考
如需详细了解此服务,请参阅 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/
之后。
以下示例展示了在各种 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
参数的最大值为 1000。
从表中获取一行
以下示例展示了如何从表中读取一行的字段值。
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);
指定要为新行设置的值时,对象键值对的键必须与表列的标题(区分大小写)完全匹配,除非可写列的类型是 lookup 或 summary 列。您可以使用该关系的值设置 lookup 和 summary 列的值。您必须使用在 Relationships 对话框中找到的关系名称更新关系的值。
列的可接受值取决于列的数据类型:
列类型 | 数据类型(读取) | 可接受的输入类型(写入) |
---|---|---|
标准数据 | ||
Text | String |
String |
编号 | Number |
Number |
日期 | Date
|
Date 、String (适用于大多数日期格式) |
Rich data | ||
人称 | String (电子邮件地址) |
String (必须与 Google 用户一致) |
文件附件 | Object[] { |
此字段无法使用 API 进行修改。 |
位置信息 | Object {
|
Object {
|
富媒体条目 | ||
下拉列表 | String |
String (必须与下拉菜单选项一致) |
标签 | String[] (代码选项数组)
|
String[] (必须与代码选项匹配) |
复选框 | Boolean |
Boolean |
核对清单 | String[] (列表项数组) |
String[] (必须与列表项一致) |
关联的数据 | ||
关系 | String |
String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
|
查询 | 取决于源列类型。 | 此字段无法修改,并将使用关联的值进行更新。 |
摘要 | 取决于源列类型和摘要函数: 计数: Number 日期类型列的最大值: String 列出值: Array |
此字段无法修改。 |
已计算字段 | ||
Auto ID | Number |
此字段无法修改。 |
元数据 | ||
创建者 | String |
此字段无法修改。 |
创建时间 | Object {
|
此字段无法修改。 |
更新程序 | String |
此字段无法修改。 |
更新时间 | Object { |
此字段无法修改。 |
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
- 在 Tables Web 应用中打开该表。
- 右键点击相应的行。
- 点击获取此行的链接。
- 将网址粘贴到其他位置,以便复制 ID。
- 在该网址中,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 界面中恢复已删除的行。要恢复已删除的行,请按以下步骤操作:
- 在计算机上,打开 Tables Web 应用。
- 打开要恢复行的表格。
- 点击顶部的“显示已删除的行和列”图标 。
- 点击已删除的行。
- 在要恢复的行的右侧,点击“从回收站恢复”图标 。
获取工作区列表
以下示例展示了如何获取用户拥有的所有工作区的列表。
// 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