⟵ сюдатуда ⟶
  • REMOTES
  • О remotes
  • Модуль remotes
  • JSON
  • Подключение
  • Входящий JSON
  • Возвращаемый JSON
  • Взаимодействие по API

    Для разработчиков

    REMOTES

    О remotes

    Возможность запуска выполнения кода внутри Тотум сторонними сервисами и/или получения структурированной и подготовленной информации через Remotes, настроить который можно через таблицу ttm_remotes.

    Вызов осуществляется обращением по адресу хост/Remotes/name_action.

    Модуль remotes

    Обращение к модулю происходит по адресу хост/Remotes/name_action, где name_action — name в таблице ttm__remotes.

    Для того, чтобы код из строки в Remotes запускался на выполенение — чекбокс Включено должен быть в true и пользователь remotes_user должен быть не пустой.

    Код из code будет выполнен от имени пользователя указанного в remotes_user.

    Обращение может происходит по GET или POST. В code при выполнении будут переданы переменные:

    • $#getrow из переменных, переданных в GET.

    • $#postrow из переменных, переданных в POST при использовании application/x-www-form-urlencoded или multipart/form-data в заголовке Content-Type запроса HTTP.

    • $#inputстрока или null — необработанные данные из тела запроса.

    • $#headersrow из заголовков HTTP-запроса.

    Ответ возвращается в зависимости от настройки Возврат:

    • success/error — возвращается success либо error (если в процессе выполнения были ошибки, текст ошибки не выводится).

    • json — ответ скрипта переводится в JSON. Если возникла ошибка, возвращается {"error":"Текст ошибки"}.

    • строка — ответ скрипта возвращается как есть в тело ответа.

    • headers + body — в ответе скрипта ожидается row с ключами headers — отправляются в качестве HTTP-заголовков ответа и body — выводится в тело ответа.

    JSON

    Подключение

    Обращение к API осуществляется через POST по адресу http(s)://domain.ru/Json/.

    Если вызываются только секции auth и remotes задавать путь к таблице не нужно — обращение осуществляется по адресу http(s)://domain.ru/Json/

    В случае, если требуется работать с таблицей используя секции import/export/recalculate, таблица задается как:

    Для подключения к API должен быть создан пользователь с интерфейсом api в таблице пользователей. Пользователь должен иметь необходимые права на таблицу, если идет работа с таблицей

    Логин и пароль этого пользователя должны передаваться в секцию auth входящего JSON.

    {
    "auth": {
        "login": "json",
        "password": "1111"
      }
    }
    

    Входящий JSON

    Входящий JSON передается в теле POST-запроса.

    Обязательная секция auth — содержит логин и пароль.

    Доступ предоставляется пользователю с интерфейсом api при наличии доступа к вызываемой таблице. Логика доступов в циклы cycles_access_type не действует.

    Для манипуляций с полем через API у поля должна быть включена опция Показывать в API и в случае наличия ограничений в Видно ролям в API должна быть указана роль api-пользователя от которого идет подключение.

    Для изменения поля через API для поля должно быть включено Редактируемое в API и в случае наличия ограничений в Редактирование в API доступно ролям должна быть указана роль от которой идет подключение.

    • import — cекция отвечает за внесение изменений в таблицу (возможно, при наличии у пользователя роли с редактированием этой таблицы). Ограничения которые могут быть установлены для роли в префильтре в API на изменение не действуют! Поэтому в целях безопасности внимательно устанавливайте разрешения для ролей в Редактирование в API доступно ролям. Если вы хотите добавить строчные ограничения, сделайте это через errorExeption.

      • footer и header — изменить значения полей хедера и футера можно через соответствующие секции передав "name": new_value.

        • __clearscбросить значения к расчетным передав name полей.

        • __pinsзапинить значения передав name полей.

      {
        "import": {
          "header": {
            "h_title": "Изменение заголовка"
          }
        }
      }
      
          {
        "import": {
          "footer": {
            "__clears": [
              "f_field",
              "f_field2"
            ]
          }
        }
      }
      
      {
        "import": {
          "footer": {
            "__pins": [
              "f_field",
              "f_field2"
            ]
          }
        }
      }
      
      • rows — секция для изменения строк по их id.

        • modify — изменение значений полей. Передается как объект с ключом id-строки и значениями: name поля, значение "2": {"row_field": new value} и/или список полей в __pins, __clears для закрепления/открепления значений.

        • add — список добавляемых строк содержащий name полей и их значения для каждой добавляемой строки.

        • remove — список id удаляемых строк.

        {
          "rows": {
            "modify": {
              "2": {
                "name_field": "new value",
                "__pins": [
                  "name_field_pin"
                ]
              },
              "3": {
                "name_field": "new value"
              }
            },
            "add": [
              {
                "name_field": "added_value_in_row1"
              },
              {
                "name_field": "added_value_in_row2"
              }
            ],
            "remove": []
          }
        }
        
      • rows-set-where — изменить/добавить/удалить строки в строчной части таблицы по условиям. В одном запросе может быть передано несколько разных изменений по разным условиям.

        • set — содержит данные для изменения в формате "name": new_value, и/или name полей в __pins и __clear если это необходимо.

        • where — список условий:

          • field — name поля по которому будет осуществлятся выборка. Поле по которому осуществляется выборка не чувствительно к Показывать в API.
          • value — значение сравнения.
          • operatop — оператор сравнения.
        {
          "import": {
            "rows-set-where": [
              {
                "where": [
                  {
                    "field": "id",
                    "value": "test",
                    "operator": "="
                  }
                ],
                "set": {
                  "test": true,
                  "__pins": [
                    "rekvizity"
                  ]
                }
              }
            ]
          }
        }
        
    • recalculate — принимает список условий для выборки строк для пересчета в простых таблицах. В расчетных таблицах эту секцию можно не вызывать — пересчет происходит при каждом обращении через API к таблице.

      • field — name поля по которому будет осуществлятся выборка. Поле по которому осуществляется выборка не чувствительно к Показывать в API.
      • operator — оператор сравнения.
      • value — значение сравнения.
    {
      "recalculate": [
        {
          "field": "id",
          "operator": "=",
          "value": [
            1,
            2,
            3
          ]
        }
    }
    
    • remotes — секция для вызова исполняемых конструкций из таблицы ttm__remotes.

      • name — name из таблицы ttm__remotes. В строке ремоута должен быть выбран пользователь, который указан в секции auth, в поле API user и стоять галочка в Включено.
      • data — информация для передачи в параметр $#data кода ремоута.
      {
        "remotes": [
          {"name":"remote1", "data": {"var1": 1, "var2": [1,2,3]}},
          {"name":"remote2", "data": {"var1": 2, "var2": [3,2,5]}}
        ]
      }
      
    • export — секция для управления возвращаемыми значениями. Ограничения которые могут быть установлены для роли в префильтре действуют в API на экспорт! Поле префильтра должно быть доступно в Показывать в API и должно быть разрешение в Видно ролям в API.

      • fields — список полей для возврата.

      • filters — задаваемые значения фильтров. Фильры расчитываются аналогично веб-версии. Доступна выборка по id без префильтра по id. Если в API выведен префильтр запрещающий показ контретной строки по id, то она показана не будет.

      {
        "export": {
          "fields": [
            "id",
            "rekvizity"
          ],
          "filters": {
            "fl_filter": [
              "value1",
              "value2",
              "value3"
            ],
            "id": [
              2
            ]
          }
        }
      }
      

    Пример входящего JSON:

    {
      "export": {
        "fields": [
          "id",
          "rekvizity"
        ],
        "filters": {
          "id": [
            1,
            2,
            3
          ]
        }
      },
      "auth": {
        "login": "json",
        "password": "1111"
      },
      "import": {
        "rows-set-where": [
          {
            "where": {
              "field": "id",
              "value": "test",
              "operator": "="
            },
            "set": {
              "test": true,
              "__pins": [
                "rekvizity"
              ]
            }
          }
        ],
        "header": {
          "__pins": [
            "rekvizity"
          ],
          "__clears": [
            "rekvizity"
          ],
          "test": "Тестовая строка"
        },
        "footer": {
          "__pins": [
            "f_summ"
          ],
          "__clears": [
            "f_summ2"
          ]
        },
        "rows": {
          "modify": {
            "2": {
              "row_field": "new value",
              "__pins": [
                "rekvizity"
              ]
            },
            "3": {
              "rowField": "new value"
            }
          },
          "add": [],
          "remove": []
        }
      },
      "recalculate": [
        {
          "field": "id",
          "operator": "=",
          "value": [
            1,
            2,
            3
          ]
        }
      ]
    }
    

    Возвращаемый JSON

    В случае возникновения ошибки возвращается JSON вида:

    {
        "error": 5,
        "errorDescription": "Пользователь с такими данными не найден. Возможно, ему не включен доступ к xml/json-интерфейсу"
    }
    

    Если запрос был выполнен без ошибок, то в случае обращения к таблице вернется время ее последнего изменения:

    {
        "updated": "2019-08-19 14:56"
    }
    

    Если была задана секция remotes:

    Список возвращаемых элементов в секции соответствует списку вызванных ремоутов:

    {
      "remotes": [
        null,
        [1,2,3],
        {"a":1, "b":2}
      ]
    }
    
    

    Если таблица была изменена:

    {
        "updated": "2019-08-20 16:01",
        "changed": true
    }
    

    Если была задана секция export:

    {
      "export": {
        "rows": [
          {
            "id": 1,
            "test": "значение поля test 1"
          },
          {
            "id": 52,
            "test": "значение поля test 52"
          }
        ],
        "header": {
          "test": "testtest"
        }
      },
      "updated": "2019-08-20 16:01"
    }
    
    ⟵ сюда туда ⟶