Служба управления конфигурациями "Осмакс"

Описание API

Версия 1.11.0

© Т1 Иннотех, 2020-

Содержание

    Содержание

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

    Продукт «Служба управления конфигурациями "Осмакс"» предоставляет 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 — внутренняя ошибка.