透過 Tables 服務，指令碼可以程式輔助方式讀取及編輯 Google 表格中的資料列。
參考資料
如要進一步瞭解這項服務，請參閱 Tables API 的說明文件。與 Apps Script 中的所有進階服務一樣，Tables 服務使用的物件、方法和參數都與公開 API 相同。詳情請參閱「如何判斷方法簽章」。
如要回報問題及尋求其他支援，請參閱 Tables 支援指南。
程式碼範例
取得資料表清單
以下範例說明如何取得使用者擁有的所有資料表清單。
// 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 網頁應用程式中開啟表格。在頂端的網址中，表格 ID 位於 /table/ 後方。
以下範例顯示各種 Google 表格網址中的表格 ID 所在位置：
https://tables.area120.google.com/u/0/workspace/abcdefghijklmnop/table/TABLE_IDhttps://tables.area120.google.com/u/0/table/TABLE_IDhttps://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);指定新資料列的值時，物件鍵值組的鍵必須完全符合資料表欄的區分大小寫標題，除非可寫入的欄類型是查閱或摘要欄。您可以使用關係的值，為「lookup」和「summary」資料欄設定值。您必須使用「關係」對話方塊中的關係名稱，更新關係的值。
資料欄可接受的值取決於資料欄的資料類型：
| 欄類型 | 資料類型 (讀取) | 可接受的輸入類型 (寫入) |
|---|---|---|
| 標準資料 | ||
| 文字 | String |
String |
| Number | Number |
Number |
| 日期 | Date
|
Date、String (適用於大多數日期格式) |
| 詳盡資料 | ||
| Person | String (電子郵件地址) |
String (必須與 Google 使用者相符) |
| 附加檔案 | Object[] { |
這個欄位無法透過 API 修改。 |
| 位置 | Object {
|
Object {
|
| 詳細項目 | ||
| 下拉式選單 | String |
String (必須與下拉式選單選項相符) |
| 標記 | String[] (代碼選項陣列)
|
String[] (必須與代碼選項相符) |
| Checkbox | Boolean |
Boolean |
| 檢查清單 | String[] (清單項目陣列) |
String[] (必須與清單項目相符) |
| 已連結資料 | ||
| 關係 | String |
String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
|
| 查詢電話號碼 | 視來源資料欄類型而定。 | 這個欄位無法修改，會隨著連結的值更新。 |
| 摘要 | 視來源資料欄類型和摘要函式而定： 計數： Number日期類型資料欄的最大值： String列出值： Array |
這個欄位無法修改。 |
| 計算結果欄位 | ||
| 自動 ID | Number |
這個欄位無法修改。 |
| 中繼資料 | ||
| 建立者 | String |
這個欄位無法修改。 |
| 建立時間 | Object {
|
這個欄位無法修改。 |
| 更新程式 | String |
這個欄位無法修改。 |
| 更新時間 | Object { |
這個欄位無法修改。 |
表格服務會盡力將指定值轉換為符合資料欄類型的值。如果資料不相符，系統不會設定值，新資料列會留空。
在表格中新增多列
以下範例說明如何同時在資料表中新增多列。
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。
- 在網址中，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 網頁應用程式。
- 開啟要還原資料列的表格。
- 按一下頂端的「顯示已刪除的列和欄」圖示 。
- 按一下「已刪除的資料列」。
- 在要還原的列右側，按一下「從垃圾桶還原」圖示 。
取得工作區清單
下列範例說明如何取得使用者擁有的所有工作區清單。
// 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