Tables 服務可讓指令碼透過程式讀取及編輯 Google Tables 中的資料列。
參考資料
如要進一步瞭解這項服務,請參閱 Tables API 的說明文件。如同 Apps Script 的所有進階服務,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,請在資料表網頁應用程式中開啟資料表。在頂端網址中,資料表 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"]);
}
}
回應中會包含「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。請使用關係的值來設定 lookup 和 summary 資料欄的值。您必須使用「Relationships」對話方塊中找到的關係名稱來更新關係的值。
資料欄可接受的值取決於資料欄的資料類型:
資料欄類型 | 資料類型 (讀取) | 可接受的輸入類型 (寫入) |
---|---|---|
標準資料 | ||
文字 | 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 |
這個欄位無法修改。 |
Metadata | ||
建立者 | 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。
從資料表 UI 取得資料列 ID
- 在資料表網頁應用程式中開啟資料表。
- 在該列上按一下滑鼠右鍵。
- 按一下「取得這個資料列的連結」。
- 將網址貼到其他位置,以便複製 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 UI 還原已刪除的資料列。如要還原已刪除的資料列,請按照下列步驟操作:
- 在電腦上開啟資料表網頁應用程式。
- 開啟要還原資料列的資料表。
- 按一下頂端的「顯示已刪除的列和欄」圖示 。
- 按一下「已刪除的列」。
- 找到要還原的資料列,然後按一下右側的「從垃圾桶還原」圖示 。
取得工作區清單
以下範例說明如何取得使用者擁有的所有工作區清單。
// 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