IoT Platform:Configurar uma regra de encaminhamento de dados

Procedimento

1. Faça login no IoT Platform console.

2. Na página Overview, localize a instância que deseja gerenciar e clique em ID ou no nome da instância.

3. No painel de navegação à esquerda, escolha Message Forwarding > Data Forwarding.

4. Na página Data Forwarding, clique em Create Rule.

   Importante

   Se a página Data Forwarding da versão mais recente for exibida, clique em Back to Previous Version no canto superior direito da página. Quando a página Data Forwarding da versão anterior aparecer, clique em Create Rule.

5. Insira os parâmetros e clique em Confirm.

   Parameter	Description
   Rule Name	Nome da regra de encaminhamento de dados. O nome deve ter de 1 a 30 caracteres e pode conter letras, dígitos, sublinhados (_) e hifens (-).
   Data format	Formato dos dados que você deseja processar com a regra. Valores válidos: JSON e Binary. Nota Como o encaminhamento de dados processa informações com base em tópicos, o formato dos dados deve ser consistente com o formato definido para o tópico. Se você selecionar Binary, a regra não poderá ser usada para processar mensagens de tópicos de comunicação básica ou tópicos de comunicação da Thing Specification Language (TSL). A regra também não poderá ser usada para encaminhar dados para o Tablestore (OTS) ou ApsaraDB RDS.
   Rule Description	Descrição da regra.

6. Após a criação da regra, a página rule details é exibida. Escreva uma instrução SQL para processar mensagens, especifique um destino de encaminhamento de dados e, em seguida, defina um destino para o qual as mensagens de erro serão encaminhadas.

   1. Clique em Write SQL para inserir uma instrução SQL que processe os campos da mensagem.

      Para obter mais informações sobre como escrever instruções SQL, consulte SQL statements e Functions.

      Parameter	Description
      Rule Query Expression	Instrução SQL. A instrução SQL é gerada automaticamente com base nos valores especificados nos parâmetros Field, Topic e Conditions (Optional).
      Field	Campo da mensagem a ser processado. Este parâmetro segue a palavra-chave SELECT na instrução SQL. Por exemplo, se você inserir deviceName() as deviceName, o campo deviceName na mensagem será selecionado. Para obter mais informações sobre as funções que podem ser usadas no campo, consulte Functions. Nota Os dados dos tópicos de comunicação básica e dos tópicos de comunicação TSL estão no formato Alink JSON. Antes de os dados serem encaminhados para o mecanismo de regras, eles são analisados com base no modelo TSL correspondente. Para obter mais informações sobre a análise de dados, consulte Data forwarding procedure. Para obter mais informações sobre os formatos dos dados analisados, consulte Data formats. Ao escrever uma instrução SQL, especifique os campos com base no formato dos dados analisados.
      Topic	Tópico de origem da mensagem a ser processada. Este parâmetro segue a palavra-chave FROM na instrução SQL. Para obter mais informações sobre os tópicos opcionais, consulte a tabela Topics a seguir. Importante Se você definir o parâmetro Data Type da regra como Binary, defina este parâmetro como Custom.
      Condition	Condição de acionamento da regra. Este parâmetro segue a palavra-chave WHERE na instrução SQL.

      Tabela 1. Descrições dos tópicos

      Topic	Description	References
      Custom	Um tópico para encaminhamento de mensagens em um formato de dados personalizado segue o mesmo formato de um tópico personalizado: /${productKey}/${deviceName}/user/${TopicShortName}. ${TopicShortName} especifica uma categoria de tópico personalizado, que é o sufixo do tópico personalizado. O valor pode conter caracteres curinga, incluindo sinais de adição (+) e cerquilhas (#). Todos os equipamentos (+): indica todos os dispositivos do product especificado. /user/#: Todos os tópicos personalizados para um dispositivo especificado.	Use custom topics for communication
      Device Status Change Notification	Tópico usado para encaminhar notificações quando o status de um dispositivo muda entre online e offline. Formato: /as/mqtt/status/${productKey}/${deviceName}.	Device online and offline status
      TSL Data Reporting	Inclui: Um dispositivo relata dados de propriedade para o seguinte tópico: /${productKey}/${deviceName}/thing/event/property/post. Dados de evento relatados por um dispositivo são encaminhados para o tópico /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post. O tópico para encaminhamento de dados de propriedade em lote de dispositivos é /${productKey}/${deviceName}/thing/property/batch/post. O tópico para encaminhamento de dados de evento em lote de dispositivos é /${productKey}/${deviceName}/thing/event/batch/post. Um dispositivo envia mensagens de resposta para comandos da nuvem para o seguinte tópico: /${productKey}/${deviceName}/thing/downlink/reply/message.	Submit device properties Submit device events Submit multiple device properties at a time Submit multiple device events at a time Device Downlink Instruction Status
      	Os tópicos a seguir são usados para enviar dados brutos do dispositivo: /sys/${productKey}/${deviceName}/thing/event/property/post: Este tópico é usado para enviar propriedades do dispositivo. /sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post e /sys/${productKey}/${deviceName}/thing/event/${tsl.functionBlockId}:{tsl.event.identifier}/post: Estes tópicos são usados para enviar eventos do dispositivo. /sys/${productKey}/${deviceName}/thing/event/property/batch/post: Este tópico é usado para enviar propriedades e eventos do dispositivo em lotes.	Submit device properties Submit device events Submit multiple device properties and events at a time
      Device Changes Throughout Lifecycle	Tópico usado para encaminhar mensagens quando um dispositivo é criado, excluído, desativado ou ativado. Formato: /${productKey}/${deviceName}/thing/lifecycle.	Changes to the device lifecycle
      Sub-Device Data Report Detected by Gateway	O tópico /${productKey}/${deviceName}/thing/list/found é usado por dispositivos gateway para relatar informações sobre subdispositivos descobertos ao IoT Platform.	Gateway discovery of sub-devices
      Device Topological Relation Changes	Tópico usado para encaminhar notificações quando relações topológicas entre subdispositivos e o gateway são criadas ou excluídas. Este tópico é específico para gateways. Formato: /${productKey}/${deviceName}/thing/topo/lifecycle.	Device Topological Relation Changes
      	Um dispositivo usa o tópico /sys/${productKey}/${deviceName}/thing/topo/change para relatar dados brutos.	Notify gateways of changes of topological relationships
      Device tag change	O tópico para encaminhamento de atualizações de tag de dispositivo é /${productKey}/${deviceName}/thing/deviceinfo/update.	Changes to device tags
      	Um dispositivo usa o seguinte tópico para relatar dados brutos: /sys/${productKey}/${deviceName}/thing/deviceinfo/update.	Submit tags
      TSL Historical Data Reporting	Inclui: /${productKey}/${deviceName}/thing/event/property/history/post: Este tópico é usado para encaminhar propriedades históricas. /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/history/post: Este tópico é usado para encaminhar eventos históricos.	Submit historical properties Submit historical events
      	/sys/${productKey}/${deviceName}/thing/event/property/history/post: Este tópico é usado para enviar dados históricos da TSL.	How to report historical data for a Thing Specification Language model
      Device Status Notification for OTA Updates	Inclui: O tópico para encaminhamento do resultado da atualização OTA de um dispositivo é /${productKey}/${deviceName}/ota/upgrade. Um dispositivo relata o progresso da atualização OTA para o tópico /${productKey}/${deviceName}/ota/progress/post.	Status notifications for OTA updates Notifications for OTA update progress
      	Um dispositivo relata seu progresso de atualização para o seguinte tópico: /ota/device/progress/${productKey}/${deviceName}.	Reporting device upgrade progress
      Submit a module version number	Tópico para relatar uma versão atualizada do módulo Over-the-Air (OTA): /${productKey}/${deviceName}/ota/version/post.	Notice of OTA Module Version Changes
      	Um dispositivo usa o seguinte tópico para relatar sua versão do módulo OTA: /ota/device/inform/${productKey}/${deviceName}.	Device reports the OTA module version
      Batch status notification	O IoT Platform publica notificações de mudança de status para um lote de atualização OTA no seguinte tópico: /${productKey}/${packageId}/${jobId}/ota/job/status.	Status Notifications for OTA Update Batches
      Job Event	Inclui os seguintes tópicos: Notificações de status de job de dispositivo: /sys/uid/${uid}/job/${jobId}/lifecycle. Notificações de status de job de migração de instância: /sys/uid/${uid}/distribution/${jobId}/lifecycle. Nota O nome do product a ser migrado é usado como o nome do job de migração de instância.	Device job status notifications Instance migration job status notifications

   2. Na seção Twin Node Attribute Change, clique em Forward Data para especificar um destino de encaminhamento de dados. Para obter mais informações sobre como configurar o recurso de encaminhamento de dados, consulte os tópicos relacionados no diretório Data forwarding examples.

      Nota

      É possível criar até 10 operações de encaminhamento de dados para cada regra.

      Quando o encaminhamento de dados falha devido a anomalias no product de nuvem de destino selecionado:

      • Ao encaminhar dados para services de nuvem, como ApsaraMQ for RocketMQ, ApsaraDB RDS e ApsaraDB for Lindorm, o acesso aos services pode falhar devido a alterações de recursos. Nesse caso, o IoT Platform interrompe o encaminhamento de dados e altera o status da regra relacionada para Add Operation. Você deve especificar um novo destino para o encaminhamento de dados.

      • Para outras exceções, o IoT Platform tenta novamente três vezes com intervalos de 1 segundo, 3 segundos e 10 segundos. A política de nova tentativa pode variar conforme o cenário. Se todas as tentativas falharem, a mensagem será descartada. Caso seu negócio tenha altos requisitos de confiabilidade de mensagens, adicione uma operação de erro e encaminhe as mensagens de erro para outros services de nuvem.

   3. Na seção Forward Error Data, clique em Abnormal. Em seguida, configure os parâmetros para encaminhar mensagens de erro ao destino especificado após a falha de todas as novas tentativas.Add Error Operation

      Importante

      • Apenas uma operação de tratamento de erros pode ser adicionada por regra.

      • Uma operação normal e uma operação de tratamento de erros não podem encaminhar mensagens para o mesmo destino. Por exemplo, dados normais e dados de erro não podem ser encaminhados para o OTS simultaneamente.

      • Se o encaminhamento de uma mensagem de erro falhar, nenhuma nova tentativa será realizada.

      • Mensagens de erro são geradas apenas se o mecanismo de regras falhar ao encaminhar dados devido a problemas em outros services de nuvem.

      Se uma mensagem falhar ao ser encaminhada para um service de nuvem, o IoT Platform tentará reencaminhá-la. Se a nova tentativa falhar, uma mensagem de erro será encaminhada com base na operação de erro especificada para o encaminhamento de dados.

      Formato da mensagem de erro:

      {
         "ruleName":"",
         "topic":"",
         "productKey":"",
         "deviceName":"",
         "messageId":"",
         "base64OriginalPayload":"",
         "failures":[
          {
           "actionType":"OTS",
           "actionRegion":"cn-shanghai",
           "actionResource":"table1",
           "errorMessage":""
          },
          {
           "actionType":"RDS",
           "actionRegion":"cn-shanghai",
           "actionResource":"instance1/table1",
           "errorMessage":""
          }
         ]
      }

      A tabela a seguir descreve os parâmetros das mensagens de erro.

      Parameter	Description
      ruleName	Nome da regra.
      topic	Tópico de origem da mensagem.
      productKey	ProductKey do product.
      deviceName	DeviceName do dispositivo.
      messageId	ID da mensagem enviada pelo IoT Platform.
      base64OriginalPayload	Dados brutos codificados em Base64.
      failures	Detalhes do erro. Vários erros podem ocorrer.
      actionType	Tipo da operação com falha.
      actionRegion	Região onde o erro ocorreu.
      actionResource	Recurso alvo da operação com falha.
      errorMessage	Mensagem de erro.

7. Acesse a página . Localize a regra configurada e clique em Data Forwarding na coluna Actions. Após a ativação da regra, os dados serão encaminhados conforme definido nela.

   Você também pode executar as seguintes ações:

   Operation	Description
   View	Na página Start, atualize as configurações de uma regra. Por exemplo, modifique ou exclua o tópico de origem de dados ou o destino de encaminhamento de dados.
   Delete	Exclui a regra. Importante Regras em execução não podem ser excluídas.
   Stop	Interrompe o encaminhamento de dados pela regra.

   Aviso

   Se um ou mais de seus aplicativos precisarem usar os dados do dispositivo encaminhados por meio de uma regra, mas a regra for excluída ou desativada, ou se o destino de encaminhamento de dados da regra for excluído, seus services poderão ficar indisponíveis. Como resultado, seus negócios podem ser interrompidos. Prossiga com cautela.

Próximos passos

Na página Data Forwarding Rules, visualize o status da regra, verifique se um destino de encaminhamento de dados está configurado e confirme se os dados estão sendo encaminhados para o destino conforme esperado.