ВАЖНО

❌Google-таблицы НЕ предназначены для быстрой работы с большим объемом данных❌

❌Google-таблицы НЕ рекомендуется использовать для финального продукта❌

❌По работоспособности интеграции с google-таблицами НЕТ и НЕ будет никаких гарантий❌

❌По ошибка сценариев с использованием google-таблиц техническая поддержка не оказывается❌

ОГРАНИЧЕНИЯ

  • При использовании апи с таблицами с суммарным количеством строк более 50_000 могут наблюдаться задержки в ответе
  • Работоспособность апи с таблицами с суммарным количеством строк более 100_000 не гарантируется. 
  • С "большими" (более 50_000 строк) таблицами крайне рекомендуется отказаться от работы через апи гугл таблиц и перейти на работу в crm системе с открытым апи. 

ВАЖНО

Для использования api таблица должна быть либо открыта для "всех, у кого есть ссылка", либо если нет такой возможности, то для пользователя twin-gsheets@gspread-restapi.iam.gserviceaccount.com

Оглавление

Введение

Новая реализация api для работы с гугл таблицами. 

Документация

Ссылка на swagger-документацию: http://intgr.twin24.io:60061/docs

Чтение данных из таблицы

Ссылка на документацию по методу

http://intgr.twin24.io:60061/docs#/Get%20Data/Get_data_from_spreadsheet_get_data_get

Метод, URL и авторизация

Метод: GET

Authorization: No Auth 

URL: http://intgr.twin24.io:60061/get_data

Описание параметров метода

Параметр

Обязательность

Описание

spreadsheet_url

даСсылка на гугл таблицу

worksheet_name

нет

Имя "листа", из которого будут получены данные

Если отсутствует, то будет использован первый лист 

filter_headersнет

Имя заголовков столбцов, по которым будет происходить фильтрация

Для передачи нескольких заголовков используется разделитель [///]

Например:

Хотим использовать заголовки Имя и Телефон

Тогда в filter_headers передаем значение Имя[///]Телефон

filter_values

нет

Значение фильтров по заголовкам

Для передачи нескольких заголовков используется разделитель [///]

Например:

Используя пример с Имя и Телефон, хотим найти Иван с номером 79991234567

Тогда в filter_values передаем значение Иван[///]79991234567

Пример запроса (URL)

http://intgr.twin24.io:60061/get_data?spreadsheet_url=https://docs.google.com/spreadsheets/d/1J3SR6E3cH6EJ5Z...3rEx3fX0/edit%23gid=0&worksheet_name=Лист1&filter_headers=Группа[///]Дата&filter_values=1[///]22.01.2022

Пример ответа

Ответ в формате Json 
{
  "count": 2,
  "data": [
    {
      "Идентификатор": "7f2e8a0c-4d6f-4d9d-8c2f-7f1c9e7a1c8a",
      "Группа": 1,
      "Фамилия": "Кузнецова",
      "Имя": "Анна",
      "Отчество": "Ивановна",
      "Дата": "22.01.2022",
      "Row": 2
    },
    {
      "Идентификатор": "3f6d4b21-8e4a-4f5d-9b7d-1c3d0f6e9c5b",
      "Группа": 1,
      "Фамилия": "Лебедев",
      "Имя": "Артем",
      "Отчество": "Александрович",
      "Дата": "22.01.2022",
      "Row": 3
    }
  ],
  "filter_used": true,
  "filter_headers": [
    "Группа",
    "Дата"
  ],
  "filter_values": [
    "1",
    "22.01.2022"
  ],
  "msg": "Ok"
}

Описание полей ответа (Успешного. Код: 200)

Поле

Обязательность

Описание

countДаЧисло элементов массива data – количество строк (не считая заголовка), полученных из таблицы
dataДаМассив данных (строк) – полученных из таблицы
Идентификатор/Группа и тднетЗначения в соответствующих заголовках таблицы в строке Row
RowнетНомер строки в таблице
filter_usedнетБыл ли применен фильтр
filter_headersнетЗаголовки, по которым была фильтрация
filter_valuesнетЗначения для фильтрации
msgДаСообщение об успешном завершении "Ok"

Добавление строки/строк в таблицу

Ссылка на документацию по методу

http://intgr.twin24.io:60061/docs#/Add%2C%20delete%20or%20update%20data/Add_row_s__to_a_spreadsheet_add_rows_post

Метод, URL, авторизация и тело

Метод: POST

Authorization: No Auth 

URL: http://intgr.twin24.io:60061/add_rows

Body:

Тело в формате Json 
{
  "data": [
    [
      "Test",
      1,
      "Just string"
    ],
    [
      "Test",
      2,
      "=A1"
    ]
  ]
}

Описание параметров метода

Параметр

Обязательность

Описание

spreadsheet_url

даСсылка на гугл таблицу

worksheet_name

нет

Имя "листа", из которого будут получены данные

Если отсутствует, то будет использован первый лист 

emptyнет

Выбор режима записи одной строки (если строк несколько - игнорируется):

  • Если не передан - запись строки производится в конец таблицы (после последней строки с данными)
  • Если передано 1 - запись строки производится в первую пустую строку

*Первый режим работает значительно быстрее второго, так как не требует поиска пустой строки

mode

нет

Выбор режима обработки переданных в таблицу данных:

  • Если не передан - запись данных производится без обработки (Например: если передана строка с формулой "=A1", то она будет записана именно как строка "=A1", а не обработана как формула)
  • Если передано 1 - запись данных производится с применением обработки от таблицы (Дата станет датой, формула - формулой и так далее)

Описание полей тела метода

Поле

Обязательность

Тип

Описание

dataдаList[List]Массив строк для записи
data.X (где X - номер элемента в массиве data)даList[int | str]Массив значений для записи в строку
data.X.Y (где Y номер элемента в массиве data.X)даint | strЗначение для записи

Пример запроса (cURL)

Ответ в формате Json 
curl --location 'http://intgr.twin24.io:60061/add_rows?spreadsheet_url=https%3A%2F%2Fdocs.google.com%2Fspreadsheets%2Fd%2F1J3SR6E3cH6EJ5Z...3rEx3fX0%2Fedit%23gid%3D0&worksheet_name=%D0%9B%D0%B8%D1%81%D1%821&mode=1' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "data": [
    [
      "Test",
      1,
      "Just string"
    ],
    [
      "Test",
      2,
      "=A1"
    ]
  ]
}'

Пример ответа

Ответ в формате Json 
{
  "msg": "Ok",
  "updatedRange": "'Лист1'!A45:C46"
}

Описание полей ответа (Успешного. Код: 200)

Поле

Обязательность

Описание

msgДа

Сообщение об успешном выполнении.

В случае ряда ошибок будет содержать текст ошибки

updatedRange
Нет

Обновленные ячейки таблицы в формате "'НАЗВАНИЕ ЛИСТА'!ДИАПАЗОН_В_А_НОТАЦИИ"

Отсутствует в случае ошибок

Удаление строки/строк из таблицы

Ссылка на документацию по методу

http://intgr.twin24.io:60061/docs#/Add%2C%20delete%20or%20update%20data/Delete_row_s__from_a_spreadsheet_delete_rows_delete

Метод, URL и авторизация

Метод: DELETE

Authorization: No Auth 

URL: http://intgr.twin24.io:60061/delete_rows

Описание параметров метода

Параметр

Обязательность

Описание

spreadsheet_url

даСсылка на гугл таблицу

worksheet_name

нет

Имя "листа", из которого будут получены данные

Если отсутствует, то будет использован первый лист 

startда

Номер строки - начало диапазона для удаления

*Если передан только параметр start, то будет удалена одна строка, номер который передан в этом параметре. 
Иначе - будет удален диапазон от start до end (включительно)

endнет

Номер строки - конец диапазона для удаления

*Если передан только параметр start, то будет удалена одна строка, номер который передан в этом параметре. 
Иначе - будет удален диапазон от start до end (включительно)

Пример запроса (URL)

http://intgr.twin24.io:60061/delete_rows?start=18&end=23&spreadsheet_url=https://docs.google.com/spreadsheets/d/1J3SR6E3cH6EJ5Z...3rEx3fX0/edit%23gid=0&worksheet_name=Лист1

Пример ответа

Ответ в формате Json 
{
  "msg": "Ok"
}

Описание полей ответа (Успешного. Код: 200)

Поле

Обязательность

Описание

msgДа

Сообщение об успешном выполнении.

В случае ряда ошибок будет содержать текст ошибки

Изменение и запись ячейки/ячеек в таблице

Ссылка на документацию по методу

http://intgr.twin24.io:60061/docs#/Add%2C%20delete%20or%20update%20data/Update_cell_s__on_a_spreadsheet_update_cells_post

Метод, URL, авторизация и тело

Метод: POST

Authorization: No Auth 

URL: http://intgr.twin24.io:60061/update_cells

Body:

Тело в формате Json 
{
  "range": "C18",
  "data": [
    [
      0,
      "=A5"
    ],
    [
      "Test"
    ]
  ]
}

Описание параметров метода

Параметр

Обязательность

Описание

spreadsheet_url

даСсылка на гугл таблицу

worksheet_name

нет

Имя "листа", из которого будут получены данные

Если отсутствует, то будет использован первый лист 

mode

нет

Выбор режима обработки переданных в таблицу данных:

  • Если не передан - запись данных производится без обработки (Например: если передана строка с формулой "=A1", то она будет записана именно как строка "=A1", а не обработана как формула)
  • Если передано 1 - запись данных производится с применением обработки от таблицы (Дата станет датой, формула - формулой и так далее)

Описание полей тела метода

Поле

Обязательность

Тип

Описание

rangeдаstrНомер ячейки или диапазон ячеек для изменения в A1 нотации
dataда

List[List] | int | str

Массив строк для записи или Значение для записи

data.X (где X - номер элемента в массиве data)даList[int | str]Массив значений для записи в строку
data.X.Y (где Y номер элемента в массиве data.X)даint | strЗначение для записи

Пример запроса (cURL)

Запись одного значения

Ответ в формате Json 
curl -X 'POST' \
  'http://intgr.twin24.io:60061/update_cells?spreadsheet_url=https%3A%2F%2Fdocs.google.com%2Fspreadsheets%2Fd%2F1J3SR6E3cH6EJ5Z...3rEx3fX0%2Fedit%23gid%3D0&worksheet_name=%D0%9B%D0%B8%D1%81%D1%821&mode=1' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "range": "C19",
  "data":"=B1"
}'

Запись массива строк

Ответ в формате Json 
curl -X 'POST' \
  'http://intgr.twin24.io:60061/update_cells?spreadsheet_url=https%3A%2F%2Fdocs.google.com%2Fspreadsheets%2Fd%2F1J3SR6E3cH6EJ5Z...3rEx3fX0%2Fedit%23gid%3D0&worksheet_name=%D0%9B%D0%B8%D1%81%D1%821&mode=1' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "range": "C18",
  "data": [
    [
      0,
      "=A5"
    ],
    [
      "Test"
    ]
  ]
}'

Пример ответа

Ответ в формате Json 
{
  "msg": "Ok"
}

Описание полей ответа (Успешного. Код: 200)

Поле

Обязательность

Описание

msgДа

Сообщение об успешном выполнении.

В случае ряда ошибок будет содержать текст ошибки


  • Нет меток