Connettore IoT Analytics - AWS IoT Greengrass

AWS IoT Greengrass Version 1 è entrato nella fase di estensione della vita utile il 30 giugno 2023. Per ulteriori informazioni, consulta la politica AWS IoT Greengrass V1 di manutenzione. Dopo questa data, AWS IoT Greengrass V1 non rilascerà aggiornamenti che forniscano funzionalità, miglioramenti, correzioni di bug o patch di sicurezza. I dispositivi che funzionano AWS IoT Greengrass V1 non subiranno interruzioni e continueranno a funzionare e a connettersi al cloud. Ti consigliamo vivamente di eseguire la migrazione a AWS IoT Greengrass Version 2, che aggiunge nuove importanti funzionalità e supporto per piattaforme aggiuntive.

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Connettore IoT Analytics

avvertimento

Questo connettore è entrato nella fase di vita prolungata e AWS IoT Greengrass non rilascerà aggiornamenti che forniscano funzionalità, miglioramenti alle funzionalità esistenti, patch di sicurezza o correzioni di bug. Per ulteriori informazioni, consulta AWS IoT Greengrass Version 1 politica di manutenzione.

Il connettore IoT Analytics invia i dati del dispositivo locale a AWS IoT Analytics. È possibile utilizzare questo connettore come hub centrale per raccogliere dati dai sensori sul dispositivo principale Greengrass e dai dispositivi client collegati. Il connettore invia i dati ai AWS IoT Analytics canali della regione corrente Account AWS e della regione. Può inviare i dati a un canale di destinazione predefinito e ai canali specificati in modo dinamico.

Nota

AWS IoT Analytics è un servizio completamente gestito che consente di raccogliere, archiviare, elaborare e interrogare dati IoT. Nel AWS IoT Analytics, i dati possono essere ulteriormente analizzati ed elaborati. Ad esempio, possono essere utilizzati per dare forma ai modelli ML per il monitoraggio della salute macchina o per testare nuove strategie di modellazione. Per ulteriori informazioni, consulta Cos'è AWS IoT Analytics? nella Guida AWS IoT Analytics per l'utente.

Il connettore accetta i dati formattati e non formattati negli argomenti MQTT di input. Supporta due argomenti predefiniti in cui il canale di destinazione viene specificato in linea. Può anche ricevere i messaggi su argomenti definiti dal cliente che vengono configurati nelle sottoscrizioni. Questo può essere usato per indirizzare messaggi da dispositivi client che pubblicano su argomenti fissi o per gestire dati non strutturati o dipendenti dallo stack provenienti da dispositivi con risorse limitate.

Questo connettore utilizza l'BatchPutMessageAPI per inviare dati (come stringa con codifica JSON o base64) al canale di destinazione. Il connettore è in grado di eseguire i dati non elaborati in un formato che soddisfa i requisiti delle API. Il connettore memorizza nel buffer i messaggi nelle code per canale ed elabora in modo asincrono i batch. Offre i parametri che consentono di controllare l'accodamento e la creazione di comportamenti in batch, nonché di limitare il consumo della memoria. Ad esempio, è possibile configurare dimensioni massime della coda, intervallo in batch, dimensioni della memoria e numero di canali attivo.

Questo connettore ha le seguenti versioni.

Versione

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

Per informazioni sulle modifiche di ogni versione, consulta Changelog.

Requisiti

Questo connettore presenta i seguenti requisiti:

Version 3 - 4
  • AWS IoT Greengrass Software principale v1.9.3 o versione successiva.

  • Python versione 3.7 o 3.8 installata sul dispositivo principale e aggiunta alla variabile di ambiente PATH.

    Nota

    Per usare Python 3.8, esegui il seguente comando per creare un collegamento simbolico dalla cartella di installazione predefinita di Python 3.7 ai binari Python 3.8 installati.

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

    Questo configura il dispositivo in modo che soddisfi il requisito Python per AWS IoT Greengrass.

  • Questo connettore può essere utilizzato solo nelle regioni di Amazon Web Services in cui entrambi AWS IoT GreengrassAWS IoT Analyticssono supportati.

  • Tutte le AWS IoT Analytics entità e i flussi di lavoro correlati vengono creati e configurati. Le entità includono canali, pipeline, datastore e set di dati. Per ulteriori informazioni, consulta le procedure AWS CLI o console nella Guida per l'utente AWS IoT Analytics .

    Nota

    AWS IoT Analytics I canali di destinazione devono utilizzare lo stesso account e trovarsi nello Regione AWS stesso connettore.

  • Il ruolo del gruppo Greengrass è configurato per consentire l'iotanalytics:BatchPutMessageazione sui canali di destinazione, come mostrato nel seguente esempio di politica IAM. I canali devono trovarsi nell'area corrente Account AWS e nella regione.

    { "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" ] } ] }

    Per il requisito del ruolo di gruppo, è necessario configurare il ruolo in modo da concedere le autorizzazioni necessarie e assicurarsi che il ruolo sia stato aggiunto al gruppo. Per ulteriori informazioni, consulta Gestione del ruolo del gruppo Greengrass (console) o Gestione del ruolo del gruppo Greengrass (CLI).

Versions 1 - 2
  • AWS IoT Greengrass Software principale v1.7 o successivo.

  • Python versione 2.7 installato sul dispositivo principale e aggiunto alla variabile di ambiente PATH.

  • Questo connettore può essere utilizzato solo nelle regioni di Amazon Web Services in cui entrambi AWS IoT GreengrassAWS IoT Analyticssono supportati.

  • Tutte le AWS IoT Analytics entità e i flussi di lavoro correlati vengono creati e configurati. Le entità includono canali, pipeline, datastore e set di dati. Per ulteriori informazioni, consulta le procedure AWS CLI o console nella Guida per l'utente AWS IoT Analytics .

    Nota

    AWS IoT Analytics I canali di destinazione devono utilizzare lo stesso account e trovarsi nello Regione AWS stesso connettore.

  • Il ruolo del gruppo Greengrass è configurato per consentire l'iotanalytics:BatchPutMessageazione sui canali di destinazione, come mostrato nel seguente esempio di politica IAM. I canali devono trovarsi nell'area corrente Account AWS e nella regione.

    { "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" ] } ] }

    Per il requisito del ruolo di gruppo, è necessario configurare il ruolo in modo da concedere le autorizzazioni necessarie e assicurarsi che il ruolo sia stato aggiunto al gruppo. Per ulteriori informazioni, consulta Gestione del ruolo del gruppo Greengrass (console) o Gestione del ruolo del gruppo Greengrass (CLI).

Parametri

MemorySize

La quantità di memoria (in KB) da allocare al connettore.

Nome visualizzato nella AWS IoT console: dimensione della memoria

Obbligatorio: true

Tipo: string

Schema valido: ^[0-9]+$

PublishRegion

Il Regione AWS modo in cui vengono creati i tuoi AWS IoT Analytics canali. Utilizza la stessa regione del connettore.

Nota

Questo deve inoltre corrispondere alla regione per i canali specificati nel ruolo gruppo.

Nome visualizzato nella AWS IoT console: regione di pubblicazione

Obbligatorio: false

Tipo: string

Schema valido: ^$|([a-z]{2}-[a-z]+-\\d{1})

PublishInterval

L'intervallo (in secondi) in cui pubblicare un batch di dati ricevuti. AWS IoT Analytics

Nome visualizzato nella AWS IoT console: Intervallo di pubblicazione

Obbligatorio: false

Tipo: string

Valore predefinito: 1

Schema valido: $|^[0-9]+$

IotAnalyticsMaxActiveChannels

Il numero massimo di AWS IoT Analytics canali che il connettore monitora attivamente. Questo deve essere maggiore di 0 e almeno pari al numero di canali su cui prevedi che il connettore pubblicherà in un determinato momento.

Puoi utilizzare questo parametro per limitare il consumo della memoria limitando il numero totale di code che il connettore è in grado di gestire in un determinato momento. Una coda viene eliminato quando tutti i messaggi in coda vengono inviati.

Nome visualizzato nella AWS IoT console: numero massimo di canali attivi

Obbligatorio: false

Tipo: string

Valore predefinito: 50

Schema valido: ^$|^[1-9][0-9]*$

IotAnalyticsQueueDropBehavior

Il comportamento per l'eliminazione di messaggi da una coda del canale quando la coda è piena.

Nome visualizzato nella AWS IoT console: comportamento di caduta dalla coda

Obbligatorio: false

Tipo: string

Valori validi: DROP_NEWEST o DROP_OLDEST

Valore predefinito: DROP_NEWEST

Schema valido: ^DROP_NEWEST$|^DROP_OLDEST$

IotAnalyticsQueueSizePerChannel

Il numero massimo di messaggi da conservare in memoria (per canale) prima che vengano inviati o eliminati. Questo numero deve essere maggiore di 0.

Nome visualizzato nella AWS IoT console: dimensione massima della coda per canale

Obbligatorio: false

Tipo: string

Valore predefinito: 2048

Schema valido: ^$|^[1-9][0-9]*$

IotAnalyticsBatchSizePerChannel

Il numero massimo di messaggi da inviare a un AWS IoT Analytics canale in una richiesta batch. Questo numero deve essere maggiore di 0.

Nome visualizzato nella AWS IoT console: numero massimo di messaggi da raggruppare in batch per canale

Obbligatorio: false

Tipo: string

Valore predefinito: 5

Schema valido: ^$|^[1-9][0-9]*$

IotAnalyticsDefaultChannelName

Il nome del AWS IoT Analytics canale utilizzato da questo connettore per i messaggi inviati a un argomento di input definito dal cliente.

Nome visualizzato nella AWS IoT console: nome del canale predefinito

Obbligatorio: false

Tipo: string

Schema valido: ^[a-zA-Z0-9_]$

IsolationMode

Modalità di containerizzazione per questo connettore. L'impostazione predefinita èGreengrassContainer, il che significa che il connettore viene eseguito in un ambiente di runtime isolato all'interno del AWS IoT Greengrass contenitore.

Nota

L'impostazione predefinita della containerizzazione per il gruppo non si applica ai connettori.

Nome visualizzato nella AWS IoT console: modalità di isolamento del contenitore

Obbligatorio: false

Tipo: string

Valori validi: GreengrassContainer o NoContainer

Schema valido: ^NoContainer$|^GreengrassContainer$

Esempio di creazione di un connettore (AWS CLI)

Il seguente comando CLI crea una ConnectorDefinition versione iniziale che contiene il connettore IoT Analytics.

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

La funzione Lambda in questo connettore ha un ciclo di vita di lunga durata.

Nella AWS IoT Greengrass console, puoi aggiungere un connettore dalla pagina Connettori del gruppo. Per ulteriori informazioni, consulta Nozioni di base sui connettori Greengrass (console).

Dati di input

Questo connettore accetta i dati su argomenti MQTT predefiniti e definiti dal cliente. Gli editori possono essere dispositivi client, funzioni Lambda o altri connettori.

Argomenti predefiniti

Il connettore supporta i due seguenti argomenti MQTT strutturati che consentono ai publisher di specificare il nome del canale in linea.

  • Un messaggio formattato sull'argomento iotanalytics/channels/+/messages/put. I dati IoT in questi messaggi di input devono essere in formato JSON o una stringa con codifica base64.

  • Un messaggio non formattato sull'argomento iotanalytics/channels/+/messages/binary/put. I messaggi di input ricevuti su questo argomento vengono trattati come dati binari e possono contenere qualsiasi tipo di dati.

    Per pubblicare gli argomenti predefiniti, sostituire il carattere jolly + con il nome del canale. Per esempio:

    iotanalytics/channels/my_channel/messages/put
Argomenti definiti dal cliente

Il connettore supporta la sintassi dell'argomento #, che consente di accettare messaggi di input su qualsiasi argomento MQTT che configuri in una sottoscrizione. Ti consigliamo di specificare il percorso di un argomento invece di utilizzare solo il carattere # jolly nelle tue sottoscrizioni. Questi messaggi vengono inviati al canale predefinito specificato per il connettore.

I messaggi di input sugli argomenti definiti dal cliente vengono trattati come dati binari. Essi possono usare qualsiasi formato del messaggio e contenere qualsiasi tipo di dati. Puoi utilizzare gli argomenti definiti dal cliente per instradare i messaggi provenienti da dispositivi che pubblicano su argomenti fissi. È inoltre possibile utilizzarli per accettare dati di input da dispositivi client che non sono in grado di elaborare i dati in un messaggio formattato da inviare al connettore.

Per ulteriori informazioni sulle sottoscrizioni e sugli argomenti MQTT, consulta Input e output.

Il ruolo del gruppo consente l'operazione iotanalytics:BatchPutMessage su tutti i canali di destinazione. Per ulteriori informazioni, consulta Requisiti.

Filtro di argomenti: iotanalytics/channels/+/messages/put

Utilizzare questo argomento per inviare messaggi formattati al connettore e specificare in modo dinamico un canale di destinazione. Questo argomento consente inoltre di specificare un ID restituito nell'output della risposta. Il connettore verifica che sia IDs univoco per ogni messaggio della BatchPutMessage richiesta in uscita a cui viene inviato. AWS IoT Analytics Viene eliminato un messaggio con un ID duplicato.

I dati di input inviati a questo argomento devono utilizzare il seguente formato del messaggio.

Proprietà dei messaggi
request

I dati da inviare al canale specificato.

Obbligatorio: true

Tipo: object che include le seguenti proprietà:

message

Il dispositivo o i dati di sensori come JSON o stringa con codifica base64.

Obbligatorio: true

Tipo: string

id

Un ID arbitrario della richiesta. Questa proprietà viene utilizzata per associare una richiesta di input a una risposta di output. Quando specificato, la proprietà id nell'oggetto della risposta è impostata su questo valore. Se si omette questa proprietà, il connettore genera un ID.

Richiesto: false

Tipo: string

Schema valido: .*

Input di esempio
{ "request": { "message" : "{\"temp\":23.33}" }, "id" : "req123" }
Filtro di argomenti: iotanalytics/channels/+/messages/binary/put

Utilizzare questo argomento per inviare messaggi non formattati al connettore e specificare in modo dinamico un canale di destinazione.

I dati del connettore non analizzano i messaggi di input ricevuti su questo argomento. Vengono trattati come dati binari. Prima di inviare i messaggi a AWS IoT Analytics, il connettore li codifica e li formatta per renderli conformi ai requisiti BatchPutMessage dell'API:

  • Il connettore codifica su base64 i dati grezzi e include il payload codificato in una richiesta BatchPutMessage in uscita.

  • Il connettore genera e assegna un ID per ogni messaggio di input.

    Nota

    L'output della risposta del connettore non include una correlazione di ID per questi messaggi di input.

Proprietà dei messaggi

Nessuna.

Filtro di argomenti: #

Utilizzare questo argomento per inviare qualsiasi formato del messaggio al canale predefinito. Ciò è particolarmente utile quando i dispositivi client pubblicano su argomenti fissi o quando si desidera inviare dati al canale predefinito da dispositivi client che non sono in grado di elaborare i dati nel formato di messaggio supportato dal connettore.

La sintassi dell'argomento viene definita nell'abbonamento creato per connettere questo connettore all'origine dati. Ti consigliamo di specificare il percorso di un argomento invece di utilizzare solo il carattere # jolly nelle tue sottoscrizioni.

I dati del connettore non analizzano i messaggi pubblicati su questo argomento di input. Tutti i messaggi di input vengono trattati come dati binari. Prima di inviare i messaggi a AWS IoT Analytics, il connettore li codifica e li formatta per renderli conformi ai requisiti dell'API: BatchPutMessage

  • Il connettore codifica su base64 i dati grezzi e include il payload codificato in una richiesta BatchPutMessage in uscita.

  • Il connettore genera e assegna un ID per ogni messaggio di input.

    Nota

    L'output della risposta del connettore non include una correlazione di ID per questi messaggi di input.

Proprietà dei messaggi

Nessuna.

Dati di output

Questo connettore pubblica le informazioni di stato come dati di output su un argomento MQTT. Queste informazioni contengono la risposta restituita da AWS IoT Analytics per ogni messaggio di input ricevuto e inviato. AWS IoT Analytics

Filtro argomento in sottoscrizione

iotanalytics/messages/put/status

Output di esempio: Operazione riuscita
{ "response" : { "status" : "success" }, "id" : "req123" }
Esempio di output: Errore
{ "response" : { "status" : "fail", "error" : "ResourceNotFoundException", "error_message" : "A resource with the specified name could not be found." }, "id" : "req123" }
Nota

Se il connettore rileva un errore ripetibile (ad esempio errori di connessione), riprova la pubblicazione nel batch successivo. Il backoff esponenziale viene gestito dall'SDK. AWS Le richieste con errori non irreversibili vengono aggiunte alla coda del canale per ulteriore pubblicazione in base al parametro IotAnalyticsQueueDropBehavior.

Esempio di utilizzo

Usa i seguenti passaggi di alto livello per configurare una funzione Lambda di esempio di Python 3.7 che puoi usare per provare il connettore.

Nota
  1. Assicurarsi di soddisfare i requisiti per il connettore.

    Per il requisito del ruolo di gruppo, è necessario configurare il ruolo in modo da concedere le autorizzazioni necessarie e assicurarsi che il ruolo sia stato aggiunto al gruppo. Per ulteriori informazioni, consulta Gestione del ruolo del gruppo Greengrass (console) o Gestione del ruolo del gruppo Greengrass (CLI).

  2. Crea e pubblica una funzione Lambda che invia dati di input al connettore.

    Salvare il codice di esempio come file PY. Scarica e decomprimi il AWS IoT Greengrass Core SDK per Python. Quindi, crea un pacchetto zip che contiene il file PY e la cartella greengrasssdk a livello root. Questo pacchetto zip è il pacchetto di distribuzione in cui carichi. AWS Lambda

    Dopo aver creato la funzione Python 3.7 Lambda, pubblica una versione della funzione e crea un alias.

  3. Configurare il gruppo Greengrass.

    1. Aggiungi la funzione Lambda tramite il relativo alias (consigliato). Configura il ciclo di vita Lambda come longevo (o nella "Pinned": true CLI).

    2. Aggiungere il connettore e configurarne i relativi parametri.

    3. Aggiungere sottoscrizioni che consentono al connettore di ricevere i dati di input e inviare i dati di output nei filtri degli argomenti supportati.

      • Imposta la funzione Lambda come origine, il connettore come destinazione e utilizza un filtro per argomenti di input supportato.

      • Imposta il connettore come origine, AWS IoT Core come destinazione e utilizza un filtro per l’argomento di output supportato. Utilizzi questo abbonamento per visualizzare i messaggi di stato nella AWS IoT console.

  4. Distribuisci il gruppo.

  5. Nella AWS IoT console, nella pagina Test, sottoscrivi l'argomento relativo ai dati di output per visualizzare i messaggi di stato dal connettore. La funzione Lambda di esempio è di lunga durata e inizia a inviare messaggi subito dopo l'implementazione del gruppo.

    Al termine del test, puoi impostare il ciclo di vita Lambda su richiesta (o nella CLI) e "Pinned": false distribuire il gruppo. Ciò impedisce alla funzione di inviare messaggi.

Esempio

L'esempio seguente della funzione Lambda invia un messaggio di input al connettore.

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

Limiti

Questo connettore è soggetto ai limiti descritti di seguito.

  • Tutti i limiti AWS SDK per Python (Boto3) imposti dall' AWS IoT Analytics batch_put_messageazione.

  • Tutte le quote imposte dall' AWS IoT Analytics BatchPutMessageAPI. Per ulteriori informazioni, vedere Service Quotas for AWS IoT Analytics in. Riferimenti generali di AWS

    • 100.000 messaggi al secondo per canale.

    • 100 messaggi per batch.

    • 128 KB per messaggio.

    Questa API utilizza i nomi dei canali (non i canali ARNs), pertanto l'invio di dati a canali interregionali o tra account non è supportato.

  • Tutte le quote imposte dal Core. AWS IoT Greengrass Per ulteriori informazioni, vedere Service Quotas for the AWS IoT Greengrass core in. Riferimenti generali di AWS

    In particolare potrebbero essere applicate le seguenti quote:

    • La dimensione massima dei messaggi inviati da un dispositivo è 128 KB.

    • La dimensione massima della coda di messaggi nel router core di Greengrass è 2,5 MB.

    • La lunghezza massima di una stringa argomento è 256 byte di caratteri con codifica UTF-8.

Licenze

Il connettore IoT Analytics include i seguenti software/licenze di terze parti:

Questo connettore è rilasciato ai sensi del contratto di licenza del software Greengrass Core.

Changelog

La tabella seguente descrive le modifiche apportate a ciascuna versione del connettore.

Versione

Modifiche

4

Aggiunge il IsolationMode parametro per configurare la modalità di containerizzazione per il connettore.

3

È stato aggiornato il runtime Lambda a Python 3.7, che modifica i requisiti di runtime.

2

Correggere per ridurre l'eccessiva registrazione di log.

1

Versione iniziale.

Un gruppo Greengrass può contenere una sola versione del connettore alla volta. Per informazioni sull'aggiornamento di una versione del connettore, consulta Aggiornamento delle versioni dei connettori.

Consulta anche