Criar um analisador

Este guia explica como criar um analisador. Os analisadores executam a transformação e o mapeamento de dados. As etapas exatas de transformação são definidas na documentação do scriptwhistle para o Manufacturing Data Engine (MDE).

Criar um analisador

Os analisadores realizam mapeamentos de origem para destino por meio de um script do Whistle. Ao criar um analisador, você precisa definir três elementos principais:

1. A classe de mensagem para cujo fluxo de mensagens um analisador faz inscrição (entrada).
2. Versão do tipo do fluxo de registros proto emitido pelo analisador (saída).
3. O script do Whistle para transformar mensagens de origem da classe de mensagem especificada (entrada) em registros proto da versão do tipo definida (saída).

O script Whistle é aplicado a todas as mensagens no fluxo da classe de mensagens de origem e gera registros proto de uma versão de tipo específica. Recomendamos que você reserve um tempo para modelar as classes de mensagens de origem para que elas compartilhem uma estrutura semântica e esquemática comum. Classes de mensagens de origem bem definidas ajudam a minimizar a lógica condicional complexa em analisadores. Consulte a seção sobre modelagem de classes de mensagens de origem para mais orientações.

Importante: a partir da versão 1.4.1 do Manufacturing Data Engine (MDE), os cabeçalhos das mensagens do Pub/Sub são armazenados em um atributo reservado chamado mdeHeaders. Se as mensagens de entrada contiverem esse atributo, uma expressão como embeddedMetadata: $root[where ($.field !=...)] vai substituir o atributo reservado e resultar na perda dos dados de cabeçalho do Pub/Sub fornecidos com a mensagem de borda. Use a expressão de filtro genérica do Whistle com cuidado para não perder dados.

É possível criar um analisador usando a API de configuração ou o console:

REST

POST /configuration/v1/parsers

{
  "name": "PARSER_NAME",
  "messageClassName": "SOURCE_MESSAGE_CLASS_NAME",
  "typeReference": {
    "name": "TYPE_NAME",
    "version": TYPE_VERSION
  },
  "script": "WHISTLE_SCRIPT"
}

Substitua:

• PARSER_NAME: o nome do analisador.
• SOURCE_MESSAGE_CLASS_NAME: o nome da classe de mensagem de origem a que esse analisador se inscreve.
• TYPE_NAME: o nome do tipo compartilhado pelos registros proto emitidos por esse analisador.
• TYPE_VERSION: a versão do tipo compartilhada pelos registros proto emitidos por esse analisador.
• WHISTLE_SCRIPT: o script do Whistle que define a transformação.

Console

1. Para criar um novo analisador usando o console, selecione a seção ANALISADORES no menu superior. Uma lista dos analisadores disponíveis é exibida:

   

2. Para cada analisador disponível, as seguintes informações são mostradas na lista:

   • Name:nome do analisador.
   • Message Class Name: nome da classe de mensagem de que o analisador está recebendo dados.
   • Type: tipo de destino emitido pelo analisador.
   • Type Version: versão do tipo de destino emitida pelo analisador.
   • Enabled: status do analisador (ativado ou desativado).
   • Actions: ações disponíveis para o analisador:
     • Ver/Editar: abre o menu de edição de um determinado analisador.
     • Desativar/ativar: permite desativar um analisador ativado ou ativar um analisador desativado.
     • Testar o analisador: abre uma interface dedicada para testar o analisador usando um arquivo JSON específico.
     • Excluir: exclui o analisador do MDE.

3. Para criar um novo analisador, clique em ADICIONAR NOVO ANALISADOR.

4. Para abrir a seção de edição de um determinado analisador, clique em Ver/Editar no ícone Ações. O menu lateral que mostra todos os parâmetros necessários para criar um novo analisador é exibido no lado direito da tela:

   

5. Para definir o novo analisador, os seguintes parâmetros precisam ser fornecidos:

   • Name: nome do analisador. Não pode ser editado depois de criado.
   • Message Class: nome da classe de mensagem de que o analisador extrai informações. Não pode ser modificado depois que o analisador é criado. Selecione a classe de mensagem na lista de classes disponíveis.
   • Parser Code: arquivo Whistle que define o mapeamento associado ao analisador. Ela pode ser modificada a qualquer momento. Modificar o código do Whistle não vai gerar uma nova versão dos analisadores. Os analisadores não têm controle de versões.
   • Type: Tipo de saída emitido pelo analisador. Não é possível modificar depois que o analisador é criado. Selecione o tipo na lista de opções disponíveis. Para novos analisadores, a versão mais recente do tipo é selecionada por padrão.

Para criar o analisador, modifique os parâmetros dele e clique em CRIAR na parte de baixo. Uma mensagem de confirmação é exibida se o novo analisador for criado com sucesso.

Testar um analisador

Para testar um analisador, forneça um script do Whistle e uma mensagem de entrada de amostra:

REST

POST /configuration/v1/parsers:test

{
  "script": "SCRIPT",
  "testMessage": TEST_MESSAGE
}

Substitua:

• SCRIPT: script do Whistle a ser testado (formatado como string).
• TEST_MESSAGE: mensagem de teste de entrada (formatada como objeto JSON).

Console

Você pode testar o analisador diretamente no menu Ações e no menu Editar analisador.

1. Para testar um analisador, clique em TESTAR. Uma tela de teste é aberta:

   

2. Forneça um exemplo de mensagem JSON para testar o analisador.

3. Insira a mensagem na caixa Entrada e clique no botão EXECUTAR TESTE.

• Se a transformação for bem-sucedida, a mensagem de saída será exibida na caixa Resultado.
• Se a transformação não for realizada, uma mensagem de erro será exibida com a provável causa do problema.

1. Use um arquivo JSON válido como mensagem de teste com uma estrutura que possa ser processada pelo arquivo Whistle do analisador. Por exemplo, este é um exemplo de um payload numérico gerado pela borda do Manufacturing Connect que pode ser testado no analisador default-numeric-value-to-default-numeric-records:

{
  "datatype": "int",
  "description": "",
  "deviceID": "0619E715-D1B8-438F-A1AB-E4D65D27EE83",
  "deviceName": "MicroLogix1100",
  "metadata": {
    "location": "ES-BCN-GRA",
    "manufacturer": "AllenBradley",
    "model": "MicroLogix1100",
    "os_revision": "Series B FRN 12.0",
    "source": "mce"
  },
  "registerId": "0997D2ED-B2AB-434C-9754-C1A3C2E9C165",
  "success": true,
  "tagName": "Manufactueing Connect edge_July_test_tag",
  "timestamp": 1691163012045,
  "value": 8004
}

Editar um analisador

É possível atualizar um analisador atual, incluindo o script Whistle:

REST

PATCH /configuration/v1/parsers/NAME

{
  "disabled": DISABLED,
  "script": "SCRIPT",
  "typeReference": {
    "name": "TYPE_NAME",
    "version": TYPE_VERSION
  },
  "script": "WHISTLE_SCRIPT"
}

Substitua:

• DISABLED: estado do analisador (verdadeiro ou falso).
• NAME: nome do analisador.
• TYPE_NAME: nome do tipo compartilhado pelos registros proto emitidos por esse analisador.
• TYPE_VERSION: versão do tipo compartilhada pelos registros proto emitidos por esse analisador.
• WHISTLE_SCRIPT: script do Whistle que define a transformação.

Console

1. Para abrir a seção de edição de um determinado analisador, clique em Ver/Editar no ícone Ações:

   

2. O menu lateral Editar analisador é aberto, mostrando os parâmetros necessários para configurar o analisador:

   

• Name: nome do analisador. Não pode ser editado depois de criado.
• Message Class: nome da classe de mensagem de que o analisador extrai informações. Não pode ser modificado depois que o analisador é criado.
• Parser Code: arquivo Whistle que define o mapeamento associado ao analisador. Ela pode ser modificada a qualquer momento. Modificar o código do Whistle não vai gerar uma nova versão dos analisadores. Os analisadores não são versionados.
• Type: Tipo de saída emitido pelo analisador. Não é possível modificar depois que o analisador é criado.
• Version: versão do tipo de saída emitida pelo analisador. Pode ser modificado a qualquer momento para versões mais recentes.

1. Para editar um analisador, modifique os parâmetros dele e clique em SALVAR.
2. Uma mensagem de confirmação é exibida se o analisador for criado.