Criar um analisador

Este guia explica como criar um analisador. Os analisadores realizam 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 Whistle. Ao criar um analisador, é necessário definir três elementos principais:

1. A classe de mensagem para o fluxo de mensagens a que um analisador se inscreve (entrada).
2. Versão do tipo do fluxo de registros proto que o analisador emite (saída).
3. O script 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 cada mensagem no fluxo da classe de mensagem 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 como modelar 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 de mensagens do Pub/Sub agora 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 evitar a perda de 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 para o fluxo de mensagens 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 compartilhado pelos registros proto emitidos por esse analisador.
• WHISTLE_SCRIPT: o script 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 será 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 da qual o analisador está se alimentando.
   • Type: tipo de destino que o analisador emite.
   • Type Version: versão do tipo de destino que o analisador emite.
   • Enabled: status do analisador (ativado ou desativado).
   • Actions: ações disponíveis para o analisador:
     • 'Visualizar/editar': abre o menu de edição de um determinado analisador.
     • 'Desativar/ativar: permite desativar um analisador ativado ou ativar um analisador desativado.
     • 'Testar 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 Visualizar/editar no ícone Ações. O menu lateral que expõe todos os parâmetros necessários para criar um novo analisador é mostrado no lado direito da tela:

   

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

   • Name: nome do analisador. Não será possível editar isso após a criação.
   • Message Class: nome da classe de mensagem da qual o analisador se alimenta. Não será possível modificar depois que o analisador for criado. Selecione a classe de mensagem na lista de classes de mensagens disponíveis.
   • Parser Code: arquivo Whistle que define o mapeamento associado ao analisador. Ele pode ser modificado a qualquer momento. A modificação do código Whistle não gera 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 será possível modificar depois que o analisador for criado. Selecione o tipo na lista de tipos 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 será mostrada se o novo analisador tiver sido criado.

Testar um analisador

É possível testar um analisador fornecendo um script Whistle e uma mensagem de entrada de amostra:

REST

POST /configuration/v1/parsers:test

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

Substitua:

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

Console

É possível 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 será aberta:

   

2. Forneça uma mensagem JSON de amostra 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á mostrada na caixa Resultado.
• Se a transformação não for bem-sucedida, uma mensagem de erro será mostrada com a causa provável do erro.

1. Use um arquivo JSON válido como mensagem de teste que tenha uma estrutura que possa ser processada pelo arquivo Whistle do analisador. Por exemplo, este é um exemplo de 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 compartilhado pelos registros proto emitidos por esse analisador.
• WHISTLE_SCRIPT: script Whistle que define a transformação.

Console

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

   

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

   

• Name: nome do analisador. Não será possível editar isso após a criação.
• Message Class: nome da classe de mensagem da qual o analisador se alimenta. Não será possível modificar depois que o analisador for criado.
• Parser Code: arquivo Whistle que define o mapeamento associado ao analisador. Ele pode ser modificado a qualquer momento. A modificação do código Whistle não gera 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 será possível modificar depois que o analisador for 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 será mostrada se o analisador tiver sido criado.