10. Calculate API

Введение

Calculate API (Интерфейс прикладного программирования утилит Calculate) - набор готовых классов, функций, структур и констант утилит Calculate, предоставляемых для использования во внешних программных продуктах. Calculate API предоставляет инструменты взаимодействия различных клиентов (таких как cl-console и cl-console-gui) с сервером утилит cl-core. Подробнее см. API в Википедии.

Доступ к API осуществляется через протокол HTTPS, использующий криптографический протокол SSL, который зашифровывает все передаваемые данные и этим защищает их от несанкционированного доступа. Установка SSL-соединения обязательна для вызова API методов.

В утилитах Calculate взаимодействие осуществляется по протоколу SOAP . Обмен данными по этому протоколу ведется посредством XML-сообщений.

Состав Calculate API

На стороне сервера утилит API реализовано с использованием библиотеки dev-python/soaplib .
Все модули и функции Calculate API можно разделить на две большие группы:
  • Основные - служат для вызова методов, непосредственно выполняющих выбранные пользователем действия (установка системы, настройка сети и др.);
  • Вспомогательные - служат для обеспечения взаимодействия клиента и сервера утилит (получение списка доступных методов, получение сессии, проверка прав сертификата и др.).

API реализовано с помощью rpc декораторов библиотеки soaplib, осуществляющих взаимодействие и проверку параметров (их число и типы данных).

Основные модули

Основные модули и методы Calculate API осуществляют основные действия сервера утилит. Простейшие из них представляют собой отдельный класс с именем CoreWsdl (для импортирования в сервер утилит). В этом классе находятся как минимум три метода (два из которых rpc методы), связанных между собой:
  • метод, запускающий процесс на выполнение;
  • метод, предоставляющий дополнительную информацию клиенту;
  • метод, выполняющий выбранное пользователем действие (представляет собой отдельный процесс).

Метод, запускающий процесс на выполнение

Рассмотрим на примере метода настройки пакетов в системе core_setup.
Имя метода, запускающего процесс на выполнение, является именем, по которому клиент вызывает данный метод (запускает процесс), в нашем случае это core_setup. Основные функции методов, запускающих процесс:
  • проверка поступающих от клиента параметров и сообщение об ошибках при необходимости;
  • создание глобального словаря параметров процесса для хранения всей информации о процессе;
  • запуск процесса на выполнение.

Каждый такой метод оборачивается двумя обязательными декораторами (подробнее о декораторах на ru.wikipedia.org ): rpc и core_method.

Декоратор rpc

Декоратор rpc служит для указания типа входных и возвращаемых данных. В декораторе метода core_setup два входных параметра - целочисленный (номер сессии) и типа CoreSetupInfo (объект, хранящий необходимые значения для запуска и выполнения процесса), и один возвращаемый параметр - массив элементов, каждый из которых имеет тип ReturnedMessage:

@rpc(Integer, CoreSetupInfo, _returns = Array(ReturnedMessage))

Возвращаемый тип ReturnedMessage

Для сообщения клиенту об успешном запуске процесса или об ошибках сервер утилит возвращает массив типовых сообщений типа ReturnedMessage. Каждое сообщение состоит из следующих полей:
  • type - тип сообщения. В случае успешного запуска процесса type рано строке "pid", в случае ошибки "error", при необходимости сообщить предупреждение - "warning"
  • message - передаваемое сообщение. В случае успешного запуска процесса значение message равно идентификатору процесса (pid), в остальных случаях message хранит строку с сообщением об ошибке или предупреждении;
  • field - поле с ошибкой или предупреждением. Значение равно имени параметра, в котором допущена ошибка или для которого необходимо сообщить предупреждение;
  • expert - устанавливается, если поле находится в дополнительных настройках.

Декоратор core_method

Декоратор core_method используется для указания дополнительной информации о методе для клиента и имеет шесть параметров:
  • category - указывает в какой категории будет находиться метод (для графических клиентов);
  • title - указывает отображаемое название метода, как правило является строкой для перевода;
  • image - указывает иконки для отображения (используется для графических клиентов. Иконки могут перечисляться через запятую и клиент использует первую найденную);
  • gui - определяет, используется ли данный метод для графических клиентов;
  • command - команда для создания символической ссылки на сервер утилит cl-core. Также указывает, используется ли данный метод для консольного клиента;
  • rights - указывает список прав, необходимых для возможности запуска данного метода. Для успешного запуска метода необходимы все указанные права.

Для метода core_setup:

@core_method(category=__('Configuration'), title=__('Configure package'),
             image='applications-other', gui=True, command='cl-core-setup',
             rights=['configure'])

Декораторы указываются непосредственно перед объявлением метода и выполняются один раз. В итоге метод core_setup имеет вид:

        ...
class CoreWsdl:
    @rpc(Integer, CoreSetupInfo, _returns = Array(ReturnedMessage))
    @core_method(category=__('Configuration'), title=__('Configure package'),
             image='applications-other', gui=True, command='cl-core-setup',
             rights=['configure'])
    def core_setup(self, sid, info):
        ...

Метод, предоставляющий дополнительную информацию

Рассмотрим на примере метода настройки пакетов в системе core_setup.
Для каждого метода, запускающего процесс на выполнение, должен быть метод, который сообщит клиенту информацию об используемых параметрах. Имя такого метода составляется из имени основного метода и окончания _view, например для метода core_setup имя метода, предоставляющего дополнительную информацию - core_setup_view.

Методы, предоставляющие дополнительную информацию клиентам, имеет один декоратор rpc, служащий для указания типа входных и возвращаемых данных. Для метода core_setup_view декоратор rpc имеет вид:

@rpc(Integer, ViewParams, _returns = ViewInfo)

Метод принимает два параметра: целое число (номер сессии) и обязательный параметр типа ViewParams, а также возвращает обязательный параметр типа ViewInfo, объект которого несёт в себе всю информацию о параметрах метода core-setup.

В результате метод core_setup_view имеет вид:

    @rpc(Integer, ViewParams,_returns = ViewInfo)
    def core_setup_view (self, sid, params):

Параметр ViewInfo

Класс ViewInfo и все ниже описанные классы (GroupField, Field) описаны в пакете calculate-core в файле core/server/api_types.py.
Параметр ViewInfo представляет собой массив объектов GroupField и булевый параметр has_brief, сообщающий клиенту о том, следует ли выводить информацию о значении всех параметров перед непосредственным запуском метода.

Каждый объект GroupField несёт информацию о группе параметров (например, настройка локализации в методе установки системы) и состоит из:
  • name - имя группы параметров для отображения;
  • last - булевое значение, указывает является ли данная группа последний (используется для методов с несколькими шагами);
  • nextlabel - строка, отображаемая на кнопке, осуществляющей переход на следующий шаг или запуск метода (по умолчанию "Далее" или "Ok", используется для графических клиентов);
  • prevlabel - строка, отображаемая на кнопке, осуществляющей переход на предыдущий шаг или выход из метода (по умолчанию "Назад" или "Отмена", используется для графических клиентов);
  • Массив объектов типа Field.

Тип параметра Field

Объект типа Field - описание отдельного параметра, состоящее из полей:
  • name - имя параметра;
  • label - отображаемое имя параметра;
  • element - тип элемента параметра (table, radio, combo, comboEdit, multichoice, input и др.), определяет основные характеристики и правила работы с параметром;
  • type - тип данных переменной;
  • help - дополнительная вспомогательная информация о параметре;
  • value - текущее значение переменной, поступившее от сервера утилит;
  • choice - список доступных для выбора значений (для элементов radio, combo, comboEdit, multichoice и др.);
  • comments - список комментариев, соответствующих каждому значению из choice, использующийся для отображения пользователю. Как правило, значения из comments имеют удобный для человека вид или перевод.
  • listvalue - список выбранных значений для элементов множественного выбора (multichoice, multichoice_add, selecttable, selecttable_add);
  • tablevalue - информация о таблице (только для элемента table), состоит из:
    • head - заголовок таблиц, определяет название столбцов и ширину таблицы;
    • body - тело таблицы, представляет собой данные таблицы, поступающие от сервера утилит;
    • values - описание типов данных для столбцов (доступные значения, комментарии, доступность на редактирование);
    • onChanged - зависимость значений столбца от ключевых значений (первого столбца);
  • uncompatible - булевое значение доступности параметра. Если uncompatible равно True, то данный параметр недоступен.
  • default - состояние параметра, находящегося в расширенных настройках. Определяет, будет ли отображено значение параметра в дополнительных настройках или оно будет пустым (авто).
  • opt - данные для работы из консоли. Состоит из:
    • help - описание параметра (отображается при вызове метода с ключом -h, --help);
    • metavalue - строка, определяющая требуемое значение параметра;
    • shortopt - короткий (односимвольный) ключ параметра (например, -h);
    • longopt - основной ключ параметра (например, --help).

Метод процесса

Метод, выполняющий выбранное пользователем действие и запускающийся в отдельном процессе, является обычным методом класса CoreWsdl. Для взаимодействия с клиентами (сообщений о прогрессе выполнения процесса, ошибках, успешном выполнении и др.) он использует ряд встроенных функций (методов), описанных в пакете calculate-core в файле core/server/func.py, таких как:
  • addMessage - основной метод добавления сообщения в стек сообщений для пользователя (сообщения имеют тип Message). Большинство методов являются удобными обёртками для данного метода. Имеет три входных параметра:
    1. type - тип передаваемого сообщения;
    2. message - текст передаваемое сообщение;
    3. id - автоматически генерируемый идентификатор объекта (номер таблицы, прогресса задания и др.);
  • printDefault - вывод сообщения без отметок
  • printPre - вывод блока неформатируемого текста
  • printSUCCESS - обычное сообщение, имеет один параметр message(строку сообщения);
  • printWARNING - сообщение с предупреждением, имеет один параметр message(строку сообщения);
  • printERROR - сообщение об ошибке, имеет один параметр message(строку сообщения). Прерывает текущую задачу;
  • startTask - начало новой задачи, имеет три параметра:
    1. message - название задачи;
    2. progress - наличие контроля прогресса выполнения задачи (отображение прогрессбара клиентами);
    3. num - количество частей для контроля прогресса. Используется только при progress равном True и определяет, сколько частей от общего прогресса выполнения займёт данная задача. Этот параметр не обязателен, актуален для клиента, работающего в упрощённом режиме вывода с одним прогрессом для всех задач текущего процесса.
  • setTaskNumber - установка числа частей для задач. Вызывается перед первым вызовом метода startTask. Если в вызовах startTask не указывается количество частей (параметр num), то в вызове setTaskNumber нет необходимости. Имеет один целочисленный параметр - число частей для задач, которое должно быть равно сумме всех значений параметра num, указанных в методах startTask;
  • endTask - сообщение о завершении текущей задачи. Имеет два параметра:
    1. result - сообщение о завершении задачи;
    2. progress_message - сообщение, используемое при выводе прогресса;
  • endFrame - сообщение пользователю о завершении работы процесса;
  • addProgress - добавление прогресса для задания;
  • setProgress - установить процент выполнения для текущего прогресса. Имеет три входных параметра:
    1. perc - процент выполнения текущей задачи;
    2. short_message - короткое сообщение для текущего процента выполнения;
    3. long_message - длинное сообщение для текущего процента выполнения;
  • getProgress - получение текущего прогресса (процента) выполнения задачи;
  • printTable - отображение таблицы. Имеет шесть параметров (три основных и три, использующихся при необходимости взаимодействия пользователя с таблицей в графических клиентах):
    1. table_name - отображаемое название таблицы;
    2. head - заголовок таблицы;
    3. body - тело таблицы;
    4. onClick - название метода, вызываемого при нажатии на строку таблицы. При этом будут переданы параметры из этой строки, описанные в поле fields (см. далее);
    5. fields - список полей, необходимых для передачи в вызываемый метод, имя которого хранится в параметре onClick. Список fields равен по длине заголовку таблицы, неиспользуемые для передачи поля равны пустым строкам. Например, при fields = ['cl_group_name', '', ''] в вызываемый метод передастся параметр cl_group_name, значение для которого будет взято из первого столбца выбранной строки;
    6. addAction - добавить кнопку добавления над таблицей (кнопка с иконкой "плюс"), при нажатии на которую будет вызван метод, имя которого указано в параметре addAction;
  • setStatus - установить статус процесса. 0 - процесс успешно завершён, 1 - процесс выполняется, 2 - процесс завершён с ошибкой;
  • getStatus - получить текущий статус процесса;
  • askQuestion - получить от пользователя дополнительные данные (задать вопрос пользователю). Имеет один параметр message - текст сообщения. Вызов этого метода возвратит введённое пользователем значение;
  • askPassword - получить пароль от пользователя. Имеет два параметра: message (текст сообщения) и twice (необходимость дублирования ввода пароля).
  • writeFile - записать текущее состояние процесса в файл (по умолчанию /var/calculate/server/pids/N.pid, где N - идентификатор процесса (pid)).
  • askChoice - получить от пользователя выбор из представленных вариантнов
  • askConfirm - получить от пользователя подтвержение
  • isInteractive - узнать интерактивно ли запущена действие в консоли (действие может из консоли может быть запущено с ключом -f)

Метод должен вернуть значение True при успешном завершении и значение False в случае ошибки.

Категория Установка

Для установки системы необходим установленный пакет calculate-install.

В категории Установка находятся три метода (при наличии необходимых прав у сертификата):
  • Установка системы (install);
  • Установка на Flash (install_flash);
  • Установка PXE (install_pxe).

Все методы установки системы работают через общий метод installCommon и описаны в файле install/cl_wsdl_install.py пакета calculate-install (/usr/lib/python2.7/site-packages/calculate/install/cl_wsdl_install.py).

Установка системы

Установка системы включает в себя:

  • install - rpc метод, проверяющий входные параметры и запускающий отдельный процесс установки системы;

Входные данные метода install:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки системы (класс InstallInfo объявлен в файле install/cl_wsdl_install.py пакета calculate-install (/usr/lib/python2.7/site-packages/calculate/install/cl_wsdl_install.py)).

Результирующие данные метода install - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • install_view - rpc метод, создающий объект ViewInfo с данными о параметрах установки и передающий его клиенту;

Входные данные метода install_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода install_view - объект типа ViewInfo, несущий информацию о всех параметрах установки, допустимых значениях и способах отображения элементов (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

  • install_vars - вспомогательный метод, формирующий структуру объекта ViewInfo;
  • Install - основной класс установки и настройки системы.

Установка системы на Flash

Установка системы на Flash включает в себя:

  • install_flash - rpc метод, проверяющий входные параметры и запускающий отдельный процесс установки системы на Flash носитель;

Входные данные метода install_flash аналогичны входным данным метода install:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки системы.

Результирующие данные метода install_flash - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • install_flash_view - rpc метод, создающий объект ViewInfo с данными о параметрах установки и передающий его клиенту;

Входные данные метода install_flash_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода install_flash_view - объект типа ViewInfo, несущий информацию о всех параметрах установки, допустимых значениях и способах отображения элементов.

  • install_flash_vars - вспомогательный метод, формирующий структуру объекта ViewInfo для методов install_flash и install_flash_view;
  • Install - основной класс установки и настройки системы.

Установка PXE

Установка PXE включает в себя:

  • install_pxe - rpc метод, проверяющий входные параметры и запускающий отдельный процесс установки системы с применением PXE (Установка PXE доступна только на Calculate Directory Server);

Входные данные метода install_pxe аналогичны входным данным метода install:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки системы.

Результирующие данные метода install_pxe - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • install_pxe_view - rpc метод, создающий объект ViewInfo с данными о параметрах установки и передающий его клиенту;

Входные данные метода install_pxe_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода install_pxe_view - объект типа ViewInfo, несущий информацию о всех параметрах установки, допустимых значениях и способах отображения элементов.

  • install_flash_vars - вспомогательный метод, формирующий структуру объекта ViewInfo для методов install_flash и install_flash_view;
  • Install - основной класс установки и настройки системы.

Категория Настройка

К категории Настройка относятся:
  • Локализация (setup_locale);
  • Загрузка (setup_boot);
  • Сеть (setup_network);
  • Видео (setup_video);
  • Настройка пакета (core_setup);
  • Система (setup_system).

Локализация

Настройка локализации, заключающаяся в настройки языка и часового пояса, включает в себя:

  • setup_locale - rpc метод, проверяющий входные параметры и запускающий отдельный процесс настройки локализации;

Входные данные метода setup_locale:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки и настройки системы.

Результирующие данные метода setup_locale - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • setup_locale_view - rpc метод, создающий объект ViewInfo с данными о параметрах настройки и передающий его клиенту;

Входные данные метода setup_locale_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода setup_locale_view - объект типа ViewInfo, несущий информацию о всех параметрах настройки локализации, допустимых значениях и способах отображения элементов (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

  • setup_locale_vars - вспомогательный метод, формирующий структуру объекта ViewInfo для настройки локализации;
  • Install - основной класс установки и настройки системы.

Загрузка

Настройка загрузки, заключающаяся в изменении конфигурации grub, включает в себя:

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

Входные данные метода setup_boot:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки и настройки системы.

Результирующие данные метода setup_boot - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • setup_boot_view - rpc метод, создающий объект ViewInfo с данными о параметрах настройки и передающий его клиенту;

Входные данные метода setup_boot_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода setup_boot_view - объект типа ViewInfo, несущий информацию о всех параметрах настройки загрузки, допустимых значениях и способах отображения элементов (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

  • setup_boot_vars - вспомогательный метод, формирующий структуру объекта ViewInfo для настройки загрузки;
  • Install - основной класс установки и настройки системы.

Сеть

Настройка сети заключается в выборе менеджера сети, настройке сетевых интерфейсов, указании имени хоста, сервера времени, сервера доменных имён, доменов для поиска и таблицы маршрутизации.
Настройка сети включает в себя:

  • setup_network - rpc метод, проверяющий входные параметры и запускающий отдельный процесс настройки сети;

Входные данные метода setup_network:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки и настройки системы.

Результирующие данные метода setup_network - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • setup_network_view - rpc метод, создающий объект ViewInfo с данными о параметрах настройки и передающий его клиенту;

Входные данные метода setup_network_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода setup_network_view - объект типа ViewInfo, несущий информацию о всех параметрах настройки сети, допустимых значениях и способах отображения элементов (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

  • setup_network_vars - вспомогательный метод, формирующий структуру объекта ViewInfo для настройки сети;
  • Install - основной класс установки и настройки системы.

Видео

Настройка видео заключается в выборе видео драйвера, разрешения экрана, разрешения фреймбуфера и установке композита.
Настройка видео включает в себя:

  • setup_video - rpc метод, проверяющий входные параметры и запускающий отдельный процесс настройки видео;

Входные данные метода setup_video:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки и настройки системы.

Результирующие данные метода setup_video - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • setup_video_view - rpc метод, создающий объект ViewInfo с данными о параметрах настройки и передающий его клиенту;

Входные данные метода setup_video_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода setup_video_view - объект типа ViewInfo, несущий информацию о всех параметрах настройки видео, допустимых значениях и способах отображения элементов (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

  • setup_video_vars - вспомогательный метод, формирующий структуру объекта ViewInfo для настройки видео;
  • Install - основной класс установки и настройки системы.

Система

Настройка системы заключается в наложении системных шаблонов (локальных, удалённых и шаблонов из overlay).
Настройка системы включает в себя:

  • setup_system - rpc метод, проверяющий входные параметры и запускающий отдельный процесс настройки системы;

Входные данные метода setup_system:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки и настройки системы.

Результирующие данные метода setup_system - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • setup_system_view - rpc метод, создающий объект ViewInfo с данными о параметрах настройки и передающий его клиенту;

Входные данные метода setup_system_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода setup_system_view - объект типа ViewInfo, несущий информацию о всех параметрах настройки системы, допустимых значениях и способах отображения элементов (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

  • setup_system_vars - вспомогательный метод, формирующий структуру объекта ViewInfo для настройки системы;
  • Install - основной класс установки и настройки системы.

Настройка пакета

Настройка пакета заключается в выборе пакета и наложении шаблонов для него.
Настройка пакета включает в себя:

  • core_setup - rpc метод, проверяющий входные параметры и запускающий отдельный процесс настройки пакета;

Входные данные метода setup_video:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа CoreSetupInfo, хранящий в себе все параметры, необходимые для настройки пакета (класс CoreSetupInfo объявлен в файле core/server/setup_package.py пакета calculate-core).

Результирующие данные метода setup_video - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • core_setup_view - rpc метод, создающий объект ViewInfo с данными о параметрах настройки и передающий его клиенту;

Входные данные метода setup_video_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода setup_video_view - объект типа ViewInfo, несущий информацию о всех параметрах настройки пакета, допустимых значениях и способах отображения элементов (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

  • core_setup_vars - вспомогательный метод, формирующий структуру объекта ViewInfo для настройки пакета;
  • updateSystemConfigs - основной класс настройки пакета.

Категория Утилиты

Категория Утилиты состоит из трёх групп методов:
  • Управление запросами (core_show_request, core_detail_request, core_confirm_request, core_del_request);
  • Просмотр сертификатов (core_view_cert);
  • Управление группами (core_show_groups, core_detail_group, core_add_group, core_change_group, core_del_group).

Управление запросами

Группа методов управления запросами состоит из методов просмотра, подробного просмотра, подтверждения (подписания) и удаления запросов.

Просмотр запросов выводит таблицу текущих запросов на сервере утилит, включает в себя:

  • core_show_request - rpc метод, проверяющий входные параметры и вызывающий вспомогательный метод requestCommon, который запускает процесс формирования таблицы запросов на сервере утилит;

Входные данные метода core_show_request:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа RequestInfo, хранящий в себе параметры выдаваемой таблицы запросов (количество строк и смещение). Класс RequestInfo объявлен в файле core/server/request.py пакета calculate-core.

Результирующие данные метода core_show_request - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • core_show_request_view - rpc метод, создающий объект ViewInfo с данными, необходимыми для формирования таблицы запросов, и передающий его клиенту;

Входные данные метода core_show_request_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода core_show_request_view - объект типа ViewInfo, несущий информацию о параметрах таблицы запросов (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

  • show_request_meth - метод, формирующий таблицу запросов на сервере утилит;
  • requestCommon - метод, выполняющий дополнительные проверки и запускающий процесс формирования таблицы запросов на сервере утилит.

Подробный просмотр запросов реализован для графических клиентов и осуществляет взаимодействие метода просмотра запросов с методами подтверждения и удаления запросов на сервере утилит, включает в себя:

  • core_detail_request - rpc метод, проверяющий входные параметры (номер запроса). Не вызывает никаких других методов (является заглушкой);

Входные данные метода core_detail_request:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа DetailRequestInfo, хранящий в себе параметры запроса (номер и имя группы для подписания сертификата). Класс DetailRequestInfo объявлен в файле core/server/request.py пакета calculate-core.

Результирующие данные метода core_detail_request - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • core_detail_request_view - rpc метод, создающий объект ViewInfo с данными запроса. Содержит данные о запросе и кнопки вызова других методов (просмотра, подписания и удаления запросов, с передачей необходимых параметров);

Входные данные метода core_detail_request_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода core_detail_request_view - объект типа ViewInfo, несущий информацию о всех параметрах запроса, допустимых значениях и способах отображения элементов, а так же кнопках перехода к другим методам и передачи им параметров (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Подтверждение (подписание) запросов осуществляет создание сертификата клиента, включает в себя:

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

Входные данные метода core_confirm_request:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа DetailRequestInfo, хранящий в себе номер запроса и имя группы для подписания сертификата.

Результирующие данные метода core_confirm_request - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • core_confirm_request_view - rpc метод, создающий объект ViewInfo с данными, необходимыми для формирования таблицы запросов, и передающий его клиенту;

Входные данные метода core_confirm_request_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода core_confirm_request_view - объект типа ViewInfo, несущий информацию о параметрах запроса (номер запроса и имя группы для подписания), допустимых значениях и способах отображения элементов (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

  • confirm_request_meth - метод, выполняющий подписание сертификата;
  • confirmRequestCommon - метод, выполняющий дополнительные проверки и запускающий процесс подписания сертификата (confirm_request_meth).

Удаление запроса включает в себя:

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

Входные данные метода core_del_request:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа DetailRequestInfo, хранящий в себе номер запроса для его удаления.

Результирующие данные метода core_del_request - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • core_del_request_view - rpc метод, создающий объект ViewInfo с данными, необходимыми для удаления запроса, и передающий его клиенту;

Входные данные метода core_del_request_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода core_del_request_view - объект типа ViewInfo, несущий информацию о параметрах запроса (номер запроса), допустимых значениях и способах отображения элементов (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

  • del_request_meth - метод, выполняющий удаления запроса;
  • delRequestCommon - метод, выполняющий дополнительные проверки и запускающий процесс удаления запроса (del_request_meth).

Просмотр сертификатов

Просмотр сертификатов заключается в просмотре данных по выбранному сертификату: доступных методов, группы прав, данных о подписчике и субъекте, серийного номера и отпечатка сертификата.
Просмотр сертификатов включает в себя:

  • core_view_cert - rpc метод, проверяющий входные параметры и вызывающий вспомогательный метод certificateCommon;

Входные данные метода core_view_cert:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа CertificateInfo, хранящий в себе номер сертификата.

Результирующие данные метода core_view_cert - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • core_view_cert_view - rpc метод, создающий объект ViewInfo с данными, необходимыми выбора сертификата для просмотра информации о нём, и передающий его клиенту;

Входные данные метода core_view_cert_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода core_view_cert_view - объект типа ViewInfo, несущий информацию о параметрах (номера сертификатов), допустимых значениях и способах отображения элементов (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

  • view_cert_meth - метод, выполняющий сбор информации о сертификате (доступных для выполнения методов, группы прав сертификата, данных о подписчике и субъекте, серийного номера и отпечатка сертификата);
  • certificateCommon - метод, выполняющий дополнительные проверки и запускающий процесс просмотра данных о сертификате (view_cert_meth).

Управление группами

Группа методов управления группами состоит из методов просмотра, подробного просмотра, добавления, изменения и удаления групп прав сертификатов.

Просмотр групп выводит таблицу текущих групп на сервере утилит, включает в себя:

  • core_show_groups - rpc метод, проверяющий входные параметры и вызывающий вспомогательный метод groupCommon, который запускает процесс формирования таблицы групп, существующих на сервере утилит;

Входные данные метода core_show_groups:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа GroupInfo, хранящий в себе параметры выдаваемой таблицы запросов (количество строк и смещение). Класс GroupInfo объявлен в файле core/server/edit_groups.py пакета calculate-core.

Результирующие данные метода core_show_groups - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • core_show_groups_view - rpc метод, создающий объект ViewInfo с данными, необходимыми для формирования таблицы групп, и передающий этот объект клиенту;

Входные данные метода core_show_groups_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода core_show_groups_view - объект типа ViewInfo, несущий информацию о параметрах таблицы групп (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

  • show_groups_meth - метод, формирующий таблицу групп на сервере утилит;
  • groupCommon - метод, выполняющий дополнительные проверки и запускающий процесс формирования таблицы групп на сервере утилит (запуск метода show_groups_meth).

Подробный просмотр группы реализован для графических клиентов и осуществляет взаимодействие метода просмотра групп с методами изменения и удаления групп на сервере утилит, включает в себя:

  • core_detail_group - rpc метод, проверяющий входные параметры (имя группы). Не вызывает никаких других методов (является заглушкой);

Входные данные метода core_detail_group:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа DetailGroupInfo, хранящий в себе параметры группы (имя группы и список прав). Класс DetailGroupInfo объявлен в файле core/server/edit_groups.py пакета calculate-core.

Результирующие данные метода core_detail_group - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • core_detail_group_view - rpc метод, создающий объект ViewInfo с данными группы. Содержит данные о группе и кнопки вызова других методов (просмотра, изменения и удаления группы, с передачей необходимых параметров);

Входные данные метода core_detail_group_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода core_detail_group_view - объект типа ViewInfo, несущий информацию о параметрах группы прав, допустимых значениях и способах отображения элементов, а так же кнопках перехода к другим методам и передачи им параметров (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Добавление группы создаёт новую группу прав на сервере утилит (для графического клиента - кнопка плюс "+" над таблицей групп). Включает в себя:

  • core_add_group - rpc метод, проверяющий входные параметры и вызывающий вспомогательный метод addGroupCommon;

Входные данные метода core_add_group:

  1. sid - идентификатор (номер) сессии;
  2. info - объект типа AddGroupInfo, хранящий в себе имя новой группы и список прав для неё.

Результирующие данные метода core_add_group - список объектов типа ReturnedMessage, несущих информацию о запуске процесса (идентификатор процесса pid) или сообщения с ошибками.

  • core_add_group_view - rpc метод, создающий объект ViewInfo с данными, необходимыми для добавления группы, и передающий его клиенту;

Входные данные метода core_add_group_view:

  1. sid - идентификатор (номер) сессии;
  2. params - объект типа ViewParams (описание типа ViewParams см. выше в разделе "Метод, предоставляющий дополнительную информацию").

Результирующие данные метода core_add_group_view - объект типа ViewInfo, несущий информацию о параметрах новой группы (имя и список прав), допустимых значениях и способах отображения элементов (описание типа ViewInfo см. выше в разделе "Метод, предоставляющий дополнительную информацию").

  • add_group_meth - метод, выполняющий добавление новой группы;
  • addGroupCommon - метод, выполняющий дополнительные проверки и запускающий процесс добавления группы (add_group_meth).

Вспомогательные модули

Вспомогательные модули служат для обеспечения взаимодействия клиента и сервера утилит. По выполняемым функциям методы этих модулей можно разделить на пять типов:
  • работа с сертификатами, запросами и списками отзывов сертификатов;
  • работа с сессиями;
  • работа с процессами;
  • работа с кэшем сессий, методов и процессов;
  • прочие методы.

Методы работы с сертификатами

К вспомогательным методам работы с сертификатами относятся:
  • post_client_request - отправить клиентский запрос на подпись сертификата. Вызов этого метода передаёт на сервер утилит от клиента запрос на подпись сертификата.

Имеет четыре входных параметра:

  • request - запрос на подпись сертификата (в виде строки с содержимым запроса);
  • ip - IP-адрес (уникальный сетевой адрес узла в компьютерной сети);
  • mac - MAC-адрес (уникальный идентификатор, присваиваемый каждой единице оборудования компьютерных сетей);
  • client_type - тип клиента (console или gui).

Возвращает номер запроса или значение "-1" в случае ошибки.

  • post_server_request - отправить серверный запрос на подпись сертификата, Вызов этого метода передаёт на сервер утилит запрос на подпись сертификата от другого сервера утилит.

Имеет три входных параметра:

  • request - запрос на подпись сертификата (в виде строки с содержимым запроса);
  • ip - IP-адрес;
  • mac - MAC-адрес;

Возвращает номер запроса или значение "-1" в случае ошибки.

  • get_client_cert - забрать подписанный сертификат клиента с сервера утилит.

Имеет два входных параметра:

  • req_id - номер запроса (уникальный номер запроса на сервере утилит, выдаётся при вызове метода post_client_request).
  • request - запрос на подпись сертификата. Необходим для проверки с ранее сохранённым.

Возвращает значение "1", если запрос был отвергнут или не найден на сервере, значение "2", если сертификата не существует (запрос ещё не был подписан). В случае подписания возвращает список из двух сертификатов - сертификат клиента и корневой сертификат сервера.

  • get_server_cert - забрать подписанный сертификат сервера утилит.

Имеет аналогичные с методом get_client_cert входные и возвращаемые параметры (см. выше).

  • get_ca - получить корневой сертификат сервера утилит.

возвращает "1", если в сертификате сервера утилит нет поля "CN", значение "2", если не найден сертификат, которым подписан сертификат сервера, иначе возвращает сертификат, которым подписан сертификат сервера.

  • get_crl - получить список отзыва сертификатов.

Возвращает содержимое списка отзывов сертификатов или значение " ".

  • post_cert - проверка сертификата на сервере. Вызывается при установке соединения для проверки наличия сертификата клиента на сервере и проверки сертификата на срок годности. Используется для графических клиентов, для консольных используется метод init_session.

Не имеет входных параметров. Возвращает список целочисленных значений: номер сертификата и значение годности сертификата (принимает значения: "-2" - срок годности истёк, "-1" - срок годности более 2-х месяцев или количество дней до истечении срока годности). Если у клиента нет сертификата возвращает значение [-3], если сертификат клиента не найден на сервере - значение [-4].

Методы работы с сессиями

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

  • post_sid - получение номера сессии с сервера утилит или продолжение незакрытой предыдущей сессии. Также вызов метода устанавливает текущий язык для локализации. Используется графическими клиентами.

Имеет три входных параметра:

  • sid - номер сессии, хранящийся у клиента. В случае, если сессия не была закрыта, она будет продолжена;
  • cert_id - номер сертификата;
  • lang - текущий язык клиента.

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

  • del_sid - закрытие (удаление) удаление сессии на сервере утилит.

Имеет единственный входной параметр sid - идентификатор (номер) сессии.

Возвращает значение ['0'] при успешном закрытии сессии.

  • get_sessions - получения списка текущих сессий на сервере утилит.

Имеет один входной параметр sid - номер своей сессии, необходимый для проверки соответствия сертификату.

Возвращает значение [''], если сессия не соответствует сертификату, иначе список всех активных сессий на сервере утилит.

  • sid_info - получить информацию по выбранной сессии.

Имеет один входной параметр sid - номер сессии.

Возвращает список значений: номер сертификата, дату подписания сертификата, ip-адрес, mac-адрес и тип клиента при указанные при генерации сертификата, а также значение, актив на ли сессия ('0' - активна, иначе - нет).

  • init_session - установка начального соединения консольного клиента. Выполняет проверку сертификата клиента и получает номер сессии (или продолжает незакрытую сессию). Аналогичен действиям методов post_sid и post_cert для графических клиентов.

Имеет два входных параметра:

  • sid - номер сессии, хранящийся у клиента. В случае, если сессия не была закрыта, она будет продолжена;
  • lang - текущий язык клиента.

Возвращает кортеж (список) из двух списков:

  • первый - список целочисленных значений: номер сертификата и значение годности сертификата (принимает значения: "-2" - срок годности истёк, "-1" - срок годности более 2-х месяцев или количество дней до истечении срока годности). Если у клиента нет сертификата возвращает значение [-3], если сертификат клиента не найден на сервере - значение [-4].
  • второй список из двух целочисленных значений: номера сессии и признака продолжения старой сессии (1 - новая сессия, 0 - старая сессия).

Методы работы с процессами

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

  • list_pid - получить список запущенных процессов (а так же завершивших работу, но принадлежащих данной сессии).

Имеет один входной параметр sid - номер текущей сессии.

Возвращает список номеров запущенных процессов или значение [0].

  • pid_info - информация по текущему процессу.

Имеет два входных параметра:

  • sid - номер текущей сессии;
  • pid - номер процесса, по которому необходимо просмотреть информацию.

Возвращает список значений: идентификатор (номер) процесса, статус процесса ('1' - активен, '0' - завершён, иначе прерван или завершён с ошибкой), время запуска процесса, имя процесса (запустившей его функции), имя rpc метода процесса.

pid_kill - завершить (прервать) выполняющийся процесс.

Имеет два параметра, аналогичных методу pid_info.

Возвращает значение -2, если сессия не соответствует сертификату, значение 3, если нет такого процесса на сервере утилит, значение 1, если не удалось послать процессу сигнал завершения и значение 0, если процессу послан сигнал завершения.

Для получения информации от выполняющихся процессов используются следующие методы: get_entire_frame, get_frame, get_progress, get_table и send_message. Методы get_entire_frame, get_frame и send_message возвращают данные типа Message (или массив таких данных).

Возвращаемый сервером утилит тип Message служит для сообщения клиенту информации о работе запущенного процесса. Добавление таких сообщений процессом описано ранее в разделе "Основные модули" -> "Метод процесса". Каждый объект типа Message состоит из следующих полей:
  1. type - тип сообщения ("error", "warning", "table", "startTask" и другие);
  2. message - передаваемое сообщение;
  3. id - уникальный номер (идентификатор), служащий для указания номера таблицы, номера значения прогресса или количества частей всех заданий и количество частей для каждого задания.
  • get_entire_frame - получить список всех сообщений процесса.

Имеет два входных параметра:

  • sid - номер сессии;
  • pid - номер выполняющегося процесса.

Возвращает массив объектов типа Message.

  • get_frame - получить список новых (неполученных ранее) сообщений процесса.

Входные и возвращаемые значения аналогичны параметрам метода get_entire_frame.

  • get_progress - получение значения прогресса для текущей задачи.

Имеет три входных параметра:

  • sid - номер сессии;
  • pid - номер процесса;
  • id - идентификатор прогресса задачи.

Возвращает объект типа ReturnProgress, состоящий из полей:

  • percent - целочисленное значение прогресса (процент);
  • short_message - короткое сообщение для текущего прогресса;
  • long_message - полное сообщение для текущего прогресса.

  • get_table - получить таблицу с сервера утилит.

Имеет аналогичные с методом get_progress параметры, где id - идентификатор таблицы для процесса.

Возвращает объект типа Table, включающий в себя поля:

  • head - шапка таблицы (список строк);
  • onClick - имя метода, вызываемого при нажатии на строку таблицы.
  • fields - имена полей (список строк), для передачи в вызываемый метод, имя которого указано в поле onClick. Номер поля в списке соответствует номеру столбца, из которого будет присвоено значение. Указывается только совместно с полем onClick;
  • body - тело таблицы (двумерный массив строк);
  • addAction - имя метода, отвечающего за добавление строки таблицы. Поле используется для графических клиентов, добавляет кнопку плюс "+" над таблицей, при нажатии на которую вызывается метод.
  • values - список объектов типа ChoiceValue, в методах printTable и get_table не используется (поле используется только в таблицах, передаваемых в составе объекта ViewInfo);

  • send_message - Отослать сообщение на сервер утилит. Посылает ответ на запросы процесса, осуществляемые вызовом методов askQuestion и askPassword.

Имеет три входных параметра:

  • sid - номер сессии;
  • pid - номер процесса;
  • text - текст ответа.

Возвращает объект типа Message

Методы работы с кэшем

Для работы с кэшем существует три метода, позволяющих на разных уровнях очищать текущие данные:

  • clear_session_cache - очищает кэш для всей сессии.

Имеет один параметр sid - номер сессии.

Возвращает 1 в случае ошибки и 0 при успешной очистке кэша сессии.

  • clear_method_cache - очищает кэш метода, принадлежащего данной сессии. Кэш метода создаётся до запуска процесса и хранит значение параметров, передаваемых от клиента серверу утилит.

Метод clear_method_cache имеет два входных параметра:

  • sid - номер сессии.
  • method_name - имя метода.

Возвращает 1 в случае ошибки и 0 при успешной очистке кэша метода.

  • clear_pid_cache - очищает кэш процесса. После завершения работы процесс хранит все данные о своей работе, чтобы пользователь мог просмотреть результаты.

Метод clear_pid_cache имеет два входных параметра:

  • sid - номер сессии;
  • pid - номер процесса.

Возвращает значение 1 в случае ошибки, значение 2 при отсутствии номера процесса в списке номеров процессов сессии и 0 при успешной очистке кэша процесса.

Прочие вспомогательные методы

К методам, не попавшим не в одну из предыдущих групп относятся:

  • get_methods - получение всех доступных (по правам сертификата) методов на сервере утилит.

Имеет два входных параметра:

  • sid - номер сессии;
  • client_type - тип клиента (gui или console).

Метод get_methods возвращает список данных о каждом методе, каждое из которых в свою очередь тоже являются списком из трёх элементов: название символической ссылки на метод (для запуска через cl-core), название rpc метода (для запуска с помощью клиентов) и отображаемое название метода.
Например:

[
 [cl-install, install, Установка системы],
 [cl-core-del-request, core_del_request, Удаление запроса],
 ...
]

  • get_server_host_name - получение имени хоста, на котором находится сервер утилит.

Не имеет входных параметров, возвращает имя хоста (hostname) сервера утилит, записанное в его сертификате.

  • active_client - метод используется для графических клиентов, позволяет определить наличие постоянного соединения с каждой из сторон, а так же был ли перезагружен сервер (при этом необходимо переустановить соединение).

Имеет один входной параметр sid - номер сессии.

Возвращает:

  • значение 0, если обновление информации о сессии прошло успешно.
  • значение 1 в случае ошибки;
  • значение 2, если клиентом послан неверный идентификатор сессии.

Спасибо!