Определяемые пользователем функции JavaScript в Azure Stream Analytics
Azure Stream Analytics поддерживает определяемые пользователем функции, написанные на языке JavaScript. Благодаря обширному набору методов, которые предоставляют объекты JavaScript String, RegExp, Math, Array и Date, в заданиях Stream Analytics стало проще создавать сложные преобразования данных.
Обзор
Определяемые пользователем функции JavaScript поддерживают скалярные вычислительные функции без отслеживания состояния, не требующие внешнего подключения. Возвращаемое значение функции может быть только скалярным (одиночным). Добавив в задание определяемую пользователем функцию JavaScript, вы сможете использовать ее в любом месте запроса, например во встроенной скалярной функции.
Ниже приведены некоторые сценарии, в которых могут пригодиться определяемые пользователем функции JavaScript.
- Анализ и обработка строки с использованием функций регулярных выражений, например Regexp_Replace() или Regexp_Extract() .
- Декодирование и кодирование данных, например преобразование двоичных данных в шестнадцатеричные.
- Математические вычисления с помощью математических функций JavaScript.
- Операции с массивами, такие как сортировка, присоединение, поиск и заполнение.
Вот некоторые действия, которые невозможно выполнить в Stream Analytics с помощью определяемой пользователем функции JavaScript.
- Вызов внешних конечных точек REST, например выполнение обратного разрешения IP-адресов или извлечение ссылочных данных из внешнего источника.
- Сериализация или десериализация входных и выходных данных в пользовательский формат сообщения.
- Создание пользовательских статистических функций.
Следует избегать использования таких функций, как Date.GetDate() или Math.random() , хотя они не запрещены в определении функции. Эти функции возвращают разные результаты при каждом вызове, а служба Azure Stream Analytics не ведет журнал вызовов и возвращаемых результатов для функций. Если функция возвращает разные результаты для одних и тех же событий, невозможно гарантировать повторяемость при перезапуске задания пользователем или службой Stream Analytics.
Добавление определяемой пользователем функции JavaScript в задание
Примечание
Эти действия подходят для заданий Stream Analytics, настроенных для работы в облаке. Если задание Stream Analytics настроено для работы в Azure IoT Edge, используйте вместо этого Visual Studio и напишите определяемую пользователем функцию, используя C#.
Чтобы создать определяемую пользователем функцию JavaScript в задании Stream Analytics, выберите Функции в разделе Топология задания. Затем выберите JavaScript UDF из раскрывающегося меню +Add (Добавить).
Затем необходимо указать следующие свойства и выбрать Сохранить.
| Свойство | Описание |
|---|---|
| Псевдоним функции | Введите имя для вызова функции в запросе. |
| Тип выходных данных | Тип, который будет возвращен определяемой пользователем функцией JavaScript в запрос Stream Analytics. |
| Определение функции | Реализация функции JavaScript, которая будет выполняться каждый раз при вызове определяемых пользователем функций из запроса. |
Тестирование и устранение неполадок с функциями UDF JavaScript
Вы можете тестировать и отлаживать логику UDF JavaScript в любом браузере. Отладка и тестирование логики этих определяемых пользователем функций сейчас не поддерживается на портале Stream Analytics. Когда функция заработает правильно, ее можно будет добавить в задание Stream Analytics, как упоминалось выше, а затем вызвать ее непосредственно из запроса. Логику запроса можно проверить с помощью JavaScript UDF, используя средства Stream Analytics для Visual Studio.
Ошибки времени выполнения JavaScript считаются неустранимыми и регистрируются в журнале действий. Чтобы получить этот журнал, перейдите на портале Azure к нужному заданию и щелкните Журнал действий.
Вызов определяемой пользователем функции из запроса
Вы можете легко вызвать функцию JavaScript в запросе с помощью псевдонима функции с префиксом udf. Ниже приведен пример JavaScript UDF, которая преобразует шестнадцатеричные значения в целочисленное значение, вызываемое в запросе Stream Analytics.
SELECT
time,
UDF.hex2Int(offset) AS IntOffset
INTO
output
FROM
InputStream
Поддерживаемые объекты JavaScript
Определяемые пользователем функции JavaScript в Azure Stream Analytics могут использовать все стандартные встроенные объекты JavaScript. Список этих объектов вы найдете здесь.
Преобразование типов Stream Analytics и JavaScript
Существуют различия между типами, которые поддерживаются в языке запросов Stream Analytics и в JavaScript. В следующей таблице перечислены сопоставления преобразования между этими типами.
| Stream Analytics | JavaScript |
|---|---|
| BIGINT | Число (JavaScript может представлять целые числа только до значения 2^53). |
| Дата и время | Дата (JavaScript поддерживает только миллисекунды) |
| double | Number |
| nvarchar(MAX) | Строка |
| Записей | Объект |
| Array | Array |
| NULL | NULL |
Ниже описаны преобразования из типов JavaScript в типы Stream Analytics.
| JavaScript | Stream Analytics |
|---|---|
| Number | Значение типа bigint, если это целое число в диапазоне от long.MinValue до long.MaxValue. Иначе используется тип double. |
| Дата | Дата и время |
| Строка | nvarchar(MAX) |
| Объект | Записей |
| Array | Array |
| NULL, не определено | NULL |
| Любой другой тип (например, функция или ошибка) | Не поддерживается (возникает ошибка времени выполнения) |
Язык JavaScript учитывает регистр, поэтому регистр полей объекта в коде JavaScript должен совпадать с регистром полей во входных данных. В заданиях с уровнем совместимости 1.0 в полях из инструкции SQL SELECT текст преобразуется в нижний регистр. При уровне совместимости 1.1 и выше поля из инструкции SELECT будут иметь тот же регистр, что и в запросе SQL.
Другие методы использования определяемой пользователем функции
Вывод вложенных значений JSON
Если вы используете этап обработки результатов, на котором входными данными являются выходные данные в формате JSON задания Stream Analytics, вам нужно записать строку JSON в выходные данные. Приведенный ниже пример вызывает функцию JSON.stringify() , которая упаковывает все полученные пары "имя — значение" и передает их единой строкой в качестве выходных данных.
Определение определяемой пользователем функции JavaScript:
function main(x) {
return JSON.stringify(x);
}
Пример запроса
SELECT
DataString,
DataValue,
HexValue,
UDF.jsonstringify(input) As InputEvent
INTO
output
FROM
input PARTITION BY PARTITIONID
Приведение строки к объекту JSON для обработки
Если у вас есть строковое поле в формате JSON, которое вы хотите преобразовать в объект JSON для обработки в определяемой пользователем функции JavaScript, можно использовать функцию JSON.parse() для создания соответствующего объекта JSON.
Определение определяемой пользователем функции JavaScript:
function main(x) {
var person = JSON.parse(x);
return person.name;
}
Пример запроса
SELECT
UDF.getName(input) AS Name
INTO
output
FROM
input
Использование try/catch для обработки ошибок
Блоки try/catch помогают выявить проблемы с неправильно сформированными входными данными, передаваемыми в определяемую пользователем функцию JavaScript.
Определение определяемой пользователем функции JavaScript:
function main(input, x) {
var obj = null;
try{
obj = JSON.parse(x);
}catch(error){
throw input;
}
return obj.Value;
}
Пример запроса: передача всей записи в качестве первого параметра для ее возврата при возникновении ошибки.
SELECT
A.context.company AS Company,
udf.getValue(A, A.context.value) as Value
INTO
output
FROM
input A
toLocaleString()
Метод toLocaleString в JavaScript можно использовать для возврата строки с учетом языка, представляющей данные даты и времени для среды, из которой вызывается этот метод. Хотя Azure Stream Analytics принимает в качестве системной метки времени только дату и время в формате UTC, этот метод можно использовать, чтобы преобразовать системную метку времени в данные с другим языковым стандартом и часовым поясом. Этот метод соответствует тому же принципу реализации, что и метод в Internet Explorer.
Определение определяемой пользователем функции JavaScript:
function main(datetime){
const options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
return datetime.toLocaleDateString('de-DE', options);
}
Пример запроса: передача даты и времени в качестве входного значения
SELECT
udf.toLocaleString(input.datetime) as localeString
INTO
output
FROM
input
Результатом этого запроса будет входное значение времени и даты в de-DE с предоставленными параметрами.
Samstag, 28. Dezember 2019
Ведение журнала пользователя
Механизм ведения журнала позволяет пользователям собирать пользовательские сведения во время выполнения задания. Данные журнала можно использовать для отладки или оценки правильности пользовательского кода в режиме реального времени. Этот механизм доступен с помощью трех различных методов.
Console.Info()
Console.Info метод используется для записи в журнал общих сведений во время выполнения кода. Этот метод регистрирует данные без прерывания вычислений. Зарегистрированное сообщение будет отмечено как информационное на уровне событий.
console.info('my info message');
Console.Warn()
Метод Console.Warn используется для регистрации данных, которые могут быть неправильными или ожидаемыми, но по-прежнему принимаются для вычислений. Этот метод не прерывает вычисление и возобновляет выполнение после возврата метода. Зарегистрированное сообщение будет отмечено как предупреждение уровня событий.
console.warn('my warning message');
Console.Error() и Console.Log()
Метод Console.Error используется только для регистрации случаев ошибок, при которых код не может продолжать выполняться. Этот метод создает исключение со сведениями об ошибке, предоставленными в качестве входного параметра, и задание перестанет выполняться. Зарегистрированное сообщение об ошибке будет отмечено как ошибка уровня событий.
console.error('my error message');
Доступ к сообщениям журнала можно получить с помощью журналов диагностики.
atob() и btoa()
Метод btoa() можно использовать для кодирования строки ASCII в Base64. Обычно это делается для передачи данных в двоичном формате. Метод atob() можно использовать для декодирования строки данных, закодированной в Base64, в формат строки ASCII.
var myAsciiString = 'ascii string';
var encodedString = btoa(myAsciiString);
var decodedString = atob(encodedString);