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.


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

Флаг, указывающий на исключение ссылок Table API (/rest/v1/table/) для ссылочных полей.

Валидные значения:

  • 1 – исключить ссылки Table API для ссылочных полей.
  • 0 – включить ссылки 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 

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

ParameterDescription
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.

Пример значения: 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."
        }
    ]
}