UTM5 Urfaclient

14    

Предупреждение#

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

Перед выполнением любого действия на системах, находящихся в коммерческой эксплуатации, с помощью пакета UTM5 Urfaclient необходимо проверить корректность действий на стендовой системе.

Пакет UTM5 Urfaclient предназначен для взаимодействия с ядром UTM5 на низком уровне и требует четкого понимания логики производимых действий.

Компания NetUP не несет ответственности за любые последствия, вызванные некорректным использованием пакета.

Введение#

Пакет предназначен для осуществления унифицированного доступа к структурам ядра UTM5 посредством RPC интерфейса (URFA).

Пакет UTM5 Urfaclient состоит из:

–модуля ядра биллинговой системы (библиотека liburfaclient.so), обеспечивающего взаимодействие утилиты utm5_urfaclient и ядра UTM5;

–утилиты utm5_urfaclient, предназначенной для выполнения требуемых действий;

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

–URFA-скриптов, специфичных для производимого действия или последовательности действий.

Вывод вызываемых URFA-функций пишется в стандартный поток вывода (stdout).

Для работы модуля необходимо наличие отдельной лицензии. Проверить наличие и срок действия лицензии можно в интерфейсе администратора UTM5 (см. Лицензии, пункт URFA Client).

Схема#

Схема api.xml содержит представленные в виде XML-тегов описания

–входных и выходных параметров функций;

–последовательности действий в зависимости от значения данных параметров.

Путь к файлу api.xml может быть указан в качестве параметра командной строки -api. По умолчанию: /netup/utm5/xml/api.xml.

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

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

Интерпретация значений переменных зависит от контекста. Например, в случае тега integer на этапе передачи значения из переменной происходит парсинг строк, на этапе приема значения в переменную происходит сериализация строк.

Необходимо внимательно относиться к выбору имен переменных, так как все переменные в данной реализации являются глобальными.

Встроенные функции системы:

–now() – возвращает строковое представление текущего времени в формате unix;

–max_time() – возвращает строковое представление максимального значения времени в системе UTM5 в формате unix (2000000000, ~2033 год);

–size(varname) – возвращает длину массива с именем var_name.

Допустимые теги#

–urfa

корневой тег. Не содержит атрибутов. Может содержать один или несколько тегов function.

–function

описывает функцию. Обязательные атрибуты:

–name – имя функции

–id – идентификатор функции.

Должен содержать теги input и output (по одному на описание функции). Порядок следования тегов input и output значения не имеет.

–input

содержит описание входных параметров функции. Не имеет атрибутов. Может содержать упорядоченную последовательность тегов:

–integer

–long

–double

–string

–ip_address

–if

–for

–error

–output

то же, что и input, только для выходных параметров функции.

–integer

может находиться внутри тега input или output; передает целое значение со знаком длиной 32 бита. Должен содержать свойство name – имя переменной-источника или получателя. Может содержать свойства:

–default – выражение для значения по умолчанию. Имеет значение только для входных параметров, в случае если не найдена переменная с именем, указанным в свойстве name. При отсутствии переменной и значения по умолчанию произойдет завершение программы с ненулевым кодом возврата.

–array_index – выражение для номера ячейки массива-источника или массива-получателя.

–long

аналогичен тегу integer, но содержит описание целых знаковых параметров длиной 64 бита (int64_t).

–double

аналогичен тегу integer, но содержит описание параметров с плавающей точкой (double).

–string

аналогичен тегу integer, но содержит описание строковых параметров.

–ip_address

аналогичен тегу integer, но содержит описание параметров типа IPv4-адреса (например 192.168.0.1 или 255.255.0.0). Внутренним представлением IPv4 адреса является целое число длиной 32 бит (тип int32_t).

–if

предназначен для обеспечения ветвления в последовательности параметров в зависимости от значения переменной. Должен иметь атрибуты:

–variable – имя проверяемой переменной,

–value – выражение для сравниваемого значения,

–condition – условие сравнения (eq – равно, ne – не равно).

Может содержать упорядоченную последовательность тегов:

–integer

–long

–double

–string

–ip_address

–if

–for

–error

Другие вложенные теги недопустимы.

–for

предназначен для обеспечения реализации циклов. Должен иметь атрибуты:

–name – имя переменной-счетчика

–from – выражение для начального значения счетчика

–count – выражение для числа итераций цикла

Может содержать упорядоченную последовательность тегов:

–integer

–long

–double

–string

–ip_address

–if

–for

–error

Другие вложенные теги недопустимы.

–error

вызывает выход из программы с ненулевым кодом возврата, если не указано обратное. Может иметь атрибуты:

–icode – код возврата программы

–comment – описание ошибки

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

URFA-скрипт#

URFA-скрипт описывает последовательность действий: вызова URFA-функций, циклов и условных операторов, представленную в виде XML-тегов. На каждое действие присутствует по одному файлу с именем <имя_действия.хml>.

Имя директории, в которой находятся URFA-скрипты, может быть указано в качестве параметра командной строки -x. По умолчанию имя директории – /netup/utm5/xml/. Например, для действия add_user по умолчанию будет использоваться файл /netup/utm5/xml/add_user.xml.

URFA-скрипт должен соответствовать требованиям схемы.

Допустимые теги#

–urfa

корневой тег. Должен содержать упорядоченную последовательность тегов:

–call

–parameter

–add

–sub

–mul

–div

–cat

–if

–for

–message

–out

–set

–error

–remove

–call

осуществляет вызов URFA-функции, определенной в api-файле.
Должен иметь атрибут function – имя вызываемой функции.
Может иметь атрибут output, при нулевом значении которого не происходит вывода результата работы функции в виде xml-документа.
Может содержать теги parameter.
Другие вложенные теги недопустимы.

–parameter

должен содержать свойство name – имя переменной.
Может определять начальные значения переменных, если имеет атрибут value, в противном случае определяет допустимый параметр командной строки.
Если значение переменной указано как в файле действия в атрибуте value, так и в командной строке, то приоритетной является командная строка. Все присутствующие в командной строке значения данного параметра, либо его значение по умолчанию, помещаются в список переменных как массив с именем, определенным свойством name.

Также может иметь атрибут comment – описание переменной и соответствующего ключа командной строки, выводимое при одновременном указании ключей командной строки -a [имя_действия] и -help.

–add

тег арифметического действия (сложения). Должен иметь атрибуты:

–arg1 – первое слагаемое,

–arg2 – второе слагаемое,

–dst – имя переменной для записи результата.

–sub

тег арифметического действия (вычитания). Должен иметь атрибуты:

–arg1 – уменьшаемое,

–arg2 – вычитаемое,

–dst – имя переменной для записи результата.

–mul

тег арифметического действия (умножения). Должен иметь атрибуты:

–arg1 – первый множитель,

–arg2 – второй множитель,

–dst – имя переменной для записи результата.

–div

тег арифметического действия (деления). Должен иметь атрибуты:

–arg1 – делимое,

–arg2 – делитель,

–dst – имя переменной для записи результата.

–cat

тег операции конкатенации строк. Должен иметь атрибуты:

–arg1 – первая строка,

–arg2 – вторая строка,

–dst – имя переменной для записи результата.

–if

предназначен для обеспечения ветвления в последовательности параметров в зависимости от значения переменной. Должен иметь атрибуты:

–variable – имя проверяемой переменной,

–value – выражение для сравниваемого значения,

–condition – условие сравнения (eq – равно, ne – не равно).

Может содержать упорядоченную последовательность тегов:

–call

–parameter

–add

–sub

–mul

–div

–cat

–if

–for

–message

–out

–set

–error

–break

–remove

Другие вложенные теги недопустимы.

–for

предназначен для обеспечения реализации циклов. Должен иметь атрибуты:

–name – имя переменной-счетчика

–from – выражение для начального значения счетчика

–count – выражение для числа итераций цикла

Может содержать упорядоченную последовательность тегов:

–call

–parameter

–add

–sub

–mul

–div

–cat

–if

–for

–message

–out

–set

–error

–break

–remove

Другие вложенные теги недопустимы.

–message

должен иметь атрибут text. Данный тег осуществляет вывод в поток STDOUT отладочных сообщений, определенных в атрибуте text.

–out

должен иметь атрибут var. Выводит в поток STDOUT значение переменной, заданной атрибутом var, в виде массива.

–set

определяет значения переменных. Должен иметь атрибут dst и один из атрибутов: src или value. Одновременное указание атрибутов src и value недопустимо.

Может также иметь атрибуты:

–dst_index – выражение для номера ячейки массива-приемника (0, если атрибут не указан);

–src_index – выражение для номера ячейки массива-источника (0, если атрибут не указан).

–dst определяет имя переменной-приемника (если переменная-приемник не существует, она будет создана),

–src определяет имя переменной-источника,

–value определяет выражение для присвоения переменной.

В текущей реализации допускается присвоение нового элемента массива либо в существующую ячейку, либо в ячейку с индексом, равным текущему размеру массива. Индекс первого элемента массива – 0. Выход за границы массива-источника также недопустим и приводит к аварийному завершению программы.

–error

вызывает выход из программы с ненулевым кодом возврата, если не указано обратное. Может иметь атрибуты:

–code – код возврата программы

–comment – описание ошибки

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

–shift

предполагает сдвиг значений массива, указанного в свойстве name, на одну позицию влево с удалением первого элемента. Данный тег предназначен для внутреннего использования, и его применение не рекомендуется.

–break

осуществляет выход из первого по вложенности тега for с продолжением выполнения скрипта со следующей за циклом строки.

–remove

удаляет элемент массива либо весь массив, имя которого должно присутствовать в свойстве name. Индекс элемента массива может быть указан в виде выражения в свойстве array_index, в противном случае удаляется весь массив. При удалении элемента массива последующие элементы смещаются на одну позицию влево.

Файл данных#

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

Допустимые теги#

–urfa

корневой тег. Должен содержать один или несколько тегов array.

–array

массив произвольной размерности.
Должен иметь атрибуты:

–name – имя переменной;

–dimension – размерность массива.

Также может иметь атрибут comment – произвольный комментарий.
Должен содержать упорядоченную последовательность тегов dim.
Другие вложенные теги недопустимы.

–dim

элемент массива, который может сам по себе быть массивом.
Может иметь атрибут comment – произвольный комментарий.
Содержимое тега должно представлять собой либо значение элемента массива, либо упорядоченную последовательность тегов dim.
Другие вложенные теги недопустимы.

Утилита utm5_urfaclient#

Вызов утилиты осуществляется из командной строки с указанием параметров.

Запуск UTM5 Urfaclient производится командой

Параметры командной строки начинаются со знака “ - ”, затем следует название ключа и через пробел значение параметра (исключение составляет ключи -help, -debug, -u и -dealer, не требующие значения).

Большинство ключей имеют соответствия среди параметров конфигурационного файла. Общий список всех ключей и параметров приведён ниже.

Допускается указание параметров, специфичных для определенного действия. В зависимости от действия некоторые специфичные параметры могут являться обязательными.

Все строковые значения должны передаваться в кодировке UTF-8.

Порядок указания параметров не имеет значения.

Конфигурационный файл#

По умолчанию UTM5 Urfaclient использует конфигурационный файл /netup/utm5/utm5_urfaclient.cfg.

Формат конфигурационного файла:

Набор символов до знака равенства является названием параметра, после – значением параметра. Пробелы учитываются. Пустые строки игнорируются. Строка, начинающаяся с символа #, считается комментарием.

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

Список возможных параметров и ключей командной строки:

Примеры работы#

Примеры URFA-скриптов находятся в директории /netup/utm5/xml. Там же находятся схема (api.xml) и примеры файлов данных – search_users_new_data.xml и teldata.xml.

Пример запуска утилиты:

В данном примере выполняется скрипт link_tariff_with_services.xml, содержащий пример подключения к лицевому счету пользователя тарифного плана с подключением всех услуг, входящих в состав этого тарифного плана с отмеченным флагом Подключать услугу по умолчанию.

По результатам работы утилита пишет данные в стандартный поток вывода.