API - Ресурсно-сервисная модель
Для выполнения запроса к API необходима дополнительная авторизация.
Используйте в запросе заголовок Authorization: Bearer <персональный токен>
.
Получение доступных типов КЕ
GET /api/public/sm/v2/rsm/config-item-types
Запрос возвращает список моделей типов КЕ.
Получение доступных рабочих групп
GET /api/public/sm/v2/rsm/work-groups
Запрос возвращает список моделей рабочих групп.
Получение всех доступных КЕ
GET /api/public/sm/v2/rsm/config-items?page=1&perPage=-1&search=sample&sortCol=id&sortDir=asc&skip=0
Запрос возвращает список моделей КЕ с минимальным набором атрибутов: идентификатор id
и имя name
.
Параметры запроса
Название параметра | Тип параметра | Описание параметра |
---|---|---|
page | number | Номер страницы |
perPage | number | Количество записей на одну страницу. Если -1 - будут возвращены все КЕ |
search | string/null | Строка поиска |
sortCol | string/null | Название поля, по которому выполняется сортировка |
sortDir | string/null | Направление сортировки (asc/desc) |
skip | number | Количество записей, которое требуется пропустить |
Получение КЕ по идентификатору
GET /api/public/sm/v2/rsm/config-items/{id}?includeState=false&includeHealth=false
Запрос возвращает модель КЕ, запрошенной по идентификатору.
Параметры запроса
Название параметра | Тип параметра | Описание параметра |
---|---|---|
includeState | boolean | Включить информацию по статусу КЕ |
includeHealth | boolean | Включить информацию по здоровью КЕ |
Коды ответов
Код ответа | Описание |
---|---|
400 | Неправильный идентификатор КЕ |
403 | У вас недостаточно прав для чтения КЕ |
404 | КЕ с идентификатором {id} не найдена |
Получение списка КЕ по фильтру
POST /api/public/sm/v2/rsm/config-items/filter?page=1&perPage=-1&search=sample&sortCol=id&sortDir=asc&skip=0
При успешном исполнении запроса возвращается список моделей КЕ, соответствующих условиям фильтра, с минимальным набором атрибутов: идентификатор id
, имя name
и словарь меток labels
.
Параметры запроса
Название параметра | Тип параметра | Описание параметра |
---|---|---|
page | number | Номер страницы |
perPage | number | Количество записей на одну страницу. Если -1 - будут возвращены все КЕ |
search | string/null | Строка поиска |
sortCol | string/null | Название поля, по которому выполняется сортировка |
sortDir | string/null | Направление сортировки (asc/desc) |
skip | number | Количество записей, которое требуется пропустить |
Тело запроса
{
"ids": [1, 2, 3],
"names": ["Sample CI 1", "Sample CI 2"],
"labels": {
"single_label": "value",
"multi_label": ["value_a", "value_b"],
"label_with_any_value": null
},
"stageCategories": ["Category1", "Category2"]
}
Поля тела запроса
Название поля | Тип поля | Описание |
---|---|---|
ids | number[] or null | Список идентификаторов КЕ. Если null , то любые |
names | string[] or null | Список названий КЕ. Если null , то любые |
labels | object or null | Словарь меток КЕ. Если null , то любые |
stageCategories | string[] or null | Список категорий стадии жизненного цикла. Если null , то любые |
-
В искомых КЕ должны присутствовать все указанные метки. Если для метки указано одно или несколько значений, то в искомой КЕ должно присутствовать хотя бы одно из значений для данной метки. Если значение метки в фильтре
null
, фильтрация осуществляется только по названию метки. -
Возможные значения категорий жизненного цикла КЕ
stageCategories
- Created - КЕ создана
- Deleted - КЕ удалена
- Active - Активная КЕ
- Archive - Архивная КЕ
Получение списка КЕ по расширенному фильтру
POST /api/public/sm/v2/rsm/config-items/filter/extended?page=1&perPage=-1&search=sample&sortCol=id&sortDir=asc&skip=0&fieldMask=id,name
При успешном исполнении запроса возвращается список расширенной модели КЕ, соответствующих условиям фильтра.
Параметры запроса
Название параметра | Тип параметра | Описание параметра |
---|---|---|
page | number | Номер страницы |
perPage | number | Количество записей на одну страницу. Если -1 - будут возвращены все КЕ |
search | string/null | Строка поиска |
sortCol | string/null | Название поля, по которому выполняется сортировка |
sortDir | string/null | Направление сортировки (asc/desc) |
skip | number | Количество записей, которое требуется пропустить |
fieldMask | string | Маска полей |
- Маска полей - представляет собой строку с названиями полей из расширенной модели КЕ, разделённые через запятую (например,
id,name,ownerWorkGroup
). В ответе на запрос будут указаны только поля, которые указаны в маске. По умолчанию возвращается только id. Данный параметр позволяет облегчить запрос к API путем указания только нужных полей в ответе.
Тело запроса
{
"ids": [1, 2, 3],
"names": ["Sample CI 1", "Sample CI 2"],
"typeIds": [1, 2, 3],
"stageCategories": ["Category1", "Category2"],
"labels": {
"single_label": "value",
"multi_label": ["value_a", "value_b"],
"label_with_any_value": null
},
"ownerWorkGroupIds": [1, 2, 3]
}
Поля тела запроса
Название поля | Тип поля | Описание |
---|---|---|
ids | number[] or null | Список идентификаторов КЕ. Если null , то любые |
names | string[] or null | Список названий КЕ. Если null , то любые |
typeIds | number[] or null | Список идентификаторов типов КЕ. Если null , то любые |
stageCategories | string[] or null | Список категорий стадии жизненного цикла. Если null , то любые |
labels | object or null | Словарь меток КЕ. Если null , то любые |
ownerWorkGroupIds | number[] or null | Список идентификаторов рабочих групп-владельцев. Если null , то любые |
-
В искомых КЕ должны присутствовать все указанные метки. Если для метки указано одно или несколько значений, то в искомой КЕ должно присутствовать хотя бы одно из значений для данной метки. Если значение метки в фильтре
null
, фильтрация осуществляется только по названию метки. -
Возможные значения категорий жизненного цикла КЕ
stageCategories
- "Created" - КЕ создана
- "Deleted" - КЕ удалена
- "Active" - Активная КЕ
- "Archive" - Архивная КЕ
Получение списка КЕ по идентификаторам
GET /api/public/sm/v2/rsm/config-items/batch?includeState=false&includeHealth=false
При успешном исполнении запроса возвращается список моделей КЕ.
В случае возникновения ошибки при получении отдельной КЕ, модель этой КЕ будет отсутствовать в результирующем списке. Если возникли ошибки при получении всех КЕ, запрос вернет пустой список.
Параметры запроса
Название параметра | Тип параметра | Описание параметра |
---|---|---|
includeState | boolean | Включить информацию по статусу КЕ |
includeHealth | boolean | Включить информацию по здоровью КЕ |
Тело запроса
[1,2,3]
Поля тела запроса
Название поля | Тип поля | Описание |
---|---|---|
ids | number[] | Список идентификаторов КЕ |
Коды ответов
Код ответа | Описание |
---|---|
400 | Список идентификаторов КЕ пустой |
Получение КЕ по уникальным ключам атрибутов
POST /api/public/sm/v2/rsm/config-items/attributes/unique-keys
При успешном исполнении запроса возвращается модель КЕ, полученной по уникальным ключам атрибутов.
Тело запроса
{
"configItemTypeId": 0,
"attributes": {
"prop1": "value1",
"prop2": "value2"
}
}
Поля тела запроса
Название поля | Тип поля | Описание |
---|---|---|
configItemTypeId | number | Идентификатор типа КЕ |
attributes | object | Ключевые атрибуты КЕ |
Коды ответов
Код ответа | Описание |
---|---|
403 | Недостаточно прав для получения информации о КЕ |
404 | КЕ не найдена |
Создание КЕ
POST /api/public/sm/v2/rsm/config-items
Запрос возвращает модель созданной КЕ.
Параметры запроса
Название параметра | Тип параметра | Описание |
---|---|---|
makeNameUnique | boolean | Создать КЕ, если название уже занято |
- Параметр
makeNameUnique
:true
- Если в CMDB существует КЕ c указанным названием будет создана новая КЕ с добавлением индекса в название КЕfalse
- Если в CMDB существует КЕ c указанным названием будет возвращена ошибка
Тело запроса
{
"name": "Name",
"description": "Description",
"parent": {
"id": 0
},
"configItemType": {
"id": 0
},
"ownerWorkGroup": {
"id": 0
},
"labels": {
"label_a_name": "label_value",
"label_b_name": ["label_value_1", "label_value_2"],
"label_c_name": null
},
"sharedToWorkGroups": [{
"workGroupId": 0,
"shareType": "ConfigItem",
"grants": ["read"]
}]
}
Поля тела запроса
Название поля | Тип поля | Описание поля |
---|---|---|
name | string | Наименование КЕ |
description | string | Описание КЕ |
parent | { id: number } / null | Идентификатор родительской КЕ, с которой требуется установить связь при создании КЕ. Если указан null или 0 , то КЕ будет создана как корневой элемент |
configItemType | { id: number } / null | Тип КЕ. Если null , то будет присвоен тип по умолчанию |
ownerWorkGroup | { id: number } / null | Рабочая группа-владелец КЕ. Если указан идентификатор родительской КЕ, то РГ-владелец будет установлен такой же, как и у этой КЕ |
labels | object / null | Словарь меток КЕ |
sharedToWorkGroups | object[] | Список моделей предоставления прав для конкретных рабочих групп |
Предоставляемые рабочим группам права
Коды ответов
Код ответа | Описание |
---|---|
201 | КЕ успешно создана |
400 | Пустое тело запроса |
400 | Неверная модель данных в теле запроса |
400 | Требуется указать наименование КЕ |
400 | Требуется указать рабочую группу-владельца КЕ |
400 | Недопустимое значение идентификатора КЕ |
400 | Недопустимое значение идентификатора рабочей группы |
400 | КЕ с идентификатором {id} уже в CMDB |
400 | Родительская КЕ с идентификатором {id} не существует в CMDB |
400 | КЕ с именем {name} уже существует для типа {typeName} |
400 | Тип КЕ с идентификатором {id} не найден в пространстве пользователя |
400 | Указанный набор прав не соответствует ни одному из существующих прав. Доступ к КЕ не передан другим рабочим группам |
403 | Недостаточно прав для добавления КЕ в РГ |
404 | Рабочая группа с идентификатором {id} не найдена |
Возможна ситуация, при которой КЕ может быть успешно создана, однако если в запросе было так же указано предоставление доступа к КЕ другим РГ с некорректными правами, то доступ к КЕ не буден предоставлен другим РГ. Будет получено сообщение: "Указанный набор прав не соответствует ни одному из существующих прав. Доступ к КЕ не передан другим рабочим группам."
Пакетное создание нескольких КЕ
POST /api/public/sm/v2/rsm/config-items/batch?makeNamesUnique=false
Запрос возвращает список моделей созданных КЕ.
В случае возникновения ошибки при создании отдельной КЕ, модель этой КЕ будет отсутствовать в результирующем списке.
Если возникли ошибки при создании всех КЕ, запрос вернет пустой список.
Параметры запроса
Название параметра | Тип параметра | Описание |
---|---|---|
makeNameUnique | boolean | Создать КЕ, если название уже занято |
- Параметр
makeNameUnique
:true
- Если в CMDB существует КЕ c указанным названием будет создана новая КЕ с добавлением индекса в название КЕfalse
- Если в CMDB существует КЕ c указанным названием будет возвращена ошибка
Тело запроса
[{
"name": "Name",
"description": "Description",
"parent": {
"id": 0
},
"configItemType": {
"id": 0
},
"ownerWorkGroup": {
"id": 0
},
"labels": {
"label_a_name": "label_value",
"label_b_name": ["label_value_1", "label_value_2"],
"label_c_name": null
},
"sharedToWorkGroups": [{
"workGroupId": 0,
"shareType": "ConfigItem",
"grants": ["read"]
}]
}]
Поля тела запроса
Название поля | Тип поля | Описание поля |
---|---|---|
name | string | Наименование КЕ |
description | string | Описание КЕ |
parent | { id: number } / null | Идентификатор родительской КЕ, с которой требуется установить связь при создании КЕ. Если указан null или 0 , то КЕ будет создана как корневой элемент |
configItemType | { id: number } / null | Тип КЕ. Если null , то будет присвоен тип по умолчанию |
ownerWorkGroup | { id: number } / null | Рабочая группа-владелец КЕ. Если указан идентификатор родительской КЕ, то РГ-владелец будет установлен такой же, как и у этой КЕ |
labels | object / null | Словарь меток КЕ |
sharedToWorkGroups | object[] | Список моделей предоставления прав для конкретных рабочих групп |
Предоставляемые рабочим группам права
Коды ответов
Код ответа | Описание |
---|---|
201 | КЕ успешно создана |
400 | Пустое тело запроса |
400 | Неверная модель данных в теле запроса |
400 | Требуется указать наименование КЕ |
400 | Требуется указать рабочую группу-владельца КЕ |
400 | Недопустимое значение идентификатора КЕ |
400 | Недопустимое значение идентификатора рабочей группы |
400 | КЕ с идентификатором {id} уже в CMDB |
400 | Родительская КЕ с идентификатором {id} не существует в CMDB |
400 | КЕ с именем {name} уже существует для типа {typeName} |
400 | Тип КЕ с идентификатором {id} не найден в пространстве пользователя |
400 | Указанный набор прав не соответствует ни одному из существующих прав. Доступ к КЕ не передан другим рабочим группам |
403 | Недостаточно прав для добавления КЕ в РГ |
404 | Рабочая группа с идентификатором {id} не найдена |
Возможна ситуация, при которой КЕ может быть успешно создана, однако если в запросе было так же указано предоставление доступа к КЕ другим РГ с некорректными правами, то доступ к КЕ не буден предоставлен другим РГ. Будет получено сообщение: "Указанный набор прав не соответствует ни одному из существующих прав. Доступ к КЕ не передан другим рабочим группам."
Удаление КЕ
DELETE /api/public/sm/v2/rsm/config-items/{id}?applyGrants=false
{id}
– идентификатор удаляемой КЕ.
При успешном исполнении запроса возвращается пустой ответ.
Параметры запроса
Название параметра | Тип параметра | Описание параметра |
---|---|---|
applyGrants | boolean | Если задано true – применить настройки доступа к подчинённым КЕ. По умолчанию – false |
Коды ответов
Код ответа | Описание |
---|---|
204 | КЕ успешно удалена |
400 | Недопустимое значение идентификатора КЕ |
403 | Недостаточно прав для удаления КЕ |
404 | КЕ с идентификатором {id} не найдена |
Массовое удаление КЕ
DELETE /api/public/sm/v2/rsm/config-items/batch?applyGrants=false
Тело запроса
[1, 2, 3]
При успешном исполнении запроса возвращается пустой ответ.
Параметры запроса
Название параметра | Тип параметра | Описание параметра |
---|---|---|
applyGrants | boolean | Если задано true – применить настройки доступа к подчинённым КЕ. По умолчанию – false |
Коды ответов
Код ответа | Описание |
---|---|
204 | КЕ успешно удалена |
400 | Недопустимое значени е идентификатора КЕ |
403 | Недостаточно прав для удаления КЕ |
404 | КЕ с идентификатором {id} не найдена |
Изменение основной информации КЕ
PUT /api/public/sm/v2/rsm/config-items/{id}?makeNameUnique=false
{id}
– идентификатор обновляемой КЕ.
Запрос возвращает модель обновлённой КЕ.
Параметры запроса
Название параметра | Тип параметра | Описание |
---|---|---|
makeNameUnique | boolean | Создать КЕ, если название уже занято |
- Параметр
makeNameUnique
:true
- Если в CMDB существует КЕ c указанным названием будет создана новая КЕ с добавлением индекса в название КЕfalse
- Если в CMDB существует КЕ c указанным названием будет возвращена ошибка
Тело запроса
{
"name": "Name",
"description": "Description",
"configItemType": {
"id": 0
},
"ownerWorkGroup": {
"id": 0
},
"labels": {
"label_a_name": "label_value",
"label_b_name": ["label_value_1", "label_value_2"],
"label_c_name": null
}
}
Поля тела запроса
Название поля | Тип поля | |
---|---|---|
name | string | Наименование КЕ |
description | string | Описание КЕ |
configItemType | { id: number } / null | Тип КЕ. Если null , то будет присвоен тип по умолчанию |
ownerWorkGroup | { id: number } / null | Рабочая группа-владелец КЕ |
labels | object / null | Словарь меток КЕ |
Коды ответов
Код ответа | Описание |
---|---|
400 | Требуется указать наименование КЕ |
400 | Требуется указать рабочую группу-владельца КЕ |
400 | Недопустимое значение идентификатора КЕ |
400 | Недопустимое значение идентификатора рабочей группы |
400 | КЕ с именем {name} уже существует для типа {typeName} |
400 | Тип КЕ с идентификатором {id} не найден в пространстве пользователя |
403 | Недостаточно прав для обновления КЕ |
404 | КЕ с идентификатором {id} не найдена |
404 | Рабочая группа с идентификатором {id} не найдена |
Изменение основной части информации нескольких КЕ
PATCH /api/public/sm/v2/rsm/config-items/batch?makeNamesUnique=false
Запрос возвращает список моделей обновлённых КЕ.
Параметры запроса
Название параметра | Тип параметра | Описание |
---|---|---|
makeNameUnique | boolean | Создать КЕ, если название уже занято |
- Параметр
makeNameUnique
:true
- Если в CMDB существует КЕ c указанным названием будет создана новая КЕ с добавлением индекса в название КЕfalse
- Если в CMDB существует КЕ c указанным названием будет возвращена ошибка
Тело запроса
[{
"id": 0,
"name": "Name",
"configItemType": {
"id": 0
},
"labels": {
"label_a_name": "label_value",
"label_b_name": ["label_value_1", "label_value_2"],
"label_c_name": null
}
}]
Поля тела запроса
Название поля | Тип поля | |
---|---|---|
id | number | Идентификатор КЕ |
name | string | Наименование КЕ. Если null , то изменений не последует |
configItemType | { id: number } / null | Тип КЕ. Если null , то изменений не последует |
labels | object / null | Словарь меток КЕ. Если null , то изменений не последует |
Коды ответов
Код ответа | Описание |
---|---|
400 | Требуется указать наименование КЕ |
400 | Требуется указать рабочую группу-владельца КЕ |
400 | Недопустимое значение идентификатора КЕ |
400 | Недопустимое значение идентификатора рабочей группы |
400 | КЕ с именем {name} уже существует для типа {typeName} |
400 | Тип КЕ с идентификатором {id} не найден в пространстве пользователя |
403 | Недостаточно прав для обновления КЕ |
404 | КЕ с идентификатором {id} не найдена |
404 | Рабочая группа с идентификатором {id} не найдена |
Предоставление доступа к КЕ
POST /api/public/sm/v2/rsm/config-items/{id}/work-groups
{id}
– идентификатор КЕ.
Запрос возвращает модель обновлённой КЕ.
Для выполнения данного запроса должен использоваться API токен со следующими условиями:
- У пользователя, владельца API токена есть доступ на редактирование КЕ, к которой нужно предоставить доступ
- У этого же пользователя есть доступ к РГ, которой планируется предоставить доступ, с любой ролью
Тело запроса
{
"workGroupId": 0,
"shareType": "ConfigItem",
"grants": ["read"]
}
Поля тела запроса
Название поля | Тип поля | Описание поля |
---|---|---|
workGroupId | number | Идентификатор рабочей группы. 0 – все рабочие группы, включая будущие |
shareType | string | Тип предоставляемых прав |
grants | string[] | Предоставляемые рабочим группам права |
Коды ответов
Код ответа | Описание |
---|---|
400 | Требуется указать список предоставляемых прав |
400 | Недопустимое значение идентификатора КЕ |
400 | Недопустимое значение идентификатора рабочей группы |
400 | Правило доступа уже установлено |
403 | Недостаточно прав для предоставления доступа к КЕ |
404 | КЕ с идентификатором {id} не найдена |
404 | Рабочая группа с идентификатором {id} не найдена |
Обновление предоставления доступа к КЕ
PUT /api/public/sm/v2/rsm/config-items/{id}/work-groups/{sharedId}
{id}
– идентификатор КЕ.
{sharedId}
- идентификатор модели предоставления доступа к КЕ.
Запрос возвращает модель обновлённой КЕ.
Тело запроса
{
"workGroupId": 0,
"shareType": "ConfigItem",
"grants": ["read"]
}
Поля тела запроса
Название поля | Тип поля | Описание поля |
---|---|---|
id | number | Идентификатора модели предоставления доступа к КЕ |
shareType | string | Тип предоставляемых прав |
grants | string[] | Предоставляемые рабочим группам права |
Коды ответов
Код ответа | Описание |
---|---|
400 | Требуется указать идентификатор рабочей группы |
400 | Требуется указать список предоставляемых прав |
400 | Недопустимое значение идентификатора КЕ |
400 | Недопустимое значение идентификатора модели предоставления доступа к КЕ |
401 | Не удалось выполнить авторизацию пользователя |
403 | Недостаточно прав для обновления предоставленного доступа к КЕ |
404 | КЕ с идентификатором {id} не найдена |
404 | Модель предоставления доступа к КЕ с идентификатором{id} не найдена |
Удаление предоставления доступа к КЕ
DELETE /api/public/sm/v2/rsm/config-items/{id}/work-groups/{sharedId}
{id}
– идентификатор КЕ.
{sharedId}
– идентификатор модели предоставления доступа к КЕ.
Запрос возвращает модель обновлённой КЕ.
Коды ответов
Код ответа | Описание |
---|---|
204 | Запрос успешно исполнен |
400 | Недопустимое значение идентификатора КЕ |
400 | Недопустимое значение идентификатора модели предоставления доступа к КЕ |
403 | Недостаточно прав для удаления предоставления доступа к КЕ |
404 | КЕ с идентификатором {id} не найдена |
404 | Модель предоставления доступа к КЕ с идентификатором {id} не найдена |