Conector de análises da IoT - AWS IoT Greengrass

AWS IoT Greengrass Version 1 entrou na fase de vida útil prolongada em 30 de junho de 2023. Para obter mais informações, consulte política de manutenção do AWS IoT Greengrass V1. Após essa data, AWS IoT Greengrass V1 não lançaremos atualizações que forneçam recursos, aprimoramentos, correções de erros ou patches de segurança. Os dispositivos que funcionam AWS IoT Greengrass V1 não serão interrompidos e continuarão operando e se conectando à nuvem. É altamente recomendável que você migre para AWS IoT Greengrass Version 2, o que adiciona novos recursos significativos e suporte para plataformas adicionais.

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á.

Conector de análises da IoT

Atenção

Esse conector passou para a fase de vida útil estendida e AWS IoT Greengrass não lançará atualizações que forneçam atributos, aprimoramentos para atributos existentes, patches de segurança ou correções de erros. Para obter mais informações, consulte Política de manutenção do AWS IoT Greengrass Version 1.

O conector de análises da IoT envia dados de dispositivos locais para o AWS IoT Analytics. É possível usar o conector como um hub central para coletar dados de sensores no dispositivo de núcleo do Greengrass e de dispositivos cliente do Greengrass. O conector envia os dados para canais do AWS IoT Analytics na região e na conta atuais da Conta da AWS. Ele pode enviar dados para um canal de destino padrão e para canais especificados de maneira dinâmica.

nota

O AWS IoT Analytics é um serviço totalmente gerenciado que permite coletar, armazenar, processar e consultar dados da IoT. No AWS IoT Analytics, os dados podem ser processados e analisados mais detalhadamente. Por exemplo, ele pode ser usado para treinar modelos de ML para monitorar a integridade da máquina ou para testar novas estratégias de modelagem. Para obter mais informações, consulte O que é o AWS IoT Analytics? no Guia do usuário do AWS IoT Analytics.

O conector aceita dados formatados e não formatados em tópicos MQTT de entrada. Ele oferece suporte a dois tópicos predefinidos nos quais o canal de destino é especificado em linha. Ele também pode receber mensagens em tópicos definidos pelo cliente que são configurados em inscrições. Isso pode ser usado para rotear mensagens de dispositivos cliente que publicam em tópicos fixos ou para lidar com dados não estruturados ou dependentes da pilha de dispositivos com recursos restritos.

Esse conector usa a API BatchPutMessage para enviar dados (como uma string JSON ou codificada em base64) ao canal de destino. O conector pode processar dados brutos em um formato que está em conformidade com os requisitos da API. O conector armazena em buffer mensagens de entrada em filas por canal e processa os lotes de maneira assíncrona. Ele fornece parâmetros que permitem controlar o comportamento de filas e lotes para restringir o consumo de memória. Por exemplo, você pode configurar o tamanho máximo da fila, o intervalo de lote, o tamanho da memória e o número de canais ativos.

Esse conector tem as seguintes versões.

Versão

ARN

4

arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/4

3

arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/3

2

arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/2

1

arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/1

Para obter informações sobre alterações de versão, consulte o Changelog.

Requisitos

Esse conector tem os seguintes requisitos:

Version 3 - 4
  • Software de núcleo do AWS IoT Greengrass v1.9.3 ou versão posterior.

  • Python, versão 3.7 ou 3.8, instalado no dispositivo de núcleo e adicionado à variável de ambiente PATH.

    nota

    Para usar o Python 3.8, execute o comando a seguir para criar um symblink da pasta de instalação padrão do Python 3.7 para os binários instalados do Python 3.8.

    sudo ln -s path-to-python-3.8/python3.8 /usr/bin/python3.7

    Isso configura seu dispositivo para atender ao requisito Python para AWS IoT Greengrass.

  • Esse conector só pode ser usado em regiões da Amazon Web Services onde o AWS IoT Greengrass e o AWS IoT Analytics são compatíveis.

  • Todas as entidades e fluxos de trabalho do AWS IoT Analytics relacionados são criados e configurados. As entidades incluem canais, pipeline, datastores e conjuntos de dados. Para obter mais informações, consulte os procedimentos da AWS CLI ou do console no Guia do usuário do AWS IoT Analytics.

    nota

    O destino de canais do AWS IoT Analytics devem usar a mesma conta e estar na mesma Região da AWS desse conector.

  • A função de grupo do Greengrass configurada para permitir a ação iotanalytics:BatchPutMessage nos canais de destino, conforme mostrado no exemplo de política do IAM a seguir. Os canais devem estar na Conta da AWS e na região atuais.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1528133056761", "Action": [ "iotanalytics:BatchPutMessage" ], "Effect": "Allow", "Resource": [ "arn:aws:iotanalytics:region:account-id:channel/channel_1_name", "arn:aws:iotanalytics:region:account-id:channel/channel_2_name" ] } ] }

    Para o requisito de função de grupo, você deve configurar a função para conceder as permissões necessárias e certificar-se de que a função tenha sido adicionada ao grupo. Para ter mais informações, consulte Gerenciar a função de grupo do Greengrass (console) ou Gerenciar a função de grupo do Greengrass (CLI).

Versions 1 - 2
  • Software AWS IoT Greengrass Core v1.7 ou posterior.

  • Python versão 2.7 instalado no dispositivo de núcleo e adicionado à variável de ambiente PATH.

  • Esse conector só pode ser usado em regiões da Amazon Web Services onde o AWS IoT Greengrass e o AWS IoT Analytics são compatíveis.

  • Todas as entidades e fluxos de trabalho do AWS IoT Analytics relacionados são criados e configurados. As entidades incluem canais, pipeline, datastores e conjuntos de dados. Para obter mais informações, consulte os procedimentos da AWS CLI ou do console no Guia do usuário do AWS IoT Analytics.

    nota

    O destino de canais do AWS IoT Analytics devem usar a mesma conta e estar na mesma Região da AWS desse conector.

  • A função de grupo do Greengrass configurada para permitir a ação iotanalytics:BatchPutMessage nos canais de destino, conforme mostrado no exemplo de política do IAM a seguir. Os canais devem estar na Conta da AWS e na região atuais.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1528133056761", "Action": [ "iotanalytics:BatchPutMessage" ], "Effect": "Allow", "Resource": [ "arn:aws:iotanalytics:region:account-id:channel/channel_1_name", "arn:aws:iotanalytics:region:account-id:channel/channel_2_name" ] } ] }

    Para o requisito de função de grupo, você deve configurar a função para conceder as permissões necessárias e certificar-se de que a função tenha sido adicionada ao grupo. Para ter mais informações, consulte Gerenciar a função de grupo do Greengrass (console) ou Gerenciar a função de grupo do Greengrass (CLI).

Parâmetros

MemorySize

A quantidade de memória (em KB) a ser alocada para esse conector.

Nome de exibição no console do AWS IoT: Tamanho da memória

Obrigatório: true

Digite: string

Padrão válido: ^[0-9]+$

PublishRegion

A Região da AWS na qual os canais do AWS IoT Analytics são criados. Use a mesma região do conector.

nota

Ela também deve corresponder à região dos canais especificados na função de grupo.

Nome de exibição no console AWS IoT: região de publicação

Obrigatório: false

Digite: string

Padrão válido: ^$|([a-z]{2}-[a-z]+-\\d{1})

PublishInterval

O intervalo (em segundos) para a publicação de um lote de dados recebidos no AWS IoT Analytics.

Nome de exibição no console do AWS IoT: Intervalo de publicação

Obrigatório: false

Digite: string

Valor padrão: 1

Padrão válido: $|^[0-9]+$

IotAnalyticsMaxActiveChannels

O número máximo de canais do AWS IoT Analytics que o conector observa ativamente. Esse valor deve ser maior que 0 e pelo menos igual ao número de canais nos quais você espera que o conector publique em determinado momento.

Você pode usar esse parâmetro para restringir o consumo de memória limitando o número total de filas que o conector pode gerenciar em determinado momento. Uma fila é excluída quando todas as mensagens dela são enviadas.

Nome de exibição no console AWS IoT: Número máximo de canais ativos

Obrigatório: false

Digite: string

Valor padrão: 50

Padrão válido: ^$|^[1-9][0-9]*$

IotAnalyticsQueueDropBehavior

O comportamento para a remoção de mensagens da fila de um canal quando ela está cheia.

Nome de exibição no console AWS IoT: Comportamento de remoção da fila

Obrigatório: false

Digite: string

Valores válidos: DROP_NEWEST ou DROP_OLDEST

Valor padrão: DROP_NEWEST

Padrão válido: ^DROP_NEWEST$|^DROP_OLDEST$

IotAnalyticsQueueSizePerChannel

O número máximo de mensagens a serem armazenadas na memória (por canal) antes que elas sejam enviadas ou removidas. Esse valor deve ser maior que 0.

Nome de exibição no console AWS IoT: Tamanho máximo da fila por canal

Obrigatório: false

Digite: string

Valor padrão: 2048

Padrão válido: ^$|^[1-9][0-9]*$

IotAnalyticsBatchSizePerChannel

O número máximo de mensagens a serem enviadas para um canal do AWS IoT Analytics em uma solicitação de lote. Esse valor deve ser maior que 0.

Nome de exibição no console AWS IoT: Número máximo de mensagem a agrupar por canal

Obrigatório: false

Digite: string

Valor padrão: 5

Padrão válido: ^$|^[1-9][0-9]*$

IotAnalyticsDefaultChannelName

O nome do canal do AWS IoT Analytics que esse conector usa para mensagens que são enviadas a um tópico de entrada definido pelo cliente.

Nome de exibição no console AWS IoT: Nome do canal padrão

Obrigatório: false

Digite: string

Padrão válido: ^[a-zA-Z0-9_]$

IsolationMode

O modo de conteinerização para este conector. O padrão é GreengrassContainer, o que significa que o conector é executado em um ambiente de tempo de execução isolado dentro do contêiner do AWS IoT Greengrass.

nota

A configuração padrão de conteinerização para o grupo não se aplica aos conectores.

Nome de exibição no console do AWS IoT: Modo de isolamento de contêiner

Obrigatório: false

Digite: string

Valores válidos: GreengrassContainer ou NoContainer

Padrão válido: ^NoContainer$|^GreengrassContainer$

Exemplo de criação de conector (AWS CLI)

O seguinte comando da CLI cria um ConnectorDefinition com uma versão inicial que contém o conector de análises da IoT.

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyIoTAnalyticsApplication", "ConnectorArn": "arn:aws:greengrass:region::/connectors/IoTAnalytics/versions/3", "Parameters": { "MemorySize": "65535", "PublishRegion": "us-west-1", "PublishInterval": "2", "IotAnalyticsMaxActiveChannels": "25", "IotAnalyticsQueueDropBehavior": "DROP_OLDEST", "IotAnalyticsQueueSizePerChannel": "1028", "IotAnalyticsBatchSizePerChannel": "5", "IotAnalyticsDefaultChannelName": "my_channel" } } ] }'
nota

A função do Lambda nesse conector tem um ciclo de vida longo.

No console do AWS IoT Greengrass, você pode adicionar um conector na página Conectores do grupo. Para obter mais informações, consulte Conceitos básicos de conectores do Greengrass (console).

Dados de entrada

Esse conector aceita dados em tópicos MQTT predefinidos e definidos pelo cliente. Os editores podem ser dispositivos cliente do Greengrass, funções do Lambda ou outros conectores.

Tópicos predefinidos

O conector oferece suporte aos dois tópicos MQTT estruturados mostrados a seguir que permitem que os editores especifiquem o nome do canal em linha.

  • Uma mensagem formatada no tópico iotanalytics/channels/+/messages/put. Os dados de IoT nessas mensagens de entrada devem ser formatados como uma string JSON ou codificada em base64.

  • Uma mensagem não formatada no tópico iotanalytics/channels/+/messages/binary/put. As mensagens de entrada recebidas nesse tópico são tratadas como dados binários e podem conter qualquer tipo de dados.

    Para publicar em tópicos predefinidos, substitua o caractere curinga + pelo nome do canal. Por exemplo:

    iotanalytics/channels/my_channel/messages/put
Tópicos definidos pelo cliente

O conector oferece suporte à sintaxe do tópico #, que permite aceitar mensagens de entrada em qualquer tópico MQTT configurado em uma assinatura. Recomendamos que você especifique um caminho de tópico em vez de usar somente o caractere curinga # em suas assinaturas. Essas mensagens são enviadas para o canal padrão especificado para o conector.

As mensagens de entrada em tópicos definidos pelo cliente são tradadas como dados binários. Elas podem usar qualquer formato de mensagem e podem ter qualquer tipo de dados. É possível usar tópicos definidos pelo cliente para rotear mensagens de dispositivos que publicam em tópicos fixos. Também é possível usá-los para aceitar dados de entrada de dispositivos cliente que não podem processar os dados em uma mensagem formatada para enviar ao conector.

Para obter mais informações sobre inscrições e tópicos MQTT, consulte Entradas e saídas.

A função de grupo deve permitir a ação iotanalytics:BatchPutMessage em todos os canais de destino. Para obter mais informações, consulte Requisitos.

Filtro de tópico: iotanalytics/channels/+/messages/put

Use esse tópico para enviar mensagens formatadas ao conector e especificar de maneira dinâmica um canal de destino. Esse tópico também permite especificar um ID que é retornado na saída da resposta. O conector verifica se os IDs são exclusivos para cada mensagem na solicitação BatchPutMessage de saída que ele envia ao AWS IoT Analytics. A mensagem que tiver um ID duplicado será removida.

Os dados de entrada enviados a esse tópico devem usar o formato de mensagem a seguir.

Propriedades de mensagens
request

Os dados a serem enviados ao canal especificado.

Obrigatório: true

Tipo: object que inclui as seguintes propriedades:

message

Os dados do dispositivo ou do sensor, como uma string codificada em JSON ou em base64.

Obrigatório: true

Digite: string

id

Um ID arbitrário para a solicitação. Essa propriedade é usada para mapear a solicitação de entrada para uma resposta de saída. Quando especificada, a propriedade id no objeto de resposta é definida para esse valor. Se você omitir essa propriedade, o conector gerará um ID.

Obrigatório: false

Digite: string

Padrão válido: .*

Exemplo de entrada
{ "request": { "message" : "{\"temp\":23.33}" }, "id" : "req123" }
Filtro de tópico: iotanalytics/channels/+/messages/binary/put

Use esse tópico para enviar mensagens não formatadas ao conector e especificar de maneira dinâmica um canal de destino.

Os dados do conector não analisam as mensagens de entrada recebidas nesse tópico. Eles são tratados como dados binários. Antes de enviar as mensagens ao AWS IoT Analytics, o conector as codifica e as formata para que atendam aos requisitos da API BatchPutMessage:

  • O conector codifica em base64 os dados brutos e inclui a carga codificada em uma solicitação BatchPutMessage de saída.

  • O conector gera e atribui um ID para cada mensagem de entrada.

    nota

    A saída de resposta do conector não inclui uma correlação de ID para essas mensagens de entrada.

Propriedades de mensagens

Nenhum.

Filtro de tópico: #

Use esse tópico para enviar qualquer formato de mensagem ao canal padrão. Isso é especialmente útil quando os dispositivos cliente publicam em tópicos fixos ou quando você deseja enviar dados para o canal padrão a partir de dispositivos cliente que não podem processar os dados no formato de mensagem compatível do conector.

Defina a sintaxe do tópico na assinatura criada para conectar esse conector à fonte de dados. Recomendamos que você especifique um caminho de tópico em vez de usar somente o caractere curinga # em suas assinaturas.

Os dados do conector não analisam as mensagens que são publicadas nesse tópico de entrada. Todas as mensagens são tratadas como dados binários. Antes de enviar as mensagens ao AWS IoT Analytics, o conector as codifica e as formata para que atendam aos requisitos da API BatchPutMessage:

  • O conector codifica em base64 os dados brutos e inclui a carga codificada em uma solicitação BatchPutMessage de saída.

  • O conector gera e atribui um ID para cada mensagem de entrada.

    nota

    A saída de resposta do conector não inclui uma correlação de ID para essas mensagens de entrada.

Propriedades de mensagens

Nenhum.

Dados de saída

O conector publica informações de status como dados de saída em um tópico MQTT. Essas informações contêm a resposta retornada pelo AWS IoT Analytics para cada mensagem de entrada que recebe e envia ao AWS IoT Analytics.

Filtro de tópico na assinatura

iotanalytics/messages/put/status

Exemplo de resultado: sucesso
{ "response" : { "status" : "success" }, "id" : "req123" }
Exemplo de resultado: falha
{ "response" : { "status" : "fail", "error" : "ResourceNotFoundException", "error_message" : "A resource with the specified name could not be found." }, "id" : "req123" }
nota

Se o conector detectar um erro que pode ser repetido (por exemplo, erros de conexão), ele tentará publicar novamente no próximo lote. O recuo exponencial é processado pelo SDK da AWS. As solicitações com erros que podem ser tentadas novamente são adicionadas de volta à fila do canal para publicação posterior de acordo com o parâmetro IotAnalyticsQueueDropBehavior.

Exemplo de uso

Use as seguintes etapas de alto nível para configurar um exemplo de função do Lambda Python 3.7 que pode ser usado para testar o conector.

nota
  1. Certifique-se de cumprir os requisitos para o conector.

    Para o requisito de função de grupo, você deve configurar a função para conceder as permissões necessárias e certificar-se de que a função tenha sido adicionada ao grupo. Para ter mais informações, consulte Gerenciar a função de grupo do Greengrass (console) ou Gerenciar a função de grupo do Greengrass (CLI).

  2. Crie e publique uma função do Lambda que envie dados de entrada para o conector.

    Salve o código de exemplo como arquivo PY. Baixe e descompacte o SDK do AWS IoT Greengrass Core para Python. Crie então um pacote zip que contenha o arquivo PY e a pasta greengrasssdk no nível raiz. Este pacote zip é o pacote de implantação que você transfere por upload para o AWS Lambda.

    Depois de criar a função do Lambda Python 3.7, publique uma versão de função e crie um alias.

  3. Configure o grupo do Greengrass.

    1. Adicione a função do Lambda pelo seu alias (recomendado). Configure o ciclo de vida do Lambda como de longa duração (ou "Pinned": true na CLI).

    2. Adicione o conector e configure seus parâmetros.

    3. Adicione assinaturas que permitam que o conector receba dados de entrada e envie dados de saída em filtros de tópico compatíveis.

      • Defina a função do Lambda como origem, o conector como destino e use um filtro de tópico de entrada compatível.

      • Defina o conector como origem, o AWS IoT Core como destino, e use um filtro de tópico de saída compatível. Use essa assinatura para exibir mensagens de status no console do AWS IoT.

  4. Implante o grupo.

  5. No console do AWS IoT, na página Teste, assine o tópico de dados de saída para exibir mensagens de status do conector. A função de exemplo do Lambda é de longa duração e começa a enviar mensagens imediatamente após o grupo ser implantado.

    Ao finalizar o teste, você pode definir o ciclo de vida do Lambda como sob demanda (ou "Pinned": false na CLI) e implantar o grupo. Isso impede o envio de mensagens pela função.

Exemplo

O exemplo a seguir da função do Lambda envia uma mensagem de entrada para o conector.

import greengrasssdk import time import json iot_client = greengrasssdk.client('iot-data') send_topic = 'iotanalytics/channels/my_channel/messages/put' def create_request_with_all_fields(): return { "request": { "message" : "{\"temp\":23.33}" }, "id" : "req_123" } def publish_basic_message(): messageToPublish = create_request_with_all_fields() print("Message To Publish: ", messageToPublish) iot_client.publish(topic=send_topic, payload=json.dumps(messageToPublish)) publish_basic_message() def lambda_handler(event, context): return

Limites

Esse conector está sujeito aos limites a seguir.

  • Todos os limites impostos pelo AWS SDK for Python (Boto3) para a ação AWS IoT Analytics batch_put_message.

  • Todas as cotas impostas pela API do AWS IoT Analytics BatchputMessage. Para obter mais informações, consulte Cotas de serviço para o AWS IoT Analytics no Referência geral da AWS.

    • 100.000 mensagens por segundo por canal.

    • 100 mensagens por lote.

    • 128 KB por mensagem.

    Essa API usa nomes de canais (e não ARNs de canais), portanto, não há suporte ao envio de dados para canais entre regiões ou entre contas.

  • Todas as cotas impostas pelo núcleo do AWS IoT Greengrass. Para obter mais informações, consulte Cotas de serviço do AWS IoT Greengrass no Referência geral da AWS.

    As cotas a seguir podem ser especialmente aplicáveis:

    • O tamanho máximo das mensagens enviadas por um dispositivo é de 128 KB.

    • O tamanho máximo da fila de mensagens no roteador do núcleo do Greengrass é de 2,5 MB.

    • O tamanho máximo da string de um tópico é de 256 bytes de caracteres codificados em UTF-8.

Licenças

O conector de análises da IoT inclui o seguinte licenciamento/software de terceiros:

Esse conector é liberado de acordo com o Contrato de licença de software do Greengrass Core.

Changelog

A tabela a seguir descreve as alterações em cada versão do conector.

Versão

Alterações

4

Adição do parâmetro IsolationMode para configurar o modo de conteinerização para o conector.

3

Atualização do runtime do Lambda para Python 3.7, o que altera o requisito de runtime.

2

Corrija para reduzir o registro excessivo.

1

Versão inicial.

Um grupo do Greengrass só pode conter uma versão do conector por vez. Para obter informações sobre como fazer upgrade de uma versão do conector, consulte Atualizar a versões do conector.

Consulte também