Agregações definidas pelo usuário do JavaScript do Azure Stream Analytics

Artigo
01/10/2024

O Azure Stream Analytics dá suporte a agregações definidas pelo usuário (UDA) escritas em JavaScript, ele permite que você implemente uma lógica de negócios complexa com monitoração de estado. Dentro do UDA você tem controle total da estrutura de dados do estado, acumulação de estado, desacumulação de estado e cálculo de resultados agregados. O artigo apresenta as duas interfaces UDA JavaScript diferentes, as etapas para criar um UDA e como usar o UDA com operações baseadas em janela na consulta do Stream Analytics.

Agregações definidas pelo usuário JavaScript

Uma agregação definida pelo usuário é usada sobre uma especificação de janela de tempo para agregar sobre os eventos nessa janela e produzir um único valor de resultado. Existem dois tipos de interfaces UDA que o Stream Analytics suporta atualmente, AccumulateOnly e AccumulateDecumul. Ambos os tipos de UDA podem ser usados por Tumbling, Hopping, Sliding e Session Window. AccumulateDecumul UDA tem um desempenho melhor do que AccumulateOnly UDA quando usado em conjunto com Hopping, Deslizamento e Janela de sessão. Você escolhe um dos dois tipos com base no algoritmo usado.

Acumular apenas agregados

Os agregados AccumulateOnly só podem acumular novos eventos ao seu estado, o algoritmo não permite a desacumulação de valores. Escolha este tipo de agregado quando desacumular uma informação de evento do valor de estado for impossível de implementar. A seguir está o modelo JavaScript para agregados AccumulatOnly:

// Sample UDA which state can only be accumulated.
function main() {
    this.init = function () {
        this.state = 0;
    }

    this.accumulate = function (value, timestamp) {
        this.state += value;
    }

    this.computeResult = function () {
        return this.state;
    }
}

AcumularAcumular agregados

Os agregados AccumulateDeaccumulate permitem a desacumulação de um valor acumulado anterior do estado, por exemplo, remova um par chave-valor de uma lista de valores de evento ou subtraia um valor de um estado de soma agregada. A seguir está o modelo JavaScript para agregações AccumulateDecumul:

// Sample UDA which state can be accumulated and deaccumulated.
function main() {
    this.init = function () {
        this.state = 0;
    }

    this.accumulate = function (value, timestamp) {
        this.state += value;
    }

    this.deaccumulate = function (value, timestamp) {
        this.state -= value;
    }

    this.deaccumulateState = function (otherState){
        this.state -= otherState.state;
    }

    this.computeResult = function () {
        return this.state;
    }
}

UDA - Declaração de função JavaScript

Cada UDA JavaScript é definido por uma declaração de objeto Function. A seguir estão os principais elementos em uma definição de UDA.

Alias de função

O alias de função é o identificador UDA. Quando chamado na consulta do Stream Analytics, sempre use o alias UDA junto com um prefixo "uda".

Tipo de função

Para UDA, o tipo de função deve ser JavaScript UDA.

Tipo de saída

Um tipo específico suportado pelo trabalho do Stream Analytics ou "Qualquer" se você quiser manipular o tipo em sua consulta.

Nome da função

O nome deste objeto Function. O nome da função deve corresponder ao alias UDA.

Método - init()

O método init() inicializa o estado da agregação. Este método é chamado quando a janela é iniciada.

Método – acumular()

O método accumulate() calcula o estado UDA com base no estado anterior e nos valores de evento atuais. Este método é chamado quando um evento entra em uma janela de tempo (TUMBLINGWINDOW, HOPPINGWINDOW, SLIDINGWINDOW ou SESSIONWINDOW).

Método – desacumular()

O método deaccumulate() recalcula o estado com base no estado anterior e nos valores de evento atuais. Este método é chamado quando um evento sai de uma SLIDINGWINDOW ou SESSIONWINDOW.

Método – deaccumulateState()

O método deaccumulateState() recalcula o estado com base no estado anterior e no estado de um salto. Este método é chamado quando um conjunto de eventos sai de uma HOPPINGWINDOW.

Método – computeResult()

O método computeResult() retorna o resultado agregado com base no estado atual. Este método é chamado no final de uma janela de tempo (TUMBLINGWINDOW, HOPPINGWINDOW, SLIDINGWINDOW ou SESSIONWINDOW).

Tipos de dados de entrada e saída suportados pelo JavaScript UDA

Para tipos de dados JavaScript UDA, consulte a seção Stream Analytics e conversão de tipo JavaScript de Integrar UDFs JavaScript.

Adicionando um UDA JavaScript do portal do Azure

Abaixo percorremos o processo de criação de um UDA a partir do Portal. O exemplo que usamos aqui é o cálculo de médias ponderadas pelo tempo.

Agora vamos criar um UDA JavaScript em um trabalho ASA existente seguindo as etapas.

Entre no portal do Azure e localize seu trabalho existente do Stream Analytics.
Em seguida, selecione o link de funções em TOPOLOGIA DE TRABALHO.
Selecione Adicionar para adicionar uma nova função.
Na visualização Nova função, selecione JavaScript UDA como o Tipo de função e, em seguida, você verá um modelo UDA padrão exibido no editor.

Preencha "TWA" como o alias UDA e altere a implementação da função da seguinte forma:

// Sample UDA which calculate Time-Weighted Average of incoming values.
function main() {
    this.init = function () {
        this.totalValue = 0.0;
        this.totalWeight = 0.0;
    }

    this.accumulate = function (value, timestamp) {
        this.totalValue += value.level * value.weight;
        this.totalWeight += value.weight;

    }

    // Uncomment below for AccumulateDeaccumulate implementation
    /*
    this.deaccumulate = function (value, timestamp) {
        this.totalValue -= value.level * value.weight;
        this.totalWeight -= value.weight;
    }

    this.deaccumulateState = function (otherState){
        this.state -= otherState.state;
        this.totalValue -= otherState.totalValue;
        this.totalWeight -= otherState.totalWeight;
    }
    */

    this.computeResult = function () {
        if(this.totalValue == 0) {
            result = 0;
        }
        else {
            result = this.totalValue/this.totalWeight;
        }
        return result;
    }
}

Depois de selecionar o botão "Salvar", seu UDA aparece na lista de funções.
Selecione a nova função "TWA", você pode verificar a definição da função.

Chamando JavaScript UDA na consulta ASA

No portal do Azure e abra seu trabalho, edite a consulta e chame a função TWA() com um prefixo de mandato "uda.". Por exemplo:

WITH value AS
(
    SELECT
    NoiseLevelDB as level,
    DurationSecond as weight
FROM
    [YourInputAlias] TIMESTAMP BY EntryTime
)
SELECT
    System.Timestamp as ts,
    uda.TWA(value) as NoseDoseTWA
FROM value
GROUP BY TumblingWindow(minute, 5)

Consulta de teste com UDA

Crie um arquivo JSON local com o conteúdo abaixo, carregue o arquivo para o trabalho do Stream Analytics e teste a consulta acima.

[
  {"EntryTime": "2017-06-10T05:01:00-07:00", "NoiseLevelDB": 80, "DurationSecond": 22.0},
  {"EntryTime": "2017-06-10T05:02:00-07:00", "NoiseLevelDB": 81, "DurationSecond": 37.8},
  {"EntryTime": "2017-06-10T05:02:00-07:00", "NoiseLevelDB": 85, "DurationSecond": 26.3},
  {"EntryTime": "2017-06-10T05:03:00-07:00", "NoiseLevelDB": 95, "DurationSecond": 13.7},
  {"EntryTime": "2017-06-10T05:03:00-07:00", "NoiseLevelDB": 88, "DurationSecond": 10.3},
  {"EntryTime": "2017-06-10T05:05:00-07:00", "NoiseLevelDB": 103, "DurationSecond": 5.5},
  {"EntryTime": "2017-06-10T05:06:00-07:00", "NoiseLevelDB": 99, "DurationSecond": 23.0},
  {"EntryTime": "2017-06-10T05:07:00-07:00", "NoiseLevelDB": 108, "DurationSecond": 1.76},
  {"EntryTime": "2017-06-10T05:07:00-07:00", "NoiseLevelDB": 79, "DurationSecond": 17.9},
  {"EntryTime": "2017-06-10T05:08:00-07:00", "NoiseLevelDB": 83, "DurationSecond": 27.1},
  {"EntryTime": "2017-06-10T05:09:00-07:00", "NoiseLevelDB": 91, "DurationSecond": 17.1},
  {"EntryTime": "2017-06-10T05:09:00-07:00", "NoiseLevelDB": 115, "DurationSecond": 7.9},
  {"EntryTime": "2017-06-10T05:09:00-07:00", "NoiseLevelDB": 80, "DurationSecond": 28.3},
  {"EntryTime": "2017-06-10T05:10:00-07:00", "NoiseLevelDB": 55, "DurationSecond": 18.2},
  {"EntryTime": "2017-06-10T05:10:00-07:00", "NoiseLevelDB": 93, "DurationSecond": 25.8},
  {"EntryTime": "2017-06-10T05:11:00-07:00", "NoiseLevelDB": 83, "DurationSecond": 11.4},
  {"EntryTime": "2017-06-10T05:12:00-07:00", "NoiseLevelDB": 89, "DurationSecond": 7.9},
  {"EntryTime": "2017-06-10T05:15:00-07:00", "NoiseLevelDB": 112, "DurationSecond": 3.7},
  {"EntryTime": "2017-06-10T05:15:00-07:00", "NoiseLevelDB": 93, "DurationSecond": 9.7},
  {"EntryTime": "2017-06-10T05:18:00-07:00", "NoiseLevelDB": 96, "DurationSecond": 3.7},
  {"EntryTime": "2017-06-10T05:20:00-07:00", "NoiseLevelDB": 108, "DurationSecond": 0.99},
  {"EntryTime": "2017-06-10T05:20:00-07:00", "NoiseLevelDB": 113, "DurationSecond": 25.1},
  {"EntryTime": "2017-06-10T05:22:00-07:00", "NoiseLevelDB": 110, "DurationSecond": 5.3}
]

Obter ajuda

Para obter ajuda adicional, experimente a nossa página de perguntas e respostas da Microsoft para o Azure Stream Analytics.

Partilhar via