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 | Флаг, определяющий тип возвращаемых данных. Валидные значения:
Значение по умолчанию: 0. |
sysparm_exclude_reference_link | Флаг, указывающий на исключение ссылок 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.
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 | Флаг, определяющий тип возвращаемых данных. Валидные значения:
Значение по умолчанию: 0. |
sysparm_exclude_reference_link | Флаг, указывающий на исключение ссылок Table API ( Валидные значения:
Значение по умолчанию: 0. |
sysparm_fields | Список полей, разделенных запятой, которые должны вернуться в ответе. Параметр поддерживает использование dot-walking. Пример значения: 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.
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 |
Используйте следующие параметры с этим методом:
Parameter | Description |
---|---|
sysparm_display_value | Флаг, определяющий тип возвращаемых данных. Валидные значения:
Значение по умолчанию: 0. |
sysparm_exclude_reference_link | Флаг, указывающий на исключение ссылок Table API ( Валидные значения:
Значение по умолчанию: 0. |
sysparm_fields | Список полей, разделенных запятой, которые должны вернуться в ответе. Параметр поддерживает использование dot-walking. Пример значения: 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}
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}
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}
Возможно два типа ответа:
- Запись была успешно удалена.
- Возникла ошибка.
Пример:
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." } ] }
- No labels