10. Calculate API¶

Calculate API
Введение
Состав 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). Большинство методов являются удобными обёртками для данного метода. Имеет три входных параметра:

type - тип передаваемого сообщения;
message - текст передаваемое сообщение;
id - автоматически генерируемый идентификатор объекта (номер таблицы, прогресса задания и др.);

printDefault - вывод сообщения без отметок
printPre - вывод блока неформатируемого текста
printSUCCESS - обычное сообщение, имеет один параметр message(строку сообщения);
printWARNING - сообщение с предупреждением, имеет один параметр message(строку сообщения);
printERROR - сообщение об ошибке, имеет один параметр message(строку сообщения). Прерывает текущую задачу;
startTask - начало новой задачи, имеет три параметра:

message - название задачи;
progress - наличие контроля прогресса выполнения задачи (отображение прогрессбара клиентами);
num - количество частей для контроля прогресса. Используется только при progress равном True и определяет, сколько частей от общего прогресса выполнения займёт данная задача. Этот параметр не обязателен, актуален для клиента, работающего в упрощённом режиме вывода с одним прогрессом для всех задач текущего процесса.

setTaskNumber - установка числа частей для задач. Вызывается перед первым вызовом метода startTask. Если в вызовах startTask не указывается количество частей (параметр num), то в вызове setTaskNumber нет необходимости. Имеет один целочисленный параметр - число частей для задач, которое должно быть равно сумме всех значений параметра num, указанных в методах startTask;
endTask - сообщение о завершении текущей задачи. Имеет два параметра:

result - сообщение о завершении задачи;
progress_message - сообщение, используемое при выводе прогресса;

endFrame - сообщение пользователю о завершении работы процесса;
addProgress - добавление прогресса для задания;
setProgress - установить процент выполнения для текущего прогресса. Имеет три входных параметра:

perc - процент выполнения текущей задачи;
short_message - короткое сообщение для текущего процента выполнения;
long_message - длинное сообщение для текущего процента выполнения;

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

table_name - отображаемое название таблицы;
head - заголовок таблицы;
body - тело таблицы;
onClick - название метода, вызываемого при нажатии на строку таблицы. При этом будут переданы параметры из этой строки, описанные в поле fields (см. далее);
fields - список полей, необходимых для передачи в вызываемый метод, имя которого хранится в параметре onClick. Список fields равен по длине заголовку таблицы, неиспользуемые для передачи поля равны пустым строкам. Например, при fields = ['cl_group_name', '', ''] в вызываемый метод передастся параметр cl_group_name, значение для которого будет взято из первого столбца выбранной строки;
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:

sid - идентификатор (номер) сессии;

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:

sid - идентификатор (номер) сессии;

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

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

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

Install - основной класс установки и настройки системы.

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

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

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

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

sid - идентификатор (номер) сессии;

info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки системы.

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

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

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

sid - идентификатор (номер) сессии;

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:

sid - идентификатор (номер) сессии;

info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки системы.

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

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

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

sid - идентификатор (номер) сессии;

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:

sid - идентификатор (номер) сессии;

info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки и настройки системы.

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

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

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

sid - идентификатор (номер) сессии;

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

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

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

Install - основной класс установки и настройки системы.

Загрузка

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

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

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

sid - идентификатор (номер) сессии;

info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки и настройки системы.

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

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

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

sid - идентификатор (номер) сессии;

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

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

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

Install - основной класс установки и настройки системы.

Сеть

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

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

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

sid - идентификатор (номер) сессии;

info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки и настройки системы.

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

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

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

sid - идентификатор (номер) сессии;

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

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

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

Install - основной класс установки и настройки системы.

Видео

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

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

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

sid - идентификатор (номер) сессии;

info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки и настройки системы.

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

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

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

sid - идентификатор (номер) сессии;

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

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

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

Install - основной класс установки и настройки системы.

Система

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

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

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

sid - идентификатор (номер) сессии;

info - объект типа InstallInfo, хранящий в себе все параметры, необходимые для установки и настройки системы.

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

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

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

sid - идентификатор (номер) сессии;

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

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

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

Install - основной класс установки и настройки системы.

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

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

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

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

sid - идентификатор (номер) сессии;

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

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

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

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

sid - идентификатор (номер) сессии;

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:

sid - идентификатор (номер) сессии;

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

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

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

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

sid - идентификатор (номер) сессии;

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

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

show_request_meth - метод, формирующий таблицу запросов на сервере утилит;

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

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

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

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

sid - идентификатор (номер) сессии;

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

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

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

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

sid - идентификатор (номер) сессии;

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

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

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

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

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

sid - идентификатор (номер) сессии;

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

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

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

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

sid - идентификатор (номер) сессии;

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

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

confirm_request_meth - метод, выполняющий подписание сертификата;

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

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

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

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

sid - идентификатор (номер) сессии;

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

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

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

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

sid - идентификатор (номер) сессии;

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

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

del_request_meth - метод, выполняющий удаления запроса;

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

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

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

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

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

sid - идентификатор (номер) сессии;

info - объект типа CertificateInfo, хранящий в себе номер сертификата.

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

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

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

sid - идентификатор (номер) сессии;

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

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

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

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

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

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

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

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

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

sid - идентификатор (номер) сессии;

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:

sid - идентификатор (номер) сессии;

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

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

show_groups_meth - метод, формирующий таблицу групп на сервере утилит;

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

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

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

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

sid - идентификатор (номер) сессии;

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:

sid - идентификатор (номер) сессии;

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

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

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

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

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

sid - идентификатор (номер) сессии;

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

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

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

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

sid - идентификатор (номер) сессии;

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 состоит из следующих полей:

type - тип сообщения ("error", "warning", "table", "startTask" и другие);
message - передаваемое сообщение;
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, если клиентом послан неверный идентификатор сессии.