本頁面由 Cloud Translation API 翻譯而成。

Tables 服務

表格服務可讓指令碼透過程式輔助方式讀取及編輯 Google 試算表中的資料列。

參考資料

如要進一步瞭解這項服務，請參閱 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，請在「Tables」網頁應用程式中開啟資料表。在頂端的網址中，資料表 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 參數。如要進一步瞭解篩選器支援的語法和欄位類型，請參閱篩選 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);

當您指定要為新資料列設定的值時，物件鍵值組合的鍵必須完全符合資料表資料欄的大小寫敏感標題，除非可寫入的資料欄類型是查閱或摘要資料欄。您可以使用關聯的值，為查閱和摘要資料欄設定值。您必須使用「Relationships」對話方塊中的關係名稱，更新關係的值。

資料欄可接受的值取決於資料欄的資料類型：

欄類型	資料類型 (讀取)	可接受的輸入類型 (寫入)
標準資料
Text	`String`	`String`
Number	`Number`	`Number`
日期	`Date Object { "year": Number, "month": Number, "day": Number }`	`Date`、`String` (大多數日期格式)
詳盡資料
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[]` (必須與代碼選項相符)
Checkbox	`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 }`	這個欄位無法修改。

表格服務會盡力將指定值轉換為符合資料欄類型的值。如果資料不相符，就不會設定值，並將新資料列的值留空。

在表格中新增多個資料列

以下範例說明如何同時在資料表中新增多個資料列。

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。

從「Tables」UI 取得資料列 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);

還原已刪除的資料列

您可以透過「資料表」UI 還原已刪除的資料列。如要還原已刪除的資料列，請按照下列步驟操作：

在電腦上開啟 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