テーブル サービス

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 ウェブアプリでテーブルを開きます。上部の URL で、テーブル ID は /table/ の直後にあります。

次の例は、さまざまな Tables URL でテーブル 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": "[email protected]",  // 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 です。

テーブルから 1 行を取得する

次のサンプルは、テーブルから 1 つの行のフィールド値を読み取る方法を示しています。

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] 列が「[email protected]」に設定されている行が含まれます。

{   “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": "[email protected]",  // 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
日付 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[]（タグ オプションと一致している必要があります）
チェックボックス Boolean Boolean
チェックリスト String[]（リストアイテムの配列） String[]（リストアイテムと一致している必要があります）
リンクされたデータ
関係 String String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
番号検索 ソース列の型によって異なります。 このフィールドは変更できず、リンクされた値で更新されます。
概要 ソース列の型と集計関数によって異なります。
Count: Number
Max on a Date-type column: String
List Values: 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 は次の 2 つの方法で確認できます。

API で行 ID を取得する

テーブルから行を読み取るときに、テーブル ID と行 ID を含む各行の name 属性を使用できます。

Tables UI から行 ID を取得する
  1. Tables ウェブアプリでテーブルを開きます。
  2. 行を右クリックします。
  3. [この行のリンクを取得] をクリックします。
  4. URL をどこかに貼り付けて、ID をコピーできるようにします。
  5. URL 内では、ID は /row/ の後にあります。

次のサンプルは、URL で行 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 から復元できます。削除した行を復元する手順は次のとおりです。

  1. パソコンで、Tables ウェブアプリを開きます。
  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