Funções definidas pelo utilizador do 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 Cadeia, RegExp, Matemática, Matriz e Data que o JavaScript fornece, 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 utilizador do JavaScript suportam funções escalares sem estado e apenas de computação que não necessitam de 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 de Matemática JavaScript
• Realizar operações de matriz como ordenar, associar, localizar e preencher

Eis algumas coisas que não pode fazer com uma função definida pelo utilizador javaScript no Stream Analytics:

• Chame pontos finais REST externos, por exemplo, fazendo pesquisa de IP inversa ou solicitando dados de referência de uma origem 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, deve evitar utilizá-las. Estas funções não devolvem o mesmo resultado sempre que lhes chama e o serviço Azure Stream Analytics não mantém um diário de invocações de funções e devolveu resultados. Se uma função devolver resultados diferentes nos mesmos eventos, a repetibilidade não é garantida quando uma tarefa é reiniciada por si ou pelo serviço Stream Analytics.

Adicionar uma função definida pelo utilizador javaScript à sua tarefa

Para criar uma função definida pelo utilizador javaScript na sua tarefa do Stream Analytics, selecione Funções em Topologia de Tarefas. Em seguida, selecione JavaScript UDF no menu pendente +Adicionar .

Em seguida, tem de fornecer as seguintes propriedades e selecionar Guardar.

Testar e resolver problemas de UDFs javaScript

Pode testar e depurar a lógica do JavaScript UDF em qualquer browser. A depuração e teste da lógica destas funções definidas pelo utilizador não é atualmente suportada no portal do Stream Analytics. Assim que a função funcionar conforme esperado, pode adicioná-la à tarefa do Stream Analytics, conforme mencionado acima, e invocá-la diretamente a partir da consulta. Pode testar a lógica de consulta com o JavaScript UDF com as ferramentas do Stream Analytics para o 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

Pode invocar facilmente a função JavaScript na consulta com o prefixo de alias de função com udf. Eis um exemplo de um UDF javaScript que converte valores hexadecimais em número inteiro que está a ser invocado numa 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:

Seguem-se conversões do JavaScript para o Stream Analytics:

A linguagem JavaScript é sensível às maiúsculas e minúsculas e o invólucro dos campos de objeto no código JavaScript tem de corresponder ao invólucro dos campos nos dados recebidos. As tarefas com o nível de compatibilidade 1.0 irão converter campos da instrução SELECT do SQL para serem em minúsculas. Em 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

Cast string to JSON object to process

Se tiver um campo de cadeia que seja JSON e quiser convertê-lo num objeto JSON para processamento num UDF JavaScript, pode utilizar a função JSON.parse() para criar um objeto JSON que pode ser utilizado.

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

Utilizar try/catch para processamento de erros

Os blocos try/catch podem ajudá-lo a identificar problemas com dados de entrada mal formados que são transmitidos 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: transmita o registo inteiro como primeiro parâmetro para que possa ser devolvido se existir 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 utilizado para devolver uma cadeia sensível à linguagem que representa os dados de data/hora de onde este método é chamado. Apesar de o Azure Stream Analtyics aceitar apenas a hora de data UTC como carimbo de data/hora do sistema, este método pode ser utilizado para ocultar o carimbo de data/hora do sistema para outra região e fuso horário. Este método segue o mesmo comportamento de implementação que o que está 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: transmitir um datetime como valor de entrada

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

O resultado desta consulta será o datetime de entrada na des-DE com as opções fornecidas.

Samstag, 28. Dezember 2019

Registo de Utilizadores

O mecanismo de registo permite que os utilizadores capturem informações personalizadas enquanto uma tarefa está em execução. Os dados de registo podem ser utilizados 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 é utilizado para registar informações gerais durante a execução do código. Este método irá registar dados sem interromper a computação. A mensagem registada será marcada como Informação ao Nível do Evento.

console.info('my info message');

Console.Warn()

O método Console.Warn é utilizado para registar dados que podem não estar corretos ou esperados, mas que ainda são aceites para computação. Este método não interromperá a computação e retomará a execução após o método ser devolvido. A mensagem registada será marcada como Aviso de Nível de Evento.

console.warn('my warning message');

Console.Error() e Console.Log()

O método Console.Error só é utilizado para registar casos de erro em que o código não pode continuar a ser executado. Este método irá gerar uma exceção com as informações de erro fornecidas, uma vez que o parâmetro de entrada e a tarefa deixarão de ser executados. A mensagem de erro registada será marcada como Erro ao Nível do Evento.

console.error('my error message');

Pode aceder a mensagens de registo através dos registos de diagnóstico.

atob() e btoa()

O método btoa() pode ser utilizado para codificar uma cadeia ASCII em Base64. Normalmente, isto é feito para transferir dados num formato binário. O método atob() pode ser utilizado para descodificar uma cadeia de dados codificada em Base64 para um formato de cadeia ASCII.

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

Passos seguintes

• Machine Learning UDF
• UDF em C#