テーブル サービス

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": "[e-mail]",  // 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\"=\"[e-mail]\""})
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"]);
  }
}

レスポンスには、[連絡先] 列が「[e-mail]」に設定されている行が含まれます。

{
  “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": "[e-mail]",  // 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] ダイアログで確認できる関係名を使用して、関係の値を更新する必要があります。

注: 列のタイトルを作成する際は、混乱を避けるためにタイトルの末尾にスペースを入れないようにしてください。

列に使用できる値は、列のデータ型によって異なります。

列の型	データ型（読み取り）	使用できる入力型（書き込み）
標準データ
テキスト	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]"
番号検索	ソース列の型によって異なります。	このフィールドは変更できません。リンクされた値で更新されます。
概要	ソース列のタイプと集計関数によって異なります。 カウント: Number 日付型列の最大値: String 値を一覧表示: 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)

注: バッチ オペレーションには最大 500 行を含めることができます。

テーブル内の行を更新する

次のサンプルは、テーブル内の既存の行の値を更新する方法を示しています。

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. [Get link to this row] をクリックします。
4. ID をコピーできるように、URL をどこかに貼り付けます。
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));

注: バッチ オペレーションには最大 500 行を含めることができます。

テーブルの行を削除する

次のサンプルは、テーブルから 1 つの行を削除する方法を示しています。

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