Документация разработчика

Общая информация

Внутренние переменные скрипта

_script_name - переменная, содержащая название текущего скрипта
_script_uuid - переменная, содержащая uuid (уникальный идентификатор) текущего скрипта
store - таблица для хранения временных данных, уникальная для каждого скрипта. Ее можно использовать просто как переменную:

store.value = 5
print(store.value) -- 5

main_store - таблица, в которой находятся хранилища всех запущенных с момента запуска системы скриптов.
Первый уровень таблицы — UUID скриптов. Второй уровень — store каждого скрипта. UUID скрипта можно узнать, нажав на значок "i" в интерфейсе. С помощью этой таблицы можно получать доступ к хранилищам других скриптов:

store.table = {1,2,3,4,5}
print(main_store["8d72fe2f-801e-48d1-ac1a-526f3e2622c0"].table) -- { 1, 2, 3, 4, 5 }

Например, это позволяет передавать между скриптами функции или таблицы, которые нельзя напрямую передать через BUS.

Функции для работы с логами

Функции log_info(), log_warning(), log_error(), log_user()

Добавляют в системный лог запись уровня "INFO", "WARNING", "ERROR" и "USER" соответственно.
Использование: log_info("Found correlation!"), log_warning("Found correlation!") , log_error("Found correlation!") , log_user("Found correlation!") Ничего не возвращает.

Функции log() и print()

log() - алиас для функции log_user()
print() - алиас для функции log_user()

Функции для работы с центральной шиной

Функция set_value()

Обновляет топик "topic", устанавливая значение "value".
Использование: set_value(topic, value, check_flag, update_time)
Ничего не возвращает.

Параметр check_flag определяет, будет ли проверяться перед изменением значение изменяемого топика.
Если параметр check_flag равен "CHECK_VALUE", то функция проверит равенство передаваемого в нее значение и старого значения в топике, и если они равны — не будет обновлять топик(т.е. не будут запущены событийные скрипты, и не будет обновлено время обновления топика). Если параметр равен чему-то другому (или не передается вообще, т.е. равен nil), то проверки производиться не будет, и значение топика будет обновлено в любом случае.
Это поведение используется для случаев, когда функции могут вернуть значение, равное значению топика, и логика работы такова, что при этом нет необходимости активировать событийные скрипты.

Параметр update_time переопределяет время обновления топика. Если update_time не указано, используется текущее системное время. Формат update_time — unix-time в секундах текущего часового пояса, допускаются десятые, сотые и тысячные доли.
Это поведение используется, например, если в драйвере запрашиваются исторические данные через API и необходимо, чтобы в выгрузку в TSDB они ушли с временем из истории, а не с текущим. Тогда в BUS загружаются исторические данные, используя параметр update_time, и они с этим временем выгружаются в TSDB.
Обратите внимание, что поле Update time в bus storage в этом случае не будет соответствовать реальности — несмотря на то, что топик был обновлен только что, время обновления в интерфейсе будет равно переданному в set_value параметру update_time.

Примеры использования:

set_value("/test/device", "5")
set_value("/test/device", "5", nil, os.time()-60*60)
set_value("/test/device", "5", "CHECK_VALUE", os.time()-60*60*2)

Функция shadow_set_value()

Обновляет топик, устанавливая значение "value", но не запускает event-скрипты, которые подписаны на этот топик.
Использование: shadow_set_value(topic, value)
Ничего не возвращает.

Данные, поступающие из драйверов или скриптов, могут обновлять значение топика в стандартном (standard) или теневом (shadow) режиме. В первом случае, отработают все скрипты, которые подписаны на изменения значения топика, во втором случае, значение будет изменено без запуска скриптов. При обновлении самим скриптом топика, на который он подписан, коллбек в скрипте вызываться не будет.

Функция get_value()

Получает значение и метаинформацию топика.
Использование: local value, update_time, type, tags = get_value(topic)
Возвращает поля value, update_time, type, tags

Функция bus_serialize()

Получает содержимое центральной шины (bus) в виде вложенной таблицы.
Использование: local table = bus_serialize(pattern)
Возвращает таблицу. Если передана переменная "pattern", то будет выбрана только часть таблицы, соответствующая заданному шаблону. Шаблоны соответствуют правилам lua patterns

Вспомогательные функции

Функция round()

Функция для "правильного" математического округления с произвольной точностью.
Получает число и количество знаков после запятой, возвращает округленное число. Если количество знаков не указано, используется 2.
Использование: local round_value = round(value, rounds)

Примеры использования:

local value = 3.1415926535
print(round(value)) --> 3.14
print(round(value, 2)) --> 3.14
print(round(value, 3)) --> 3.142

Функция deepcopy()

Функция для копирования таблиц lua(если попытаться скопировать таблицу table_a = table_b, мы получим две ссылки на одну и ту же таблицу).
Получает таблицу, возвращает копию таблицу. Таблица не должна быть рекурсивной, иначе функция переполнит стек.
Использование: local copy_table = deepcopy(table)

Пример использования:

local old_table = {1, 2, 4}
local copy_table = deepcopy(old_table)

Встроенные библиотеки

Для использования этих библиотек не нужно делать require, они уже есть в области видимости каждого скрипта.

Библиотека HTTP Client

Библиотека, реализующая примитивы для http-запросов.
Уже созданный экземпляр доступен через объект http_client, т.е. для метода request() нужно вызвать http_client.request()
Пример использования:

local r = http_client:get('http://google.com')
print(r.body)

Документация

Библиотека MQTT

Библиотека, реализующая клиента протокола MQTT. Доступна через объект mqtt
Пример использования:

local mqtt_object = mqtt.new("client_id", true)
mqtt_object:connect({ host='127.0.0.1', port=1883 })
ok, err = mqtt_object:subscribe('my/topic/#', 1)
ok, err = mqtt_object:publish('my/topic/#', 'Some payload as string', mqtt.QOS_0, mqtt.RETAIN)

Документация

Библиотека JSON

Библиотека, конвертирующая таблицы lua в json и обратно. Доступна через объект json
Пример использования:

json.encode({abc = 234, cde = 345}) --> '{"cde":345,"abc":234}'
json.decode('[123, "hello"]') --> [123, 'hello']

Документация

Библиотека Socket

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

local sock_1 = socket('AF_INET', 'SOCK_DGRAM', 'udp')
local sock_2 = socket('AF_INET', 'SOCK_DGRAM', 'udp')
sock_1:bind('127.0.0.1')
sock_2:sendto('127.0.0.1', sock_1:name().port,'X')
message = sock_1:recvfrom()
print(message) --> X

Документация

Библиотека Fiber

Библиотека для работы с потоками. Доступна через объект fiber
Не стоит подключать библиотеку fiber вручную, т.е. делать "local fiber = require 'fiber'".
В этом случае, ошибки внутри тредов fiber не попадут в лог конкретного скрипта и не сгенерируют ошибку, что усложняет отладку.
В библиотеке доступны методы fiber.sleep(), fiber.create(), fiber.kill(), fiber.yield(), fiber.self(), fiber.status(). Для остальных нужно делать require и оборачивать функции, которые запускаются через fiber.create() в pcall()/xpcall().
Пример использования:

local function loop()
   while true do
      print("tick")
      fiber.sleep(1.2) --seconds
   end
end
fiber.create(loop)

Документация

Скрипты и драйвера

Drivers

Драйвера — это скрипты на Lua, которые реализуют тот или иной протокол(часто с привлечением сторонних библиотек) для связи с устройством, конвертируя данные приходящие с каждого устройства в единый формат. Они работают в качестве транслятора между "языком" устройства и общей шиной.

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

Bus-event scripts

Этот тип скриптов выполняется для каждого устройства из группы устройств, определяемых маской, при обновлении их данных на центральной шине.
Bus-event scripts

В теле скрипта должна присутствовать функция event_handler(), в которую будет передано значение измененного топика и его адрес:

function event_handler(value, topic)
   print(value, topic) --> "5 /test/device"
end

Также, в теле скрипта, можно создать функции init() и destroy(), которые будут вызваны при инициализации скрипта и его выгрузке соответственно.
Это может быть полезно, например, если нужно сделать экспорт множества топиков по маске в MQTT.

У Bus-event скриптов существует возможность однократного запуска нажатием кнопки "Run Once" на странице редактиования скрипта или на странице со списком скриптов.
При однократном запуске, принудительно запускается event_handler() c аргументами value=0, topic="once". Не выполняются init() и destroy(). Однократный запуск полезен для отладки и совершения разовых действий.

Примеры bus-event скриптов

Web-event scripts

Скрипты, выполняемые при обращении к выбранному URL ("endpoint") с помощью HTTP запроса.

Web-event scripts

Функция, реализующая непосредственную логику при обработке запроса — http_callback().

При создании web-event скрипта, необходимо дать ему название и указать endpoint.
Полный адрес скрипта формируется как адрес_сервера:порт + /we/ + endpoint и отображается в нижней части модального окна как "Full script URL".

Создание web-event скрипта

В скриптах доступны переменные, содержащие данные запроса:

function http_callback(params, req)
   return {data=params}
end

Если в функции http_callback() вернуть одно значение-таблицу (напр. return table), то она будет сериализована в JSON и в таком виде отдана клиенту http-сервера.
Если необходимо управлять возвращаемыми данными напрямую, то надо вернуть 2 значения (напр. return nil, 'OK'), тогда первое значение будет отброшено, а второе - выдано клиенту в "сыром" виде без сериализации. Для дополнительных сведений смотрите документацию HTTP сервера Tarantool

Примеры web-event скриптов

Timer-event scripts

Скрипты, выполняемые с определенным интервалом (указывается в секундах).

Timer-event script

Для создания скрипта, укажите его название и желаемый интервал его выполнения в секундах.

Код скрипта должен находиться внутри функции event_handler().

function event_handler()
   print("Timer event start")
end

Примеры timer-event скриптов

Schedule scripts

Скрипты, выполняемые по заданному расписанию.

Schedule script

Для создания скрипта, укажите его название и расписание в формате crontab.
Формат отличается от стандартного необходимостью указания секунд в интервале (первый символ). Если вам не нужны секунды, укажите в первом символе "0". Не указываете там "*", иначе скрипт будет запускаться каждую секунду в подходящих интервалах.

┌───────────── секунды (0 - 59)
│ ┌───────────── минуты (0 - 59)
│ │ ┌───────────── часы (0 - 23)
│ │ │ ┌───────────── дни месяца (1 - 31)
│ │ │ │ ┌───────────── месяца (JAN-DEC или 1 - 12)
│ │ │ │ │ ┌───────────── день недели (SUN-SAT или 0 - 6) (с воскресения до субботы)
│ │ │ │ │ │
│ │ │ │ │ │
* * * * * *

К примеру, с такими настройками расписания, скрипт будет запускаться по четвергам в 13:45:15

 15 45 13 * * 4

Код скрипта должен находиться внутри функции event_handler().

function event_handler()
   print("Shedule event start")
end

Примеры shedule-event скриптов

Last Updated: 9/25/2018, 3:32:06 PM