Сервис столов

Служба таблиц позволяет сценариям программно читать и редактировать строки в таблицах Google .

Ссылка

Дополнительные сведения об этой службе см. в документации API таблиц. Как и все расширенные службы в Apps Script, служба таблиц использует те же объекты, методы и параметры, что и общедоступный 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));

Найдите идентификатор таблицы

Чтобы найти идентификатор таблицы, откройте таблицу в веб-приложении Таблицы . В URL-адресе вверху идентификатор таблицы находится сразу после /table/ .

В приведенном ниже примере показано, где найти идентификатор таблицы в различных URL-адресах таблиц:

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 — 1000.

Получить одну строку из таблицы

В следующем примере показано, как считать значения полей одной строки из таблицы.

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);

Когда вы указываете значения, которые нужно установить для новой строки, ключи пар «ключ-значение» объекта должны точно соответствовать заголовкам столбцов таблицы с учетом регистра, если тип столбца, доступного для записи, не является столбцом поиска или столбцом сводки . Вы устанавливаете значения для столбцов поиска и сводки , используя значение связи. Вы должны обновить значение связи, используя имя связи, найденное в диалоговом окне « Отношения» .

Допустимые значения для столбца зависят от типа данных столбца:

Тип столбца Тип данных (чтение) Допустимые типы ввода (запись)
Стандартные данные
Текст String String
Число Number Number
Дата Date
Object {
"year": Number,
"month": Number,
"day": Number
}		 Date , String (в большинстве форматов даты)
Богатые данные
Человек 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		 Это поле не может быть изменено.
Расчетное поле
Автоматический идентификатор 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));
 Ответ возвращает обновленную строку.

Найдите идентификатор строки

Узнать идентификатор строки можно двумя способами:

Получите идентификатор строки с помощью API

Когда вы читаете строки из таблицы, вы можете использовать атрибут name для каждой строки, который включает идентификаторы таблицы и строки.

Получите идентификатор строки из пользовательского интерфейса таблиц.
  1. Откройте таблицу в веб-приложении Таблицы .
  2. Щелкните строку правой кнопкой мыши.
  3. Нажмите Получить ссылку на эту строку .
  4. Вставьте URL-адрес куда-нибудь, чтобы можно было скопировать идентификатор.
  5. В URL-адресе идентификатор находится после /row/ .

В приведенном ниже примере показано, где найти идентификатор строки в URL-адресе: 

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);

Восстановить удаленные строки

Вы можете восстановить удаленные строки из пользовательского интерфейса таблиц. Чтобы восстановить удаленную строку, выполните следующие действия:

  1. На своем компьютере откройте веб-приложение Таблицы .
  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