Funções definidas pelo usuário JavaScript no Azure Stream Analytics
O Azure Stream Analytics suporta as funções definidas pelo utilizador escritas no JavaScript. Com o conjunto avançado de métodos de Cadeia, RegExp, Matemática, Matriz e Data que o JavaScript dispõe, as transformações de dados complexas com tarefas do Stream Analytics tornam-se mais fáceis de criar.
Descrição geral
As funções definidas pelo usuário JavaScript suportam funções escalares sem monitoração de estado, somente computação, que não exigem conectividade externa. O valor devolvido de uma função só pode ser um valor escalar (único). Depois de adicionar uma função definida pelo utilizador do JavaScript para uma tarefa, pode utilizar a função em qualquer parte da consulta, como uma função escalar incorporada.
Seguem-se alguns cenários onde as funções definidas pelo utilizador do JavaScript poderão ser úteis:
- Analisar e manipular cadeias com funções de expressão regular, por exemplo, Regexp_Replace() e Regexp_Extract()
- Descodificar e codificar dados, por exemplo, conversão de binário para hexadecimal
- Fazer cálculos matemáticos com funções JavaScript Math
- Realizar operações de array como classificar, juntar, localizar e preencher
Aqui estão algumas coisas que você não pode fazer com uma função JavaScript definida pelo usuário no Stream Analytics:
- Chamar pontos de extremidade REST externos, por exemplo, fazendo pesquisa reversa de IP ou extraindo dados de referência de uma fonte externa
- Executar a serialização de formato de evento personalizado ou a desserialização em entradas/saídas
- Criar agregações personalizadas
Embora funções como Date.GetDate() ou Math.random() não estejam bloqueadas na definição de funções, você deve evitar usá-las. Essas funções não retornam o mesmo resultado toda vez que você as chama, e o serviço Azure Stream Analytics não mantém um diário de invocações de função e resultados retornados. Se uma função retornar resultados diferentes nos mesmos eventos, a repetibilidade não será garantida quando um trabalho for reiniciado por você ou pelo serviço Stream Analytics.
Adicionar uma função JavaScript definida pelo usuário ao seu trabalho
Nota
Essas etapas funcionam nos trabalhos do Stream Analytics configurados para serem executados na nuvem. Se seu trabalho do Stream Analytics estiver configurado para ser executado no Azure IoT Edge, use o Visual Studio e escreva a função definida pelo usuário usando C#.
Para criar uma função JavaScript definida pelo usuário em seu trabalho do Stream Analytics, selecione Funções em Topologia do trabalho. Em seguida, selecione JavaScript UDF no menu suspenso +Adicionar .
Em seguida, você deve fornecer as seguintes propriedades e selecionar Salvar.
| Property | Description |
|---|---|
| Alias de função | Insira um nome para invocar a função em sua consulta. |
| Tipo de saída | Tipo que será retornado pela função JavaScript definida pelo usuário para sua consulta do Stream Analytics. |
| Definição de função | Implementação da sua função JavaScript que será executada sempre que o UDF for invocado a partir da sua consulta. |
Testar e solucionar problemas de UDFs JavaScript
Você pode testar e depurar sua lógica UDF JavaScript em qualquer navegador. Atualmente, não há suporte para depuração e teste da lógica dessas funções definidas pelo usuário no portal do Stream Analytics. Quando a função funcionar conforme o esperado, você poderá adicioná-la ao trabalho do Stream Analytics como mencionado acima e, em seguida, invocá-la diretamente da sua consulta. Você pode testar sua lógica de consulta com JavaScript UDF usando as ferramentas do Stream Analytics para Visual Studio.
Os erros de runtime do JavaScript são considerados fatais e são apresentados no Registo de atividades. Para obter o registo, no portal do Azure, aceda à sua tarefa e selecione Registo de atividades.
Chamar uma função definida pelo utilizador do JavaScript numa consulta
Você pode facilmente invocar sua função JavaScript em sua consulta usando o alias de função prefixado com udf. Aqui está um exemplo de um UDF JavaScript que converte valores hexadecimais em inteiros sendo invocados em uma consulta do Stream Analytics.
SELECT
time,
UDF.hex2Int(offset) AS IntOffset
INTO
output
FROM
InputStream
Objetos de JavaScript suportados
As funções definidas pelo utilizador do JavaScript do Stream Analytics suportam objetos do JavaScript standard incorporados. Para obter uma lista destes objetos, veja Objetos Globais.
Conversão de tipos do Stream Analytics e do JavaScript
Existem diferenças nos tipos que a linguagem de consulta do Stream Analytics e do JavaScript suportam. Esta tabela lista os mapeamentos de conversão entre os dois:
| Stream Analytics | JavaScript |
|---|---|
| bigint | Number (o JavaScript só pode representar números inteiros até precisamente 2^53) |
| DateTime | Date (o JavaScript só suporta milissegundos) |
| duplo | Número |
| nvarchar(MAX) | String |
| Registo | Object |
| Matriz | Matriz |
| NULL | Nulo |
Seguem-se conversões do JavaScript para o Stream Analytics:
| JavaScript | Stream Analytics |
|---|---|
| Número | Bigint (se o número for redondo e entre long.MinValue e long.MaxValue; caso contrário, é duplo) |
| Date | DateTime |
| String | nvarchar(MAX) |
| Object | Registo |
| Matriz | Matriz |
| Null, Undefined | NULL |
| Qualquer outro tipo (por exemplo, uma função ou erro) | Não suportado (resultados num erro de runtime) |
A linguagem JavaScript diferencia maiúsculas de minúsculas e o invólucro dos campos no código JavaScript deve corresponder ao invólucro dos campos nos dados recebidos. Os trabalhos com nível de compatibilidade 1.0 converterão os campos da instrução SQL SELECT em minúsculas. No nível de compatibilidade 1.1 e superior, os campos da instrução SELECT terão o mesmo invólucro especificado na consulta SQL.
Outros padrões da função definida pelo utilizador do JavaScript
Escrever JSON aninhado para a saída
Se tiver um passo de processamento de seguimento que utiliza uma saída da tarefa do Stream Analytics como entrada e requer um formato JSON, pode escrever uma cadeia JSON para a saída. O exemplo seguinte chama a função JSON.stringify() para empacotar todos os pares de nome/valor da entrada e, em seguida, escreve-os como um valor de cadeia único na saída.
Definição da função definida pelo utilizador do JavaScript:
function main(x) {
return JSON.stringify(x);
}
Consulta de exemplo:
SELECT
DataString,
DataValue,
HexValue,
UDF.jsonstringify(input) As InputEvent
INTO
output
FROM
input PARTITION BY PARTITIONID
Transmitir cadeia de caracteres para objeto JSON para processar
Se você tiver um campo de cadeia de caracteres que é JSON e quiser convertê-lo em um objeto JSON para processamento em um UDF JavaScript, poderá usar a função JSON.parse() para criar um objeto JSON que pode ser usado.
Definição da função definida pelo utilizador do JavaScript:
function main(x) {
var person = JSON.parse(x);
return person.name;
}
Consulta de exemplo:
SELECT
UDF.getName(input) AS Name
INTO
output
FROM
input
Use try/catch para tratamento de erros
Os blocos try/catch podem ajudá-lo a identificar problemas com dados de entrada malformados que são passados para um UDF JavaScript.
Definição da função definida pelo utilizador do JavaScript:
function main(input, x) {
var obj = null;
try{
obj = JSON.parse(x);
}catch(error){
throw input;
}
return obj.Value;
}
Consulta de exemplo: passe o registro inteiro como primeiro parâmetro para que ele possa ser retornado se houver um erro.
SELECT
A.context.company AS Company,
udf.getValue(A, A.context.value) as Value
INTO
output
FROM
input A
toLocaleString()
O método toLocaleString em JavaScript pode ser usado para retornar uma cadeia de caracteres sensível ao idioma que representa os dados de data e hora de onde esse método é chamado. Embora o Azure Stream Analytics só aceite a hora UTC como carimbo de data/hora do sistema, esse método pode ser usado para ocultar o carimbo de data/hora do sistema para outra localidade e fuso horário. Este método segue o mesmo comportamento de implementação que o disponível no Internet Explorer .
Definição da função definida pelo utilizador do JavaScript:
function main(datetime){
const options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
return datetime.toLocaleDateString('de-DE', options);
}
Consulta de exemplo: Passar um datetime como valor de entrada
SELECT
udf.toLocaleString(input.datetime) as localeString
INTO
output
FROM
input
A saída desta consulta será a entrada datetime em de-DE com as opções fornecidas.
Samstag, 28. Dezember 2019
Registo de Utilizadores
O mecanismo de registro em log permite que os usuários capturem informações personalizadas enquanto um trabalho está em execução. Os dados de log podem ser usados para depurar ou avaliar a correção do código personalizado em tempo real. Este mecanismo está disponível através de três métodos diferentes.
Console.Info()
Console.Info método é usado para registrar informações gerais durante a execução do código. Esse método registrará dados sem interromper a computação. A mensagem registrada será marcada como Informativa de Nível de Evento.
console.info('my info message');
Console.Warn()
O método Console.Warn é usado para registrar dados que podem não estar corretos ou esperados, mas ainda são aceitos para computação. Este método não interromperá a computação e retomará a execução depois que o método for retornado. A mensagem registrada será marcada como Aviso de Nível de Evento.
console.warn('my warning message');
Console.Error() e Console.Log()
O método Console.Error é usado apenas para registrar casos de erro em que o código não pode continuar a ser executado. Esse método lançará uma exceção com as informações de erro fornecidas como o parâmetro de entrada e o trabalho pararão de ser executados. A mensagem de erro registrada será marcada como Erro de Nível de Evento.
console.error('my error message');
Você pode acessar mensagens de log por meio dos logs de diagnóstico.
atob() e btoa()
O método btoa() pode ser usado para codificar uma string ASCII em Base64. Isso geralmente é feito para transferir dados em um formato binário. O método atob() pode ser usado para decodificar uma cadeia de dados codificados em Base64 para um formato de cadeia de caracteres ASCII.
var myAsciiString = 'ascii string';
var encodedString = btoa(myAsciiString);
var decodedString = atob(encodedString);