Ingestão de dados usando regras AWS IoT Core - AWS IoT SiteWise

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Ingestão de dados usando regras AWS IoT Core

Você pode enviar dados AWS IoT SiteWise de AWS IoT coisas e outros AWS serviços usando regras em AWS IoT Core. As regras transformam as mensagens do MQTT e realizam ações para interagir com AWS os serviços. A ação da AWS IoT SiteWise regra encaminha os dados das mensagens para a BatchPutAssetPropertyValueoperação a partir da AWS IoT SiteWise API. Para obter mais informações, consulte Rules e a AWS IoT SiteWise ação no AWS IoT Developer Guide.

Você pode seguir um tutorial que mostra as etapas necessárias para configurar uma regra que ingere dados de AWS IoT coisas por meio das sombras de seus dispositivos. Para ter mais informações, consulte Ingestão de dados AWS IoT SiteWise de coisas AWS IoT.

Você também pode enviar dados AWS IoT SiteWise de outros AWS serviços. Para ter mais informações, consulte Interagir com outros serviços da AWS.

Concedendo AWS IoT o acesso necessário

Você usa funções do IAM para controlar os AWS recursos aos quais cada regra tem acesso. Antes de criar uma regra, você deve criar uma função do IAM com uma política que permita que a regra execute ações no AWS recurso necessário. AWS IoT assume essa função ao executar uma regra.

Se você criar a ação de regra no AWS IoT console, poderá escolher um ativo raiz para criar uma função que tenha acesso a uma hierarquia de ativos selecionada. Para obter mais informações sobre como definir manualmente uma função para uma regra, consulte Conceder AWS IoT o acesso necessário e Aprovar as permissões de função no Guia do AWS IoT desenvolvedor.

Para a ação da AWS IoT SiteWise regra, você deve definir uma função que permita iotsitewise:BatchPutAssetPropertyValue acesso às propriedades do ativo para as quais a regra envia dados. Para melhorar a segurança, você pode especificar um caminho AWS IoT SiteWise de hierarquia de ativos na Condition propriedade.

O exemplo de política de confiança a seguir concede acesso a um ativo específico e seus filhos.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iotsitewise:BatchPutAssetPropertyValue", "Resource": "*", "Condition": { "StringLike": { "iotsitewise:assetHierarchyPath": [ "/root node asset ID", "/root node asset ID/*" ] } } } ] }

É possível remover o Condition da política para conceder acesso a todos os ativos. O exemplo de política de confiança a seguir permite acesso a todos os seus ativos.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iotsitewise:BatchPutAssetPropertyValue", "Resource": "*" } ] }

Configurando a ação da AWS IoT SiteWise regra

A ação da AWS IoT SiteWise regra envia dados da mensagem MQTT que iniciou a regra para as propriedades do ativo em AWS IoT SiteWise. É possível fazer upload de várias entradas de dados em diferentes propriedades de ativos ao mesmo tempo, para que você possa enviar atualizações a todos os sensores de um dispositivo em uma mensagem. Também é possível fazer upload de vários pontos de dados de uma vez para cada entrada de dados.

nota

Quando você envia dados para AWS IoT SiteWise com a ação de regra, seus dados devem atender a todos os requisitos da BatchPutAssetPropertyValue operação. Por exemplo, seus dados não podem ter um time stamp com mais de 7 dias do horário Unix epoch atual. Para obter mais informações, consulte Ingerir dados com a API do AWS IoT SiteWise.

Para cada entrada de dados na ação de regra, você identifica uma propriedade de ativo e especifica o time stamp, a qualidade e o valor de cada ponto de dados para essa propriedade de ativo. A ação da regra espera strings para todos os parâmetros.

Para identificar uma propriedade de ativo em uma entrada, especifique um dos seguintes elementos:

  • O Asset ID (ID do ativo) (assetId) e o Property ID (ID da propriedade) (propertyId) da propriedade de ativo para a qual você está enviando dados. Você pode encontrar o ID do ativo e o ID da propriedade usando Console do AWS IoT SiteWise o. Se você souber o ID do ativo, poderá usar o AWS CLI to call DescribeAssetpara encontrar o ID da propriedade.

  • O Property alias (Alias da propriedade) (propertyAlias), que é um alias de fluxo de dados (por exemplo, /company/windfarm/3/turbine/7/temperature). Para usar esta opção, primeiro você deve definir o apelido da propriedade do seu ativo. Para saber como definir apelidos de propriedades, consulte Mapeamento de fluxos de dados industriais para propriedades de ativos.

Para o time stamp em cada entrada, é possível usar o time stamp relatado pelo seu equipamento ou o time stamp relatado pelo AWS IoT Core. O time stamp tem dois parâmetros:

  • Time in seconds (Tempo em segundos) (timeInSeconds) – o horário Unix epoch, em segundos, no qual o sensor ou equipamento reportou os dados.

  • Offset in nanos (Deslocamento em nanossegundos) (offsetInNanos) – (opcional) o deslocamento em nanossegundos do tempo em segundos.

Importante

Se seu time stamp for uma string, tiver uma parte decimal ou não estiver em segundos, AWS IoT SiteWise rejeitará a solicitação. Você deve converter o time stamp em segundos e o deslocamento em nanossegundos. Use os recursos do mecanismo de AWS IoT regras para converter o carimbo de data/hora. Para obter mais informações, consulte:

Também é possível usar modelos de substituição para vários parâmetros na ação para executar cálculos, invocar funções e extrair valores da carga de mensagem. Para obter mais informações, consulte Modelos de substituição no Guia do desenvolvedor do AWS IoT .

nota

Como uma expressão em um modelo de substituição é avaliado separadamente da instrução SELECT, não é possível usar um modelo de substituição para fazer referência a um alias criado usando uma cláusula AS. Você pode fazer referência somente às informações presentes na carga original, além das funções e dos operadores compatíveis.

Obter time stamps para dispositivos que não informam a hora exata

Se seu sensor ou equipamento não reportar dados de tempo precisos, você pode obter a hora atual da época do Unix a partir do mecanismo de AWS IoT regras com timestamp (). Essa função reporta o tempo em milissegundos, portanto, é necessário converter o valor para tempo em segundos e deslocamento em nanossegundos. Para fazer isso, use as seguintes conversões:

  • Para Time in seconds (Tempo em segundos) (timeInSeconds), use ${floor(timestamp() / 1E3)} para converter o tempo de milissegundos para segundos.

  • Para Offset in nanos (Deslocamento em nanossegundos) (offsetInNanos), use ${(timestamp() % 1E3) * 1E6} para calcular o deslocamento em nanossegundos do time stamp.

Conversão de time stamps em formato de string

Se seu sensor ou equipamento reportar dados de hora em formato de string (por exemplo, 2020-03-03T14:57:14.699Z), você pode usar time_to_epoch (String, String). Essa função insere o time stamp e o padrão de formato como parâmetros e gera o tempo em milissegundos. Em seguida, você deve converter o tempo para tempo em segundos e o deslocamento em nanossegundos. Para fazer isso, use as seguintes conversões:

  • Para Time in seconds (Tempo em segundos) (timeInSeconds), use ${floor(time_to_epoch("2020-03-03T14:57:14.699Z", "yyyy-MM-dd'T'HH:mm:ss'Z'") / 1E3)} para converter o string do time stamp de milissegundos para segundos.

  • Para Offset in nanos (Deslocamento em nanossegundos) (offsetInNanos), use ${(time_to_epoch("2020-03-03T14:57:14.699Z", "yyyy-MM-dd'T'HH:mm:ss'Z'") % 1E3) * 1E6} para calcular o deslocamento em nanossegundos do string do time stamp.

nota

A função time_to_epoch suporta sequências de time stamp com precisão de até milissegundos. Para converter cadeias de caracteres com precisão de microssegundos ou nanossegundos, você pode configurar uma AWS Lambda função que sua regra chama para converter o timestamp em valores numéricos. Para ter mais informações, consulte Convertendo strings de time stamp de precisão de nanossegundos.

Convertendo strings de time stamp de precisão de nanossegundos

Se o seu dispositivo enviar informações de time stamp no formato de string (por exemplo, 2020-03-03T14:57:14.699728491Z), use as etapas a seguir para configurar suaa ação da regra. Você pode criar uma AWS Lambda função que converta o timestamp de uma string em Time in seconds (timeInSeconds) e Offset em nanos (). offsetInNanos Assim, você pode usar aws_lambda(functionArn, inputJson) em seus parâmetros de ação da regra para invocar essa função do Lambda e usar a saída na sua regra.

nota

Esta seção contém instruções avançadas que presumem que você esteja familiarizado com como criar os recursos a seguir:

Para criar uma ação de AWS IoT SiteWise regra que analisa cadeias de caracteres de carimbo de data/hora
  1. Crie uma função do Lambda com as seguintes propriedades:

    • Nome da função – use um nome descritivo de função (por exemplo, ConvertNanosecondTimestampFromString).

    • Tempo de execução — Use um tempo de execução do Python 3, como o Python 3.11 (). python3.11

    • Permissões — Crie uma função com permissões básicas do Lambda () AWSLambdaBasicExecutionRole.

    • Camadas — Adicione a camada AWSSDKpandas-Python311 para usar a função Lambda. numpy

    • Código de função – use o código de função a seguir, que consome um argumento de string chamado timeInSeconds e emite na saída os valores timestamp e offsetInNanos para esse time stamp.

      import json import math import numpy # Converts a timestamp string into timeInSeconds and offsetInNanos in Unix epoch time. # The input timestamp string can have up to nanosecond precision. def lambda_handler(event, context): timestamp_str = event['timestamp'] # Parse the timestamp string as nanoseconds since Unix epoch. nanoseconds = numpy.datetime64(timestamp_str, 'ns').item() time_in_seconds = math.floor(nanoseconds / 1E9) # Slice to avoid precision issues. offset_in_nanos = int(str(nanoseconds)[-9:]) return { 'timeInSeconds': time_in_seconds, 'offsetInNanos': offset_in_nanos }

      Essa função Lambda insere cadeias de caracteres de timestamp no formato ISO 8601 usando datetime64 de. NumPy

      nota

      Se suas strings de time stamp não estiverem no formato ISO 8601, você poderá implementar uma solução com pandas que defina seu formato. Para obter mais informações, consulte pandas.to_datetime.

  2. Ao configurar a AWS IoT SiteWise ação para sua regra, use os seguintes modelos de substituição para Tempo em segundos (timeInSeconds) e Deslocamento em nanos (). offsetInNanos Esses modelos de substituição presumem que a carga de mensagem contém a string de time stamp em timestamp. A função aws_lambda consome uma estrutura JSON para seu segundo parâmetro, assim você pode modificar os modelos de substituição abaixo, se necessário.

    • Para Time in seconds (Tempo em segundos) (timeInSeconds), use o seguinte modelo de substituição.

      ${aws_lambda('arn:aws:lambda:region:account-id:function:ConvertNanosecondTimestampFromString', {'timestamp': timestamp}).timeInSeconds}
    • Para Offset in nanos (Deslocamento em nanos) (offsetInNanos), use o seguinte modelo de substituição.

      ${aws_lambda('arn:aws:lambda:region:account-id:function:ConvertNanosecondTimestampFromString', {'timestamp': timestamp}).offsetInNanos}

    Para cada parâmetro, substitua region e account-id por sua região e ID da AWS conta. Se você usou um nome diferente para sua função do Lambda, altere-o também.

  3. Conceda AWS IoT permissões para invocar sua função com a lambda:InvokeFunction permissão. Para obter mais informações, consulte aws_lambda(functionArn, inputJson).

  4. Teste sua regra (por exemplo, use o cliente de teste AWS IoT MQTT) e verifique se ela AWS IoT SiteWise recebe os dados que você envia.

    Se sua regra não funcionar como esperado, consulte Solução de problemas de uma ação de AWS IoT SiteWise regra.

nota

Esta solução invoca a função do Lambda duas vezes para cada string de time stamp. Você pode criar outra regra para reduzir o número de invocações de função do Lambda se sua regra manipular vários pontos de dados que têm o mesmo time stamp em cada carga.

Para fazer isso, crie uma regra com uma ação de publicar novamente que invoque o Lambda e publique a carga original com a string de time stamp convertida para timeInSeconds e offsetInNanos. Em seguida, crie uma regra com uma ação de AWS IoT SiteWise regra para consumir a carga convertida. Com essa abordagem, você reduz o número de vezes que a regra invoca o Lambda, mas aumenta o número de ações de AWS IoT regras executadas. Considere a definição de preço de cada serviço caso você aplique essa solução ao seu caso de uso.

Configurações de regra de exemplo

Esta seção contém exemplos de configurações de regras que você pode usar para criar uma regra com uma AWS IoT SiteWise ação.

exemplo O exemplo de ação de regra que usa aliases de propriedade como tópicos de mensagem

O exemplo a seguir cria uma regra com uma AWS IoT SiteWise ação que usa o tópico (por meio de topic ()) como alias da propriedade para identificar as propriedades do ativo. Você pode usar esse exemplo para definir uma regra para a ingestão de dados de tipo duplo em todas as turbinas eólicas localizadas em todos os parques eólicos. Este exemplo exige que você defina aliases de propriedade em todas as propriedades dos ativos da turbina. Você precisa definir uma segunda regra semelhante para ingerir dados de tipo inteiro.

aws iot create-topic-rule \ --rule-name SiteWiseWindFarmRule \ --topic-rule-payload file://sitewise-rule-payload.json

O exemplo de carga no sitewise-rule-payload.json contém o conteúdo a seguir.

{ "sql": "SELECT * FROM '/company/windfarm/+/turbine/+/+' WHERE type = 'double'", "description": "Sends data to the wind turbine asset property with the same alias as the topic", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [ { "iotSiteWise": { "putAssetPropertyValueEntries": [ { "propertyAlias": "${topic()}", "propertyValues": [ { "timestamp": { "timeInSeconds": "${timeInSeconds}" }, "value": { "doubleValue": "${value}" } } ] } ], "roleArn": "arn:aws:iam::account-id:role/MySiteWiseActionRole" } } ] }

Com essa ação de regra, é possível enviar a mensagem ao alias de propriedade de uma turbina eólica (por exemplo, /company/windfarm/3/turbine/7/temperature) como um tópico para ingerir dados.

{ "type": "double", "value": "38.3", "timeInSeconds": "1581368533" }
exemplo Exemplo de ação de regra que usa time stamp() para determinar o tempo

O exemplo a seguir cria uma regra com uma AWS IoT SiteWise ação que identifica uma propriedade do ativo por IDs e usa timestamp () para determinar a hora atual.

aws iot create-topic-rule \ --rule-name SiteWiseAssetPropertyRule \ --topic-rule-payload file://sitewise-rule-payload.json

O exemplo de carga no sitewise-rule-payload.json contém o conteúdo a seguir.

{ "sql": "SELECT * FROM 'my/asset/property/topic'", "description": "Sends device data to an asset property", "ruleDisabled": false, "awsIotSqlVersion": "2016-03-23", "actions": [ { "iotSiteWise": { "putAssetPropertyValueEntries": [ { "assetId": "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE", "propertyId": "a1b2c3d4-5678-90ab-cdef-33333EXAMPLE", "propertyValues": [ { "timestamp": { "timeInSeconds": "${floor(timestamp() / 1E3)}", "offsetInNanos": "${(timestamp() % 1E3) * 1E6}" }, "value": { "doubleValue": "${value}" } } ] } ], "roleArn": "arn:aws:iam::account-id:role/MySiteWiseActionRole" } } ] }

Com essa ação de regra, é possível enviar a mensagem a seguir ao my/asset/property/topic para ingerir dados.

{ "type": "double", "value": "38.3" }

Reduzir custos com a ingestão básica

AWS IoT Core fornece um recurso chamado Basic Ingest, que você pode usar para enviar dados AWS IoT Core sem incorrer em custos de AWS IoT mensagens. A Ingestão básica otimiza fluxo de dados para cargas de ingestão de dados de volume alto removendo o agente de mensagem de publicação/assinatura do caminho de ingestão. É possível usar a Ingestão básica se souber para quais regras as mensagens devem ser roteadas.

Para usar a Ingestão básica, envie mensagens diretamente a uma regra específica usando um tópico especial, $aws/rules/rule-name. Por exemplo, para enviar uma mensagem a uma regra chamada SiteWiseWindFarmRule, envie uma mensagem ao tópico$aws/rules/SiteWiseWindFarmRule.

Se a ação de regra usa modelos de substituição que contêm topic(Decimal), é possível transmitir o tópico original ao fim do tópico especial de Ingestão básica, como $aws/rules/rule-name/original-topic. Por exemplo, para usar a Ingestão básica com o exemplo de alias de propriedade do parque de energia eólica da seção anterior, é possível enviar mensagens ao tópico a seguir.

$aws/rules/SiteWiseWindFarmRule//company/windfarm/3/turbine/7/temperature
nota

O exemplo acima inclui uma segunda barra (//) porque AWS IoT remove o prefixo Basic Ingest ($aws/rules/rule-name/) do tópico que está visível para a ação da regra. Neste exemplo, a regra recebe o tópico /company/windfarm/3/turbine/7/temperature.

Para obter mais informações, consulte Reducing messaging costs with basic ingest no AWS IoT Developer Guide.

Solução de problemas da ação da AWS IoT SiteWise regra

Para solucionar problemas de sua ação de AWS IoT SiteWise regra em AWS IoT Core, você pode configurar CloudWatch registros ou configurar uma ação de erro de republicação para sua regra. Para ter mais informações, consulte Solução de problemas de uma ação de AWS IoT SiteWise regra.