Connettore SNS - AWS IoT Greengrass
RequisitiParametriDati di inputDati di outputEsempio di utilizzoLicenzeChangelogConsulta anche

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 SNS

Il connettore SNS pubblica messaggi su un argomento di Amazon SNS. Ciò consente ai server Web, agli indirizzi e-mail e agli altri abbonati al messaggio di rispondere agli eventi nel gruppo Greengrass.

Questo connettore riceve informazioni sui messaggi SNS in un argomento MQTT, quindi invia il messaggio a un argomento SNS specificato. Facoltativamente, puoi utilizzare funzioni Lambda personalizzate per implementare la logica di filtraggio o formattazione sui messaggi prima che vengano pubblicati su questo connettore.

Questo connettore ha le seguenti versioni.

Versione

ARN

4

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

3

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

2

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

1

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

Per informazioni sulle modifiche di ogni versione, consulta Changelog.

Requisiti

Questo connettore presenta i seguenti requisiti:

Version 3 - 4

  • Software AWS IoT Greengrass Core v1.9.3 o versioni successive.

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

  • Un argomento SNS configurato. Per le istruzioni, consulta Creazione di un argomento Amazon SNS nella Guida per lo Sviluppatore di Amazon Simple Notification Service.

  • Il ruolo del gruppo Greengrass è configurato per consentire l'sns:Publishazione sul target Amazon SNSTopic, come illustrato nel seguente esempio di policy IAM.

    {
    "Version":"2012-10-17",
    "Statement":[
        {
            "Sid":"Stmt1528133056761",
            "Action":[
                "sns:Publish"
            ],
            "Effect":"Allow",
            "Resource":[
                "arn:aws:sns:region:account-id:topic-name"
            ]
        }
    ]
 }

    Questo connettore consente di sostituire dinamicamente l'argomento predefinito nel payload del messaggio di input. Se l'implementazione utilizza questa funzionalità, la policy IAM deve consentire l'sns:Publishautorizzazione su tutti gli argomenti di destinazione. Puoi concedere alle risorse un accesso granulare o condizionale (ad esempio, utilizzando uno schema di denominazione con il carattere jolly *).

    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 GreengrassSoftware di base v1.7 o successivo.

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

  • Un argomento SNS configurato. Per le istruzioni, consulta Creazione di un argomento Amazon SNS nella Guida per lo Sviluppatore di Amazon Simple Notification Service.

  • Il ruolo del gruppo Greengrass è configurato per consentire l'sns:Publishazione sul target Amazon SNSTopic, come illustrato nel seguente esempio di policy IAM.

    {
    "Version":"2012-10-17",
    "Statement":[
        {
            "Sid":"Stmt1528133056761",
            "Action":[
                "sns:Publish"
            ],
            "Effect":"Allow",
            "Resource":[
                "arn:aws:sns:region:account-id:topic-name"
            ]
        }
    ]
 }

    Questo connettore consente di sostituire dinamicamente l'argomento predefinito nel payload del messaggio di input. Se l'implementazione utilizza questa funzionalità, la policy IAM deve consentire l'sns:Publishautorizzazione su tutti gli argomenti di destinazione. Puoi concedere alle risorse un accesso granulare o condizionale (ad esempio, utilizzando uno schema di denominazione con il carattere jolly *).

    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 del connettore

Questo connettore fornisce i seguenti parametri:

Version 4
DefaultSNSArn

L'ARN dell'argomento SNS predefinito in cui pubblicare i messaggi. L'argomento di destinazione può essere ignorato con la proprietà sns_topic_arn del payload del messaggio di input.

Nota

Il ruolo del gruppo deve permettere l'autorizzazione sns:Publish a tutti gli argomenti di destinazione. Per ulteriori informazioni, consulta Requisiti.

Nome visualizzato nella AWS IoT console: argomento SNS predefinito ARN

Obbligatorio: true

Tipo: string

Schema valido: arn:aws:sns:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):([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 container AWS IoT Greengrass.

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$

Versions 1 - 3
DefaultSNSArn

L'ARN dell'argomento SNS predefinito in cui pubblicare i messaggi. L'argomento di destinazione può essere ignorato con la proprietà sns_topic_arn del payload del messaggio di input.

Nota

Il ruolo del gruppo deve permettere l'autorizzazione sns:Publish a tutti gli argomenti di destinazione. Per ulteriori informazioni, consulta Requisiti.

Nome visualizzato nella AWS IoT console: argomento SNS predefinito ARN

Obbligatorio: true

Tipo: string

Schema valido: arn:aws:sns:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):([a-zA-Z0-9-_]+)$

Esempio di creazione di un connettore (AWS CLI)

Il seguente comando CLI crea un file ConnectorDefinition con una versione iniziale che contiene il connettore SNS.

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
    "Connectors": [
        {
            "Id": "MySNSConnector",
            "ConnectorArn": "arn:aws:greengrass:region::/connectors/SNS/versions/4",
            "Parameters": {
                "DefaultSNSArn": "arn:aws:sns:region:account-id:topic-name",
                "IsolationMode" : "GreengrassContainer"
            }
        }
    ]
}'

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 informazioni sui messaggi SNS su un argomento MQTT, quindi pubblica il messaggio così com'è nell'argomento SNS di destinazione. I messaggi di input devono essere in formato JSON.

Filtro argomento in sottoscrizione

sns/message

Proprietà dei messaggi
request

Informazioni sul messaggio da inviare all'argomento SNS.

Obbligatorio: true

Tipo: object che include le seguenti proprietà:

message

Il contenuto del messaggio come stringa o in formato JSON. Per degli esempi, vedi Input di esempio.

Per inviare JSON, la proprietà message_structure deve essere impostata su json e il messaggio deve essere un oggetto JSON codificato come stringa che contiene una chiave default.

Obbligatorio: true

Tipo: string

Schema valido: .*

subject

L'oggetto del messaggio.

Richiesto: false

Tipo: testo ASCII, fino a 100 caratteri. Deve iniziare con una lettera, un numero o un segno di punteggiatura. Non deve contenere interruzioni di riga né caratteri di controllo.

Modello valido: .*

sns_topic_arn

L'ARN dell'argomento SNS in cui pubblicare i messaggi. Se specificato, il connettore effettua la pubblicazione in questo argomento anziché in quello predefinito.

Nota

Il ruolo del gruppo deve permettere l'autorizzazione sns:Publish a qualsiasi argomento di destinazione. Per ulteriori informazioni, consulta Requisiti.

Richiesto: false

Tipo: string

Schema valido: arn:aws:sns:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):([a-zA-Z0-9-_]+)$

message_structure

La struttura del messaggio.

Obbligatorio: false. Questo deve essere specificato per inviare un messaggio JSON.

Tipo: string

Valori validi: json

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 non utilizzi questa funzione, puoi omettere la proprietà oppure specificare una stringa vuota.

Richiesto: false

Tipo: string

Schema valido: .*

Limiti

Le dimensioni dei messaggi SNS non devono superare i 256 KB.

Input di esempio: messaggio in formato stringa

In questo esempio viene inviato un messaggio in formato stringa. Specifica la proprietà facoltativa sns_topic_arn, che sostituisce l'argomento di destinazione predefinito.

{
    "request": {
        "subject": "Message subject",
        "message": "Message data",
        "sns_topic_arn": "arn:aws:sns:region:account-id:topic2-name"
    },
    "id": "request123"
}
Input di esempio: messaggio JSON

Questo esempio invia un messaggio come oggetto JSON codificato come stringa che include la chiave default.

{
    "request": {
        "subject": "Message subject",
        "message": "{ \"default\": \"Message data\" }",
        "message_structure": "json"
    },
    "id": "request123"
}

Dati di output

Questo connettore pubblica le informazioni di stato come dati di output su un argomento MQTT.

Filtro argomento in sottoscrizione

sns/message/status

Output di esempio: Operazione riuscita
{
    "response": {
        "sns_message_id": "f80a81bc-f44c-56f2-a0f0-d5af6a727c8a",
        "status": "success"
    },
    "id": "request123"
}
Esempio di output: Errore
{
   "response" : {
        "error": "InvalidInputException",
        "error_message": "SNS Topic Arn is invalid",
        "status": "fail"
   },
   "id": "request123"
}

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 GreengrassCore 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 = 'sns/message'

def create_request_with_all_fields():
    return  {
        "request": {
            "message": "Message from SNS Connector Test"
        },
        "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

Licenze

Il connettore SNS 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

Aggiunto il parametro IsolationMode 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