Определяемые пользователем функции JavaScript в Azure Stream Analytics

Azure Stream Analytics поддерживает определяемые пользователем функции, написанные на языке JavaScript. Используя богатый набор методов String, RegExp, Math, Array и Date , который предоставляет JavaScript, вы можете создавать сложные преобразования данных в задачах Stream Analytics. Определяемые пользователем функции JavaScript поддерживают скалярные вычислительные функции без отслеживания состояния, не требующие внешнего подключения. Возвращаемое значение функции может быть только скалярным (одиночным). Добавив в задание определяемую пользователем функцию JavaScript, вы сможете использовать ее в любом месте запроса, например во встроенной скалярной функции.

В этой статье описывается, когда использовать пользовательские функции JavaScript и как их определять и вызывать в ваших задачах Stream Analytics.

Когда использовать пользовательскую функцию JavaScript

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

• Разбор и обработка строк с помощью регулярных выражений, например , Regexp_Replace() и Regexp_Extract()
• Декодирование и кодирование данных, например преобразование двоичных данных в шестнадцатеричные.
• Выполнение математических вычислений с помощью математических функций JavaScript
• Операции с массивами, такие как сортировка, присоединение, поиск и заполнение.

Вот некоторые вещи, которые нельзя сделать, используя пользовательскую функцию JavaScript в Stream Analytics:

• Например, вызывайте внешние REST-конечные точки, выполняя обратный IP-поиск или вытягивая ссылки из внешнего источника
• Выполнять сериализацию или десериализацию в пользовательском формате событий для входных или выходных данных
• Создание пользовательских статистических функций.

Хотя такие функции, как Date.GetDate() или Math.random(), не запрещены в определении функций, избегайте их использования. Эти функции возвращают разные результаты при каждом вызове, а служба Azure Stream Analytics не ведет журнал вызовов и возвращаемых результатов для функций. Если функция возвращает другой результат для одних и тех же событий, повторяемость результатов не гарантируется, если задание перезапускаете вы или служба Stream Analytics.

Определите пользовательскую функцию JavaScript в портале Azure

Для задачи Stream Analytics, работающей в облаке, добавьте пользовательскую функцию JavaScript со страницы Functions в разделе Job Topology, где в меню +Add есть опция JavaScript UDF .

Примечание.

Этот опыт применяется к вакансиям в Stream Analytics, настроенных на работу в облаке. Если задание Stream Analytics настроено для работы в Azure IoT Edge, используйте вместо этого Visual Studio и напишите определяемую пользователем функцию, используя C#.

Определение функции состоит из следующих свойств:

Свойство	Описание
Псевдоним функции	Имя, которое вызывает функцию в вашем запросе.
Тип выходных данных	Тип, который определяемая пользователем функция JavaScript возвращает для вашего запроса Stream Analytics.
Определение функции	Реализация вашей JavaScript-функции, которая запускается каждый раз, когда UDF вызывается из вашего запроса.

Тестирование и устранение неполадок JavaScript UDF-логики

Поскольку портал Stream Analytics не поддерживает отладку и тестирование логики этих пользовательских функций, вы можете тестировать и отладить логику JavaScript UDF в любом браузере. Когда функция работает как ожидается, она готова добавить её в задачу Stream Analytics и вызвать её напрямую из вашего запроса. Вы также можете проверить логику запроса с помощью JavaScript UDF, используя инструменты Stream Analytics для Visual Studio.

Stream Analytics считает ошибки во время выполнения JavaScript фатальными и выводит их в журнал активности. Журнал доступен в портале Azure на странице журнала активности вашей работы.

Вызвать пользовательскую функцию JavaScript в запросе

Чтобы вызвать функцию 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 конвертирует значения по мере их передачи между ними.

Stream Analytics и преобразование типов в JavaScript

Язык запросов Stream Analytics и JavaScript поддерживают разные типы. В этой таблице перечислены соответствия преобразования между ними:

Stream Analytics	JavaScript
bigint	Число (JavaScript может представлять целые числа только до значения 2^53).
Дата/время	Дата (JavaScript поддерживает только миллисекунды)
double	Число
nvarchar(MAX)	Строка
Запись	Объект
Массив	Массив
NULL	Null

Ниже описаны преобразования из типов JavaScript в типы Stream Analytics.

JavaScript	Stream Analytics
Число	Bigint (если число целое и находится между long.MinValue и long.MaxValue; в противном случае — double)
Дата	Дата/время
Строка	nvarchar(MAX)
Объект	Запись
Массив	Массив
NULL, не определено	NULL
Любой другой тип (например, функция или ошибка)	Не поддерживается (возникает ошибка времени выполнения)

JavaScript чувствителен к регистру, и корпус объектных полей в JavaScript-коде должен совпадать с облицовкой полей в входящих данных. Задачи с уровнем совместимости 1.0 преобразуют поля в операторе SQL SELECT в нижний регистр. На уровне совместимости 1.1 и выше поля оператора SELECT имеют тот же корпус, что и в SQL-запросе.

Типичные функциональные паттерны

Следующие шаблоны показывают распространённые способы использования пользовательских функций JavaScript для преобразования данных в ваших запросах Stream Analytics. Каждый шаблон содержит определение функции и примерный запрос, вызывающий её.

Записать вложенный JSON в выходной поток

Если у вас есть последующий этап обработки, который использует выходные данные задания Stream Analytics в качестве входных данных, и ему требуется формат JSON, можно записать в выходные данные строку JSON. Следующее определение функции вызывает функцию JSON.stringify() для упаковки всех пар имён/значений входа и записывания их в виде одного строкового значения на выходе.

function main(x) {
return JSON.stringify(x);
}

Запрос Stream Analytics вызывает функцию, как показано в следующем примере.

SELECT
    DataString,
    DataValue,
    HexValue,
    UDF.jsonstringify(input) As InputEvent
INTO
    output
FROM
    input PARTITION BY PARTITIONID

Приведение строки к объекту JSON для обработки

Если у вас есть строковое поле JSON и вы хотите преобразовать его в JSON-объект для обработки в JavaScript UDF, вы можете использовать функцию JSON.parse( ) для создания JSON-объекта, который затем можно использовать. Следующее определение функции анализирует строку и возвращает свойство из полученного объекта.

function main(x) {
var person = JSON.parse(x);  
return person.name;
}

Запрос Stream Analytics вызывает функцию, как показано в следующем примере.

SELECT
    UDF.getName(input) AS Name
INTO
    output
FROM
    input

Использование try/catch для обработки ошибок

Блоки try/catch помогут выявить проблемы с искажёнными входными данными, которые вы передаёте в JavaScript UDF. Следующее определение функции использует блок try/catch для обработки ошибок разбора.

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. Следующее определение функции преобразует входное значение даты и времени в локаль de-DE.

function main(datetime){
    const options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
    return datetime.toLocaleDateString('de-DE', options);
}

В следующем примере запроса в качестве входного значения передаётся datetime.

SELECT
    udf.toLocaleString(input.datetime) as localeString
INTO
    output
FROM
    input

Выход этого запроса — это входная дата времени в de-DE с предоставленными опциями.

Samstag, 28. December 2019

Ведение журнала пользователей

Логирование — это механизм, который Azure Stream Analytics использует для захвата пользовательской информации из пользовательской функции JavaScript во время выполнения задачи. Поскольку выполняющаяся задача в остальном непрозрачна, лог-данные дают вам видимость поведения и корректности вашего пользовательского кода в реальном времени. Каждое лог-сообщение содержит уровень событий, который указывает на значимость сообщения и может ли задание продолжать работу.

Информационные сообщения исходят из метода console.info(), например console.info('my info message');, . Этот уровень записывает общую информацию во время выполнения и не прерывает вычисления. Предупреждающие сообщения поступают из метода console.warn( ), например console.warn('my warning message');. Этот уровень фиксирует данные, которые могут быть неожиданными, но всё же приемлемы для вычислений, поэтому задание продолжает выполняться. Сообщения об ошибках выводятся методами console.error() и console.log(), например console.error('my error message');. Эти методы применяются только в случаях, когда код не может продолжить работу, поэтому они выдают исключение с предоставленной информацией об ошибке и останавливают работу.

Получить доступ к сообщениям журнала можно через диагностические журналы.

atob() и btoa()

Stream Analytics поддерживает два метода конвертации в Base64, что является распространённым способом кодирования бинарных данных в виде текста. Метод btoa() кодирует ASCII-строку в Base64, а метод atob() декодирует строку данных, закодированных Base64, обратно в ASCII-строку. В следующем примере btoa() кодируется ASCII-строка, atob() а затем декодирует результат обратно в исходную строку.

var myAsciiString = 'ascii string';
var encodedString = btoa(myAsciiString);
var decodedString = atob(encodedString);

Связанные материалы

• UDF с машинным обучением
• Пользовательские функции C#