Общие сведения

Продукт «Служба управления конфигурациями "Осмакс"» предоставляет RESTful API для:

Авторизация

Для доступа к конечным точкам (endpoints) API необходимо в заголовке HTTP-запроса Authorization предоставить билет (ticket) Kerberos.

Чтобы получить билет (ticket) Kerberos, выполните шаги:

  1. Убедитесь, что на машине, с которой вы будете выполнять вызов API-методов, настроено окружение для аутентификации Kerberos — установлен и настроен Kerberos-клиент.

  1. Получите билет (ticket) Kerberos, используя команду kinit.

    kinit -v <имя пользователя>@<имя домена>

    Пример команды:

    kinit -v vivanov@OSMAX.TERRA.INNO.TECH

    Пример вывода:

    Placing tickets for `vivanov@OSMAX.TERRA.INNO.TECH` in cache `API:AS8FAF0V-AS4S-V39T-T4ZE-12DE34N4N77JA`

  2. Для проверки валидности полученного билета (ticket) отобразите список кэшированных билетов (tickets) Kerberos, выполнив команду klist.

    Пример вывода:

    Credentials cache: API:EC59A7DE-43A4-43E3-A349-56F92E31A71D
        Principal: aarshavin@OSMAX.TERRA.INNO.TECH

  Issued                Expires               Principal
Feb 13 12:51:40 2024  Feb 13 22:51:40 2024  krbtgt/OSMAX.TERRA.INNO.TECH@OSMAX.TERRA.INNO.TECH
Feb 13 12:51:47 2024  Feb 13 22:51:40 2024  HTTP/staging-osmax.terra.inno.tech@OSMAX.TERRA.INNO.TECHH

Чтобы подставить значение полученного билета (ticket) в заголовок Authorization при вызове API-метода, используйте утилиту cURL.

Ниже рассмотрен вызов API-метода на примере getConfigurationList — получение списка конфигураций:

curl -x POST --location "https://"staging-osmax-terra-inno-tech/api/v1/configurations/search"
-Н "Content-type: application/json" --negotiate --user : | jq

Где:

  • curl — утилита командной строки, которая позволяет отправлять HTTP-запросы на сервер и получать ответы;

  • -x POST — флаг, указывающий метод запроса, который используется для отправки данных на сервер;

  • --location — флаг, указывающий curl на необходимость следовать перенаправлениям, если сервер возвращает HTTP-код 3xx;

  • https://staging-rt-terra-inno-tech — URL-адрес сервера, на который будет отправлен запрос;

  • -H "Content-type: application/json" — флаг, который добавляет заголовок к запросу. В данном примере заголовок Content-type устанавливается в значение application/json, что указывает на то, что тело запроса будет передано в формате JSON;

  • --negotiate — флаг, указывающий на использование аутентификации по протоколу Kerberos (Negotiate);

  • --user : — флаг, который определяет имя пользователя для аутентификации. Двоеточие в сочетании с флагом --negotiate указывает curl, что необходимо получить билет (ticket) для указанного хоста от имени данного пользователя и подставить в заголовок Authorization.

Пример ответа:

{
  "configurations": [
    {
      "id": 5467,
      "displayName": "Яндекс браузер",
      "description": "Браузер от компании Яндекс",
      "fullDescription": "Браузер от компании Яндекс.(...)",
      "guide": "Если вы не сделали его основным, при его запуске может появляться окно Сделать этот браузер основным?  Чтобы окно больше не показывалось, включите опцию Больше не спрашивать и нажмите Не сейчас.",
      "isApplication": true,
      "tags": [
        "Браузер"
      ],
      "categories": [
        "Сеть"
      ],
      "createdAt": "2023-08-27T09:37:40.000Z",
      "updatedAt": "2023-08-27T09:37:40.000Z",
      "createdBy": "vivanov@domain.local",
      "updatedBy": "vivanov@domain.local",
      "iconPath": "icons/123321-7cb06ef0-87ab-4a60-b20e-33c2d9725a09-open-office.png",
      "imagesPaths": [
        "images/123321-7cb06ef0-87ab-4a60-b20e-33c2d9725a09-open-office-screen03.jpg"
      ],
      "defaultVersion": 1234,
      "isActive": true
    }
  ],
  "meta": {
    "totalRecords": 1729,
    "pageSize": 20,
    "totalPages": 87,
    "currentPage": 2,
    "hasNext": true,
    "hasPrev": true
  }
}

Если при установке продукта в конфигурационном файле бэкенда application.properties каталога /opt/osmax-core задан параметр osmax.authorization.user-groups-white-list, доступ будет разрешен только пользователям, входящим в указанные группы (см. раздел «Предварительная конфигурация бэкенда. Параметры настройки авторизации и аутентификация»).

API логического модуля «Каталог конфигураций»

В разделе описаны методы API-интерфейса модуля «Каталог конфигураций», предназначенные для управления формулами SaltStack и управления конфигурациями:

  • deleteFormula — удаление формулы SaltStack из S3-совместимого хранилища;

  • getCategoryById — получение категории конфигурации по идентификатору;

  • updateCategoryById — изменение категории конфигурации по идентификатору;

* deleteCategoryById — удаление категории конфигурации по идентификатору;

  • createCategory — создание категории конфигурации;

  • getCategoriesList — получение списка категорий.

Метод deleteFormula

Удаление формулы из S3-совместимого хранилища.

DELETE /v2/formulas/{formulaName}

Параметр пути

Имя Описание Обязательный Тип

formulaName

Имя формулы

Да

string

Ответы

Код Сообщение Тип данных / объект схемы (DTO) Пример

200

Результат удаления формулы из S3-совместимого хранилища

S3ObjectDeleteResult

 
{
  "importResult": [
    {
      "server": "http://localhost:9000",
      "description": "Сообщение о результате выполнения операции",
      "status": "imported"
    },
    {
      "server": "http://localhost:9000",
      "description": "Сообщение о результате выполнения операции",
      "status": "imported"
    }
  ],
  "status": "imported"
}

401

Ошибка аутентификации

422

Ошибка операции над сущностью пакета из-за связи с активными версиями

ActiveVersionsRelatedEntityEditError

 
{
  "code": "validation_failed",
  "message": "Cannot reload formula with name ark since it is used by active versions",
  "versions": [
    {
      "versionId": 1234,
      "versionDisplayName": "23.5.0",
      "configurationId": 5467,
      "configurationDisplayName": "Яндекс браузер"
    }
  ]
}

500

Внутренняя ошибка

BasicError

 
{
  "code": "internal_error",
  "message": "Database is unavailable"
}

Метод getCategoryById

Получение категории конфигураций по идентификатору.

GET /v1/categories/{categoryId}

Параметр пути

Имя Описание Обязательный Тип Пример

categoryId

Идентификатор категории конфигурации

Да

string

Сеть

Ответы

Код Сообщение Тип данных / объект схемы (DTO) Пример

200

Перечень параметров категории конфигурации

CategoryResponse

 
{
  "createdAt": "2023-08-27T09:37:40.000Z",
  "color": "00ff00",
  "name": "Офис",
  "description": "Категория программ для работы в сети Интернет",
  "iconCode": "ms_office_icon",
  "id": "office",
  "updatedAt": "2023-08-27T09:37:40.000Z"
}

400

Некорректные параметры запроса

BasicError

 
{
  "code": "validation_failed",
  "message": "getCategoryById.categoryId: size must be between 3 and 64"
}

401

Ошибка аутентификации

404

Объект не найден

BasicError

 
{
  "code": "object_not_found",
  "message": "Category with id=officeCategory not found"
}

500

Внутренняя ошибка

BasicError

 
{
  "code": "internal_error",
  "message": "Database is unavailable"
}

Метод updateCategoryById

Изменение категории конфигураций по идентификатору.

PUT /v1/categories/{categoryId}

Параметр пути

Имя Описание Обязательный Тип Пример

categoryId

Идентификатор категории конфигурации

Да

string

Сеть

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

CategoryUpdateRequest

Пример запроса

{
  "color": "00ff00",
  "name": "Офис",
  "description": "Категория программ для работы в сети Интернет",
  "iconCode": "ms_office_icon"
}

Тип контента

application/json

Ответы

Код Сообщение Тип данных / объект схемы (DTO) Пример

200

Представление категории конфигурации

CategoryResponse

 
{
  "createdAt": "2023-08-27T09:37:40.000Z",
  "color": "00ff00",
  "name": "Офис",
  "description": "Категория программ для работы в сети Интернет",
  "iconCode": "ms_office_icon",
  "id": "office",
  "updatedAt": "2023-08-27T09:37:40.000Z"
}

400

Некорректные параметры запроса

BasicError

 
{
  "code": "validation_failed",
  "message": "updateCategoryById.categoryUpdateRequest.color: must match `[A-Fa-f0-9]+`"
}

401

Ошибка аутентификации

404

Объект не найден

BasicError

 
{
  "code": "object_not_found",
  "message": "Category with id=officeCategory not found"
}

500

Внутренняя ошибка

BasicError

 
{
  "code": "internal_error",
  "message": "Database is unavailable"
}

Метод deleteCategoryById

Удаление категории конфигурации по идентификатору.

DELETE /v1/categories/{categoryId}

Параметр пути

Имя Описание Обязательный Тип Пример

categoryId

Идентификатор категории конфигурации

Да

string

Сеть

Ответы

Код Сообщение Тип данных / объект схемы (DTO) Пример

204

Категория удалена

400

Некорректные параметры запроса

BasicError

 
{
  "code": "validation_failed",
  "message": "deleteCategoryById.categoryId: size must be between 3 and 64"
}

401

Ошибка аутентификации

404

Объект не найден

BasicError

 
{
  "code": "object_not_found",
  "message": "Category with id=officeCategory not found"
}

500

Внутренняя ошибка

BasicError

 
{
  "code": "internal_error",
  "message": "Database is unavailable"
}

Метод createCategory

Создание категории конфигурации.

POST /v1/categories

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

CategoryCreateRequest

Пример запроса

{
  "id": "office",
  "name": "Офис",
  "description": "Категория программ для работы в сети Интернет",
  "color": "00ff00",
  "iconCode": "ms_office_icon"
}

Тип контента

application/json

Ответы

Код Сообщение Тип данных / объект схемы (DTO) Пример

200

Набор параметров созданной категории конфигурации

CategoryResponse

 
{
  "createdAt": "2023-08-27T09:37:40.000Z",
  "color": "00ff00",
  "name": "Офис",
  "description": "Категория программ для работы в сети Интернет",
  "iconCode": "ms_office_icon",
  "id": "office",
  "updatedAt": "2023-08-27T09:37:40.000Z"
}

400

Некорректные параметры запроса

BasicError

 
{
  "code": "validation_failed",
  "message": "createCategory.createCategoryRequest.color: must match `[A-Fa-f0-9]+`"
}

401

Ошибка аутентификации

500

Внутренняя ошибка

BasicError

 
{
  "code": "internal_error",
  "message": "Database is unavailable"
}

Метод getCategoryList

Получение списка категорий конфигураций.

POST /v1/categories/search

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

Имя Описание Обязательный Тип Пример

page

Общее количество страниц

Нет

integer

2

pageSize

Количество элементов, возвращаемых в запросе

Нет

integer

20

Ответы

Код Сообщение Тип данных / объект схемы (DTO) Пример

200

Список категорий

CategoriesListResponse

 
{
  "meta": {
    "totalRecords": 1,
    "pageSize": 20,
    "totalPages": 1,
    "currentPage": 1,
    "hasNext": false,
    "hasPrev": false
  },
  "categories": [
    {
      "createdAt": "2023-08-27T09:37:40.000Z",
      "color": "00ff00",
      "name": "Офис",
      "description": "Категория программ для работы в сети Интернет",
      "iconCode": "ms_office_icon",
      "id": "office",
      "updatedAt": "2023-08-27T09:37:40.000Z"
    },
    {
      "createdAt": "2023-08-27T09:37:40.000Z",
      "color": "00ee00",
      "name": "Дизайн",
      "description": "Программы для дизайнерской разработки, создания макетов",
      "iconCode": "ms_design_icon",
      "id": "design",
      "updatedAt": "2023-08-27T09:37:40.000Z"
    }
  ]
}

400

Некорректные параметры запроса

BasicError

 
{
  "code": "validation_failed",
  "message": "getCategoriesList.page: must be greater than or equal to 1"
}

401

Ошибка аутентификации

500

Внутренняя ошибка

BasicError

 
{
  "code": "internal_error",
  "message": "Database is unavailable"
}

Описание параметров схемы

Ошибка обновления сущности из-за наличия связанных активных версий.

BasicError

Информация об ошибке.

Имя поля Обязательное Тип Описание Пример

code

Да

string

Код ошибки. Включает параметр ErrorCode. Возможные значения:

  • object_already_exists — объект уже существует;

  • object_not_found — объект не найден;

  • validation_failed — ошибка валидации;

  • authorization_failed — ошибка авторизации;

  • internal_error — внутренняя ошибка

validation_failed

message

Да

string

Сообщение об ошибке

Template contains not resolved variables

CategoryCreateRequest

Параметры для создания категории конфигураций.

Имя поля Обязательное Тип Описание Пример

id

Да

string

Идентификатор категории конфигураций (макс. длина: 64). Включает параметр CategoryId

Сеть

name

Да

string

Название категории конфигураций (макс. длина: 255). Включает параметр CategoryName

Офис

description

Нет

string

Описание категории конфигураций (макс. длина: 64). Включает параметр CategoryDescription

Категория программ для работы в сети Интернет

color

Да

string

Цвет в формате HEX (макс. длина: 6). Включает параметр HexColor

00ff00

iconCode

Да

string

Код изображения для категории (макс. длина: 255). Включает параметр IconCode

ms_office_icon

CategoryDescription

Описание категории конфигураций.

Тип: string.

Пример: Категория программ для работы в сети Интернет.

CategoryId

Идентификатор категории конфигураций (макс. длина: 64).

Тип: string.

Шаблон: [A-Za-z0-9_\-]+.

Пример: Сеть.

CategoriesListResponse

Список категорий конфигураций.

Имя поля Обязательное Тип Описание Пример

categories

Да

Список категорий конфигураций. Включает параметр CategoryResponse

meta

Да

Категории конфигураций. Включает параметр PaginationMetadata

CategoryName

Название категории конфигураций (макс. длина: 255).

Тип: string.

Пример: Офис.

CategoryResponse

Перечень параметров категории конфигураций.

Имя поля Обязательное Тип Описание Пример

id

Да

string

Идентификатор категории конфигураций (макс. длина: 64). Шаблон: [A-Za-z0-9_\-]+. Включает параметр CategoryId

Сеть

name

Да

string

Название категории конфигураций (макс. длина: 255). Включает параметр CategoryName

Офис

description

Нет

string

Описание категории конфигураций (макс. длина: 64). Включает параметр CategoryDescription

Категория программ для работы в сети Интернет

color

Да

string

Цвет в формате HEX. Шаблон: [A-Fa-f0-9]+. Включает параметр HexColor

00ff00

iconCode

Да

string

Код изображения для категории (макс. длина: 255). Включает параметр IconCode

ms_office_icon

createdAt

Нет

string

Дата создания

2023-08-27T09:37:40.000Z

updatedAt

Нет

string

Дата последнего изменения

2023-08-27T09:37:40.000Z

CategoryUpdateRequest

Параметры для обновления категории конфигураций.

Имя поля Обязательное Тип Описание Пример

name

Да

string

Название категории конфигураций (макс. длина: 255). Включает параметр CategoryName

Офис

description

Нет

string

Описание категории конфигураций (макс. длина: 64). Включает параметр CategoryDescription

Категория программ для работы в сети Интернет

color

Да

string

Цвет в формате HEX. Шаблон: [A-Fa-f0-9]+ (макс. длина: 6). Включает параметр HexColor

00ff00

iconCode

Да

string

Код изображения для категории (макс. длина: 255). Включает параметр IconCode

ms_office_icon

ErrorCode

Код ошибки.

Тип: string.

Возможные значения:

  • object_already_exists — объект уже существует;

  • object_not_found — объект не найден;

  • validation_failed — ошибка валидации;

  • authorization_failed — ошибка авторизации;

  • internal_error — внутренняя ошибка.

HexColor

Цвет в формате HEX (макс. длина: 6).

Тип: string.

Шаблон: [A-Fa-f0-9]+.

Пример: 00ff00.

IconCode

Код изображения для категории (макс. длина: 255).

Тип: string.

Пример: ms_office_icon.

PaginationMetadata

Метаданные постраничной навигации.

Имя поля Обязательное Тип Описание Пример

totalRecords

Да

integer

Общее количество записей

1729

pageSize

Да

integer

Количество возвращаемых элементов в запросе

20

totalPages

Да

integer

Общее количество страниц

87

currentPage

Да

integer

Номер текущей страницы

2

hasNext

Да

boolean

Признак наличия следующей страницы

true

hasPrev

Да

boolean

Признак наличия предыдущей страницы

true

RelatedActiveVersionsInfo S3ObjectDeleteResult S3ObjectImportStatus

Информация об активной версии.

S3ObjectDeleteResult

Результат удаления объекта.

Имя поля Обязательное Тип Описание Пример

status

Да

string

Статус нахождения объекта в хранилище. Включает параметр S3ObjectImportStatus. Возможные значения:

  • failed — не загружен;

  • imported — успешно загружен;

  • partially_imported — частично загружен;

  • deleted — удален

imported

importResult

Список результатов загрузки/удаления объекта. Включает параметр S3ObjectImportResult

S3ObjectImportResult

Результат загрузки/удаления объекта.

Имя поля Обязательное Тип Описание Пример

server

Нет

string

Имя/URI сервера

http://localhost:9000

description

Нет

string

Сообщение о результате выполнения операции

Операция выполнена успешно

status

Нет

string

Статус нахождения объекта на сервере. Включает параметр S3ServerObjectImportStatus. Возможные значения:

  • error — ошибка выполнения операции;

  • imported — успешно загружен;

  • deleted — удален

imported

S3ObjectImportStatus

Статус нахождения объекта в хранилище.

Тип: string.

Возможные значения:

  • failed — не загружен;

  • imported — успешно загружен;

  • partially_imported — частично загружен;

  • deleted — удален.

S3ServerObjectImportStatus

Статус нахождения объекта на сервере.

Тип: string.

Возможные значения:

  • error — ошибка выполнения операции;

  • imported — успешно загружен;

  • deleted — удален.

API логического модуля «Инвентаризация»

В разделе описаны методы API-интерфейса логического модуля «Инвентаризация», предназначенные для управления настройками продукта:

  • getSaltScheduleSettings — получение настроек расписания синхронизации агентов (minions) с сервером управления (master);

  • updateSaltScheduleSettings — изменение настроек расписания синхронизации агентов (minions) с сервером управления (master).

Группа методов getSaltScheduleSettings

Получение настроек расписания синхронизации агентов (minions) с сервером управления (master) в SaltStack.

В зависимости от типа операции вы можете отдельно получить настройки (интервал времени и допустимую задержку выполнения операции) для каждой из них, используя следующие методы:

  • GET /v1/app/settings/salt/schedules/highstate — применение назначенных конфигураций на устройствах;

  • GET /v1/app/settings/salt/schedules/grains — инвентаризация устройств;

  • GET /v1/app/settings/salt/schedules/grains_sync — синхронизация параметров Grains;

  • GET /v1/app/settings/salt/schedules/refresh_pillar — синхронизация файлов Pillar;

  • GET /v1/app/settings/salt/schedules/user_session_history — синхронизация данных о сессиях пользователей;

  • GET /v1/app/settings/salt/schedules/user_agent_installation — сбор данных об установке агента (minion);

  • GET /v1/app/settings/salt/schedules/software_inventory_sync — инвентаризация устройств с помощью модулей выполнения (execution modules), при которой собираются только измененные данные;

  • GET /v1/app/settings/salt/schedules/software_inventory_full_sync — полная инвентаризация устройств с помощью модулей выполнения (execution modules).

Все вышеперечисленные API-методы построены по единому принципу, поэтому ниже приведено общее описание, применимое ко всей группе GET /v1/app/settings/salt/schedules/{scheduleType}.

Параметр пути

Имя Описание Обязательный Тип Пример

scheduleType

Тип операции. Возможные значения: highstate, grains, grains_sync, refresh_pillar, agent_installation, software_inventory_sync, software_inventory_full_sync

Да

string

highstate

Ответы

Код Сообщение Тип данных / объект схемы (DTO) Пример

200

Текущие настройки расписаний для SaltStack

SaltScheduleSettingsResponse

 
{
  "seconds": 3600,
  "hours": 24,
  "minutes": 60,
  "days": 14,
  "range": "{}",
  "splay": 10
}

401

Ошибка аутентификации

500

Внутренняя ошибка

BasicError

 
{
  "code": "internal_error",
  "message": "DB property with name salt.schedule.highstate.seconds required, but not found"
}

Группа методов updateSaltScheduleSettings

Изменение настроек расписания синхронизации агентов (minions) с сервером управления (master) в SaltStack.

В зависимости от типа операции вы можете отдельно изменить настройки (интервал времени и допустимую задержку выполнения операции) для каждой из них, используя следующие методы:

  • PUT /v1/app/settings/salt/schedules/highstate — применение назначенных конфигураций на устройствах;

  • PUT /v1/app/settings/salt/schedules/grains — инвентаризация устройств;

  • PUT /v1/app/settings/salt/schedules/grains_sync — синхронизация параметров Grains;

  • PUT /v1/app/settings/salt/schedules/refresh_pillar — синхронизация файлов Pillar;

  • PUT /v1/app/settings/salt/schedules/user_session_history — синхронизация данных о сессиях пользователей;

  • GET /v1/app/settings/salt/schedules/user_agent_installation — сбор данных об установке агента (minion);

  • GET /v1/app/settings/salt/schedules/software_inventory_sync — инвентаризация устройств с помощью модулей выполнения (execution modules), во время которой собираются только измененные данные;

  • GET /v1/app/settings/salt/schedules/software_inventory_full_sync — полная инвентаризация устройств с помощью модулей выполнения (execution modules).

Все вышеперечисленные API-методы построены по единому принципу, поэтому ниже приведено общее описание, применимое ко всей группе PUT /v1/app/settings/salt/schedules/{scheduleType}.

Параметр пути

Имя Описание Обязательный Тип Пример

scheduleType

Тип операции. Возможные значения: highstate, grains, grains_sync, refresh_pillar, agent_installation, software_inventory_sync, software_inventory_full_sync

Да

string

highstate

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

См. SaltUpdateScheduleSettingsRequest

Пример запроса

{
  "seconds": 3600,
  "hours": 24,
  "minutes": 60,
  "days": 14,
  "range": "{}",
  "splay": 10
}

Тип контента

application/json

Ответы

Код Сообщение Тип данных / объект схемы (DTO) Пример

204

Успешное применение настроек

400

Incorrect request params (некорректные параметры запроса)

BasicError

 
{
  "code": "validation_failed",
  "message": "One field of 'seconds', 'minutes', 'hours' or 'days' should be filled"
}

401

Ошибка аутентификации

500

Внутренняя ошибка

BasicError

 
{
  "code": "internal_error",
  "message": "DB property with name salt.schedule.highstate.seconds required, but not found"
}

Описание параметров схемы

BasicError

Описание ошибки.

Имя поля Обязательное Тип Описание Пример

code

Да

string

Код ошибки. Включает параметр ErrorCode. Допустимые значения:

  • object_already_exists — объект уже существует;

  • object_not_found — объект не найден;

  • validation_failed — ошибка валидации;

  • authorization_failed — ошибка авторизации;

  • internal_error — внутренняя ошибка

validation_failed

message

Да

String

Сообщение об ошибке

Template contains not resolved variables

ErrorCode

Код ошибки.

Тип: string.

Допустимые значения:

  • object_already_exists — объект уже существует;

  • object_not_found — объект не найден;

  • validation_failed — ошибка валидации;

  • authorization_failed — ошибка авторизации;

  • internal_error — внутренняя ошибка.

LastExecutionStatus

Статус последнего запуска задания на удаление данных.

Тип: string.

Допустимые значения:

  • ERROR — задание выполнено с ошибкой;

  • SUCCESS — задание успешно выполнено.

SaltScheduleSettingsResponse

Текущие настройки расписаний для SaltStack.

Имя поля Обязательное Тип Описание Пример

seconds

Нет

integer

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

3600

minutes

Нет

integer

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

60

hours

Нет

integer

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

24

days

Нет

integer

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

14

range

Нет

string

Временной интервал от 00:00 до 23:59, в рамках которого будет выполняться операция согласно расписанию. Включает параметры TimeRange:

  • start — начало временного интервала в формате HH:MM (24 часа). Шаблон: ^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]$;

  • end — окончание временного интервала в формате HH:MM (24 часа). Шаблон: ^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]$

  • 09:00

  • 18:00

splay

Нет

integer

Определяет верхнюю границу случайной задержки перед запланированным выполнением в секундах. Например, если splay=10, ко времени следующего выполнения операции будет добавлен случайный промежуток от 0 до 10 секунд. Минимальное значение: 0. Максимальное значение: 10

5

SaltUpdateScheduleSettingsRequest

Запрос на изменение настроек расписаний для SaltStack.

Имя поля Обязательное Тип Описание Пример

seconds

Нет

integer

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

3600

minutes

Нет

integer

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

60

hours

Нет

integer

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

24

days

Нет

integer

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

14

range

Нет

string

Временной интервал от 00:00 до 23:59, в рамках которого будет выполняться операция согласно расписанию. Включает параметры TimeRange:

  • start — начало временного интервала в формате HH:MM (24 часа). Шаблон: ^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]$;

  • end — окончание временного интервала в формате HH:MM (24 часа). Шаблон: ^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]$

  • 09:00

  • 18:00

splay

Нет

integer

Определяет верхнюю границу случайной задержки перед запланированным выполнением в секундах. Например, если splay=10, ко времени следующего выполнения операции будет добавлен случайный промежуток от 0 до 10 секунд. Минимальное значение: 0. Максимальное значение: 10

5

createdAt

Да

string

Дата и время создания параметра

2023-08-27T09:37:40.000Z

updatedAt

Да

string

Дата и время последнего обновления параметра

2023-08-27T09:37:40.000Z

updatedBy

Нет

string

Автор последнего изменения параметра

author

TimeRange

Временной интервал от 00:00 до 23:59.

Имя поля Обязательное Тип Описание Пример

start

Да

string

Начало временного интервала в формате HH:MM (24 часа). Шаблон: ^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]$

09:00

end

Да

string

Окончание временного интервала в формате HH:MM (24 часа). Шаблон: ^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]$

18:00

API модуля установки ОС

В разделе описаны методы API-интерфейса модуля установки ОС, предназначенные для выполнения операций по поддержке хода процесса установки ОС.

getBootLoaderConfigurationFile

Получение конфигурационного файла для программы-загрузчика для конкретного устройства. Функция предназначена для вызова с конечных устройств для получения цепочки загрузки.

GET /v1/boot_loaders/{bootloaderId}/config

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

Имя Описание Обязательный Тип Пример

bootloaderId

Уникальный внутренний идентификатор программы-загрузчика

Да

string

ipxe

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

Имя Описание Обязательный Тип Пример

mac

MAC-адрес устройства

Нет

string

00:1b:63:84:45:e6

templateSlug

Cистемное наименование шаблона

Нет

string

ipxe_initial

Ответы

Код Сообщение Тип данных / объект схемы (DTO) Пример

200

Сформированный конфигурационный файл для программы-загрузчика

404

Объект не найден

BasicError

 
{
  "code": "object_not_found",
  "message": "string"
}

422

Невозможно обработать запрос

BasicError

 
{
  "code": "object_not_found",
  "message": "string"
}

500

Внутренняя ошибка

BasicError

 
{
  "code": "internal_error",
  "message": "string"
}

getPostInstallScriptFile

Получение назначенного на устройство файла пост-установочного скрипта. Функция предназначена для вызова с конечных устройств.

GET /v1/provisioning_scripts

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

Имя Описание Обязательный Тип Пример

machineId

Уникальный внутренний идентификатор устройства

Да

string($uuid)

75e291ec-83fe-4fd4-bd2e-6d327801c71f

Ответы

Код Сообщение Тип данных / объект схемы (DTO) Пример

200

Файл пост-установочного скрипта

401

Ошибка аутентификации

404

Объект не найден

BasicError

 
{
  "code": "object_not_found",
  "message": "string"
}

500

Внутренняя ошибка

BasicError

 
{
  "code": "internal_error",
  "message": "string"
}

getUnattendedInstallFile

Получение назначенного на устройство файла автоответов, заполненного параметрами согласно шаблону, который определяется по MAC-адресу, передаваемому в запросе.

GET /v1/unattended_install_files

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

Имя Описание Обязательный Тип Пример

mac

MAC-адрес устройства

Да

string

00:1b:63:84:45:e6

Ответы

Код Сообщение Тип данных / объект схемы (DTO) Пример

200

Файл автоответов

401

Ошибка аутентификации

404

Объект не найден

BasicError

 
{
  "code": "object_not_found",
  "message": "string"
}

500

Внутренняя ошибка

BasicError

 
{
  "code": "internal_error",
  "message": "string"
}

updateInstallationProcessStatus

Фиксация состояния процесса установки ОС на новое устройство.

POST /v1/unprovisioned_machines/{unprovisionedMachineId}/installation_process/status

Параметр пути

Имя Описание Обязательный Тип Пример

unprovisionedMachineId

Уникальный внутренний идентификатор устройства

Да

string($uuid)

75e291ec-83fe-4fd4-bd2e-6d327801c71f

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

Имя Описание Обязательный Тип Пример

status

Статусы этапов установки ОС. Возможные значения:

  • PRESTART — подготовка к установке;

  • IN_PROCESS — в процессе установки;

  • INSTALL_ERROR — ошибка установки;

  • FINISHED — завершение установки

Да

string

IN_PROCESS

step

Название текущего шага установки ОС

Да

string

additionalInfo

Дополнительная информация, например при ошибке установки код ответа или описание причины

Нет

string

Description

Ответы

Код Сообщение Тип данных / объект схемы (DTO) Пример

204

Статус успешно изменен

404

Объект не найден

BasicError

 
{
  "code": "object_not_found",
  "message": "string"
}

422

Невозможно обработать запрос

BasicError

 
{
  "code": "invalid_entity",
  "message": "string"
}

500

Внутренняя ошибка

BasicError

 
{
  "code": "internal_error",
  "message": "string"
}

Описание параметров схемы

BasicError

Информация об ошибке.

Имя поля Обязательное Тип Описание Пример

code

Да

string

Код ошибки. Включает параметр ErrorCode. Допустимые значения:

  • object_already_exists — объект уже существует;

  • object_not_found — объект не найден;

  • validation_failed — ошибка валидации;

  • authorization_failed — ошибка авторизации;

  • internal_error — внутренняя ошибка

validation_failed

message

Да

string

Сообщение об ошибке

Template contains not resolved variables

ErrorCode

Код ошибки.

Тип: string.

Допустимые значения:

  • object_already_exists — объект уже существует;

  • object_not_found — объект не найден;

  • validation_failed — ошибка валидации;

  • authorization_failed — ошибка авторизации;

  • internal_error — внутренняя ошибка.