Версия: 1.23.3

Table API

Table API позволяет вам производить операции CRUD (создание, чтение, обновление и удаление) на созданных таблицах.

При обработке запросов на операции CRUD посредством Table API учитываются правила контроля доступа (ACL).

Формат URL Table API:

Название	Значение
URL по умолчанию	/rest/v1/table/

Авторизация

Table API поддерживает два типа запросов на авторизацию:

Basic Auth – аутентификация включает в себя отправку запроса с проверенным именем пользователя и паролем.
Bearer Token – аутентификация с ключом доступа. Токен представляет собой текстовую строку, которая включена в заголовок запроса.

Операция CREATE

Используйте метод POST, чтобы создать запись в указанной таблице. Метод не поддерживает создание нескольких записей.

Пример:

POST /rest/v1/table/{tableName}

Параметры тела запроса

Вы можете указать необходимое количество колонок и их значений.

Параметр	Значение
column_name	column_value

Используйте следующие параметры с этим методом:

Параметр	Описание
sysparm_display_value	Флаг, определяющий тип возвращаемых данных. Валидные значения: 1 – возвращает отображаемое значение поля. 0 – возвращает значение поля из базы данных. Значение по умолчанию: 0.
sysparm_exclude_reference_link	Флаг, указывающий на исключение ссылок Table API (/rest/v1/table/) для ссылочных полей. 1 – исключить ссылки Table API для ссылочных полей. 0 – включить ссылки Table API для ссылочных полей. Значение по умолчанию: 0.
sysparm_fields	Список полей, разделенных запятой, которые должны вернуться в ответе. Параметр поддерживает использование dot-walking. Dot-walking не работает для таблицы Запланированные задания (sys_schedule_job), ее дочерних таблиц и таблицы Индикаторы (sys_indicator), так как после создания запись проходит обработку и не сразу появляется в базе данных. Пример значения: number,caller.phone
sysparm_view	Представление формы, поля которого должны вернуться в ответе. Обратите внимание, что этот параметр может быть переопределен параметром sysparm_fields. Из набора колонок представления, указанного в sysparm_view, выводятся только те, что указаны в sysparm_fields. Если указаны поля в sysparm_fields, которых нет в выбранном представлении, оно не выведется. Если параметр не задан, в ответе на запрос возвращаются значения всех колонок таблицы.

внимание

Используйте тело запроса типа raw JSON вместо form-data.

HTTP
POST /rest/v1/table/task HTTP/1.1
Host: sandbox-01.dev.simpleone.ru
Authorization: Bearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu
Content-Type: application/json
Content-Length: 43
 
{
    "subject": "Task created by REST"
}

Ответ

{
  "status": "OK",
  "data": [
    {
      "sys_id": "166031411802010329",
      "state": "7",
      "priority": null,
      "urgency": null,
      "impact": null,
      "assigned_user": null,
      "assignment_group": null,
      "wf_executing_activity": null,
      "closed_by": null,
      "followers_list": null,
      "parent_id": null,
      "opened_by": null,
      "caller": {
        "value": "155931135900000001",
        "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
      },
      "contact": null,
      "service": null,
      "screenshot": null,
      "short_description": null,
      "work_notes": null,
      "active": true,
      "closed_at": null,
      "sla_due": null,
      "sys_updated_at": "2022-08-12 14:21:58",
      "sys_created_at": "2022-08-12 14:21:58",
      "description": null,
      "number": "TSK0000006",
      "subject": "Task created by REST",
      "additional_comments": null,
      "comments": null,
      "opened_at": "2022-08-12 14:21:58",
      "due_date": null,
      "attention_required": false,
      "company": null,
      "approval_state": "not_requested",
      "sys_db_table_id": "155931135900000083",
      "display_name": "TSK0000006 Task created by REST",
      "sys_updated_by": {
        "value": "155931135900000001",
        "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
      },
      "sys_created_by": {
        "value": "155931135900000001",
        "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
      }
    }
  ]
}

Операция READ

Операции чтения в SimpleOne ограничены методом GET.

Для извлечения одной записи из указанной таблицы, используйте следующий шаблон URL:

GET /rest/v1/table/{tableName}/{sys_id}

Для извлечения нескольких записей, используйте следующий шаблон URL:

GET /rest/v1/table/{tableName}

Используйте следующие параметры с этим методом:

Параметр	Описание
sysparm_query	Закодированная строка запроса, которая используется для фильтрации результатов. Параметр поддерживает использование dot-walking. Пример значения: active=1. Для создания сложного запроса, используйте системные названия операторов и строку условий.
sysparm_display_value	Флаг, определяющий тип возвращаемых данных. Валидные значения: 1 – возвращает отображаемое значение поля. 0 – возвращает значение поля из базы данных. Значение по умолчанию: 0.
sysparm_exclude_reference_link	1 – исключить ссылки Table API для ссылочных полей. 0 – включить ссылки Table API для ссылочных полей. Значение по умолчанию: 0.
sysparm_fields	Список полей, разделенных запятой, которые должны вернуться в ответе. Параметр поддерживает использование dot-walking. Dot-walking не работает для таблицы Запланированные задания (sys_schedule_job), ее дочерних таблиц и таблицы Индикаторы (sys_indicator), так как после создания запись проходит обработку и не сразу появляется в базе данных. Пример значения: number,caller.phone
sysparm_view	Представление формы, поля которого должны вернуться в ответе. Обратите внимание, что этот параметр может быть переопределен параметром sysparm_fields. Из набора колонок представления, указанного в sysparm_view, выводятся только те, что указаны в sysparm_fields. Если указаны поля в sysparm_fields, которых нет в выбранном представлении, оно не выведется. Если параметр не задан, в ответе на запрос возвращаются значения всех колонок таблицы.
sysparm_limit	Максимальное количество результатов, возвращаемое запросом. Значение по умолчанию: 20.
sysparm_page	Номер страницы, с которой начнется чтение. Например, если значение параметра sysparm_limit – 40, а у sysparm_page значение равно двум, то ответ будет включать записи 41–80. Значение по умолчанию: 1.

внимание

Используйте тело запроса типа raw JSON вместо form-data.

HTTP
GET /rest/v1/table/task?sysparm_query=active=1&sysparm_fields=number,caller&sysparm_limit=1&sysparm_exclude_reference_link=true HTTP/1.1
Host: sandbox-01.dev.simpleone.ru
Authorization: Bearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu

Ответ

{
    "status": "OK",
    "data": [
        {
            "number": "TSK0000006",
            "caller": 155931135900000001
        }
    ]
}

Операция UPDATE

Для операции обновления доступны два метода: PUT и PATCH. PUT обновляет запись целиком, при этом любые поля, не включенные в тело запроса, будут перезаписаны значениями null или по умолчанию. PATCH обновляет только те поля, которые указаны в теле запроса, без изменения остальных полей записи.

Параметры тела

Вы можете указать необходимое количество колонок и их значений.

Параметр	Значение
column_name	column_value

Используйте следующие параметры с этим методами PUT и PATCH:

Параметр	Описание
sysparm_display_value	Флаг, определяющий тип возвращаемых данных. Валидные значения: 1 – возвращает отображаемое значение поля. 0 – возвращает значение поля из базы данных. Значение по умолчанию: 0.
sysparm_exclude_reference_link	Флаг, указывающий на исключение ссылок Table API (/rest/v1/table/) для ссылочных полей. Валидные значения: 1 – исключить ссылки Table API для ссылочных полей. 0 – включить ссылки Table API для ссылочных полей. Значение по умолчанию: 0.
sysparm_fields	Список полей, разделенных запятой, которые должны вернуться в ответе. Параметр поддерживает использование dot-walking. Dot-walking не работает для таблицы Запланированные задания (sys_schedule_job), ее дочерних таблиц и таблицы Индикаторы (sys_indicator), так как после создания запись проходит обработку и не сразу появляется в базе данных. Пример значения: number,caller.phone
sysparm_view	Представление формы, поля которого должны вернуться в ответе. Обратите внимание, что этот параметр может быть переопределен параметром sysparm_fields. Из набора колонок представления, указанного в sysparm_view, выводятся только те, что указаны в sysparm_fields. Если указаны поля в sysparm_fields, которых нет в выбранном представлении, оно не выведется. Если параметр не задан, в ответе на запрос возвращаются значения всех колонок таблицы.

внимание

Используйте тело запроса типа raw JSON вместо form-data.

PUT

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

Пример:

PUT /rest/v1/table/{tableName}/{sys_id}

HTTP
PUT /rest/v1/table/task/166032552604350116 HTTP/1.1
Host: sandbox-01.dev.simpleone.ru
Authorization: Bearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu
Content-Type: application/json
Content-Length: 20
 
{
  "state": "3"
}

Ответ

{
    "status": "OK",
    "data": [
    {
        "sys_id": "166032552604350116",
        "state": "3",
        "priority": null,
        "urgency": null,
        "impact": null,
        "assigned_user": null,
        "assignment_group": null,
        "wf_executing_activity": null,
        "closed_by": null,
        "followers_list": null,
        "parent_id": null,
        "opened_by": null,
        "caller":
        {
            "value": "155931135900000001",
            "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
        },
        "contact": null,
        "service": null,
        "screenshot": null,
        "short_description": null,
        "work_notes": null,
        "active": true,
        "closed_at": null,
        "sla_due": null,
        "sys_updated_at": "2022-08-13 13:46:11",
        "sys_created_at": "2022-08-12 17:32:06",
        "description": null,
        "number": "TSK0000014",
        "subject": "Kickoff meeting",
        "additional_comments": null,
        "comments": null,
        "opened_at": "2022-08-12 17:32:06",
        "due_date": null,
        "attention_required": false,
        "company":
        {
            "value": "166032365806600708",
            "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/org_company/166032365806600708"
        },
        "approval_state": "not_requested",
        "sys_db_table_id": "155931135900000083",
        "display_name": "TSK0000014 Kickoff meeting",
        "sys_updated_by":
        {
            "value": "155931135900000001",
            "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
        },
        "sys_created_by":
        {
            "value": "155931135900000001",
            "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
        }
    }]
}

PATCH

Используйте метод для частичного обновления записей. Этот метод обновляет отдельные поля записи в указанной таблице, используя значения, которые определены в теле запроса.

Пример:

PATCH /rest/v1/table/{tableName}/{sys_id}

HTTP
PATCH /rest/v1/table/task/166032552604350116 HTTP/1.1
Host: sandbox-01.dev.simpleone.ru
Authorization: Bearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu
Content-Type: application/json
Content-Length: 43
 
{
  "description": "Some description"
}

Ответ

{
    "status": "OK",
    "data": [
        {
            "active": true,
            "additional_comments": null,
            "approval_state": "not_requested",
            "assigned_user": null,
            "assignment_group": null,
            "attention_required": false,
            "caller": {
                "value": "155931135900000001",
                "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
            },
            "closed_at": null,
            "closed_by": null,
            "comments": null,
            "company": null,
            "contact": null,
            "description": "Some description",
            "display_name": "TSK0000005 Some subject",
            "due_date": null,
            "followers_list": null,
            "impact": "2",
            "number": "TSK0000005",
            "opened_at": "2023-08-10 11:55:30",
            "opened_by": null,
            "parent_id": null,
            "priority": "2",
            "screenshot": null,
            "service": {
                "value": "157416651911910348",
                "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/sys_cmdb_ci_service/157416651911910348"
            },
            "short_description": null,
            "sla_due": null,
            "state": "1",
            "state_changed_at": "2023-08-10 11:55:30",
            "subject": "Some subject",
            "sys_created_at": "2023-08-10 11:55:30",
            "sys_created_by": {
                "value": "155931135900000001",
                "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/155931135900000001"
            },
            "sys_db_table_id": "155931135900000083",
            "sys_id": "169166853014539923",
            "sys_updated_at": "2023-08-10 11:56:25",
            "sys_updated_by": {
                "value": "169166788816565275",
                "link": "http://sandbox-01.dev.simpleone.ru/rest/v1/table/user/169166788816565275"
            },
            "urgency": "2",
            "wf_executing_activity": null,
            "work_notes": null
        }
    ]
}

Операция DELETE

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

Пример:

DELETE /rest/v1/table/{tableName}/{sys_id}

Возможно два типа ответа:

Запись была успешно удалена.
Возникла ошибка.

Пример:

HTTP
DELETE /rest/v1/table/sys_filter/166039918402151705 HTTP/1.1
Host: sandbox-01.dev.simpleone.ru
Authorization: Bearer 70xlHwLAgSeBKF7Dafbu-lcUrWlvw4eu

Ответ об успешном удалении
{
    "status": "OK",
    "data": {
        "description": "Records successfully deleted."
}
}

Ответ о возникновении ошибки
{
    "status": "ERROR",
    "error_type": "SERVER",
    "errors": [
        {
            "message": "You have no access to delete this records."
        }
    ]
}

Авторизация​

Операция CREATE​

Операция READ​

Операция UPDATE​

PUT​

PATCH​

Операция DELETE​

Авторизация

Операция CREATE

Операция READ

Операция UPDATE

PUT

PATCH

Операция DELETE