Перейти к основному содержимому
Версия: 1.20.1

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_namecolumn_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 значение равно двум, то ответ будет включать записи 21–60..
Значение по умолчанию: 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_namecolumn_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."
}
]
}