Nozioni di base sui connettori Greengrass (CLI) - 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à.

Nozioni di base sui connettori Greengrass (CLI)

Questa caratteristica è disponibile solo perAWS IoT GreengrassCore v1.7 e successive.

Questo tutorial mostra come utilizzare l'AWS CLI con i connettori.

Utilizza i connettori per accelerare il ciclo di vita dello sviluppo. I connettori sono moduli precostituiti e riutilizzabili che semplificano l'interazione con servizi, protocolli e risorse. Possono aiutarti a distribuire più rapidamente la logica di business ai dispositivi Greengrass. Per ulteriori informazioni, consulta la pagina Integrazione con servizi e protocolli tramite i connettori Greengrass .

In questo tutorial, configuri e distribuisciNotifiche Twilioconnettore. Il connettore riceve le informazioni sui messaggi Twilio come dati di input, quindi attiva un messaggio di testo Twilio. Il flusso di dati viene mostrato nel seguente schema.

Flusso di dati dalla funzione Lambda al connettore Twilio Notifications a Twilio.

Dopo avere configurato il connettore, è necessario creare una funzione Lambda e una sottoscrizione.

  • La funzione valuta i dati simulati da un sensore di temperatura. Pubblica in base a condizioni le informazioni sul messaggio Twilio in un argomento MQTT. Questo è l'argomento a cui il connettore effettua la sottoscrizione.

  • La sottoscrizione consente alla funzione di effettuare la pubblicazione nell'argomento e al connettore di ricevere i dati dall'argomento.

Il connettore Twilio Notifications richiede un token di autorizzazione Twilio per interagire con l'API Twilio. Il token è un segreto sotto forma di testo creato AWS Secrets Manager e a cui fa riferimento una risorsa di gruppo. Ciò consente a AWS IoT Greengrass di creare una copia locale del segreto nel core Greengrass, dove viene crittografata e resa disponibile al connettore. Per ulteriori informazioni, consulta la pagina Distribuzione dei segreti nel core AWS IoT Greengrass .

Il tutorial include le seguenti fasi di alto livello:

Il completamento di questo tutorial richiede circa 30 minuti.

Uso dell'API AWS IoT Greengrass

È utile comprendere i seguenti schemi quando lavori con i gruppi Greengrass e i componenti dei gruppi (ad esempio connettori, funzioni e risorse del gruppo).

  • In alto nella gerarchia, un componente dispone di un oggetto definizione, ovvero un container di oggetti versione. Una versione è invece un container dei connettori, delle funzioni o di altri tipi di componenti.

  • Quando effettui una distribuzione nel core Greengrass, distribuisci una specifica versione del gruppo. Una versione del gruppo può contenere una versione di ciascun tipo di componente. È necessario un core, ma gli altri sono inclusi in base alle necessità.

  • Le versioni non possono essere modificate. Pertanto, se desideri apportare modifiche, dovrai crearne di nuove.

Suggerimento

Se si verifica un errore quando esegui un comando AWS CLI, aggiungi il parametro --debug ed esegui nuovamente il comando per ottenere ulteriori informazioni sull'errore.

L'API AWS IoT Greengrass ti consente di creare più definizioni per un tipo di componente. Ad esempio, puoi creare un oggetto FunctionDefinition ogni volta che crei una FunctionDefinitionVersion oppure puoi aggiungere nuove versioni a una definizione esistente. Questa flessibilità ti consente di personalizzare il sistema di gestione delle versioni.

Prerequisiti

Per completare questo tutorial, è necessario quanto segue:

  • Un gruppo Greengrass e un core Greengrass (v1.9.3 or later). Per informazioni su come creare un gruppo e un core Greengrass, consulta Guida introduttiva con AWS IoT Greengrass. Nel tutorial Nozioni di base sono descritte anche le fasi per l'installazione del software AWS IoT Greengrass Core.

  • Python 3.7 installato sul dispositivo AWS IoT Greengrass core.

  • AWS IoT Greengrassdeve essere configurato per supportare segreti locali, come descritto inRequisiti dei segreti.

    Nota

    Questo requisito include consentire l'accesso ai tuoi segreti di Secrets Manager. Se stai utilizzando il ruolo del servizio Greengrass predefinito, Greengrass avrà il permesso di ottenere i valori dei segreti con nomi che iniziano con"*greengrass -.

  • SID dell'account Twilio, token di autorizzazione e numero di telefono abilitato per Twilio. Dopo avere creato un progetto Twilio, questi valori sono disponibili nel pannello di controllo del progetto.

    Nota

    Puoi utilizzare un account di prova Twilio. Se utilizzi un account di prova, devi aggiungere numeri di telefono di destinatari non Twilio a un elenco di numeri di telefono verificati. Per ulteriori informazioni, consultaCome lavorare con il tuo account di prova Twilio gratuito.

Fase 1: Creazione di un segreto di Secrets Manager

In questa fase, è possibile utilizzare l'API AWS Secrets Manager per creare un segreto del token di autorizzazione Twilio.

  1. È necessario creare innanzitutto il segreto.

    • Replace (Sostituisci)twilio-auth-tokencon il token di autorizzazione Twilio.

    aws secretsmanager create-secret --name greengrass-TwilioAuthToken --secret-string twilio-auth-token
    Nota

    Per impostazione predefinita, il ruolo del servizio Greengrass consenteAWS IoT Greengrassper ottenere il valore dei segreti con nomi che inizianogreengrass -. Per ulteriori informazioni, consulta Requisiti dei segreti.

  2. Copiare l'ARN del segreto dall'output. In questo modo si crea la risorsa segreta e si configura il connettore delle notifiche Twilio.

Fase 2: Creazione della versione e della definizione della risorsa

In questa fase, è possibile utilizzareAWS IoT GreengrassAPI per creare una risorsa del segreto di Secrets Manager.

  1. Creare una definizione di risorsa che includa una versione iniziale.

    • Sostituire secret-arn con l'ARN del segreto copiato nella fase precedente.

     

    JSON Expanded
    aws greengrass create-resource-definition --name MyGreengrassResources --initial-version '{ "Resources": [ { "Id": "TwilioAuthToken", "Name": "MyTwilioAuthToken", "ResourceDataContainer": { "SecretsManagerSecretResourceData": { "ARN": "secret-arn" } } } ] }'
    JSON Single-line
    aws greengrass create-resource-definition \ --name MyGreengrassResources \ --initial-version '{"Resources": [{"Id": "TwilioAuthToken", "Name": "MyTwilioAuthToken", "ResourceDataContainer": {"SecretsManagerSecretResourceData": {"ARN": "secret-arn"}}}]}'
  2. Copiare la LatestVersionArn della definizione di risorsa dall'output. È possibile utilizzare questo valore per aggiungere la definizione di risorsa alla versione del gruppo distribuita nel core.

Fase 3: Creazione della versione e della definizione del connettore

In questa fase, si configurano i parametri del connettore Twilio Notifications.

  1. Creare una definizione del connettore con una versione iniziale.

    • Sostituire account-sid con il SID dell'account Twilio.

    • Replace (Sostituisci)secret-arncon ilARNdel segreto di Secrets Manager. Il connettore lo utilizzerà per ottenere il valore del segreto locale.

    • Sostituire phone-number con il numero di telefono abilitato per Twilio. Twilio lo utilizza per iniziare il messaggio di testo. Questo può essere sostituito nel payload del messaggio di input. Utilizza il seguente formato: +19999999999.

     

    JSON Expanded
    aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyTwilioNotificationsConnector", "ConnectorArn": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4", "Parameters": { "TWILIO_ACCOUNT_SID": "account-sid", "TwilioAuthTokenSecretArn": "secret-arn", "TwilioAuthTokenSecretArn-ResourceId": "TwilioAuthToken", "DefaultFromPhoneNumber": "phone-number" } } ] }'
    JSON Single-line
    aws greengrass create-connector-definition \ --name MyGreengrassConnectors \ --initial-version '{"Connectors": [{"Id": "MyTwilioNotificationsConnector", "ConnectorArn": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4", "Parameters": {"TWILIO_ACCOUNT_SID": "account-sid", "TwilioAuthTokenSecretArn": "secret-arn", "TwilioAuthTokenSecretArn-ResourceId": "TwilioAuthToken", "DefaultFromPhoneNumber": "phone-number"}}]}'
    Nota

    TwilioAuthToken è l'ID utilizzato nella fase precedente per creare la risorsa segreta.

  2. Copiare il LatestVersionArn della definizione del connettore dall'output. È possibile utilizzare questo valore per aggiungere la definizione del connettore alla versione del gruppo distribuita nel core.

Fase 4: Creazione di un pacchetto di distribuzione della funzione Lambda

Per creare una funzione Lambda, devi prima creare una funzione Lambdapacchetto di distribuzioneche contiene il codice della funzione e le dipendenze. Le funzioni Lambda di Greengrass richiedonoAWS IoT GreengrassCore SDKper attività come la comunicazione con messaggi MQTT nell'ambiente principale e l'accesso ai segreti locali. Questo tutorial crea una funzione Python, in modo da utilizzare la versione Python dell'SDK nel pacchetto di distribuzione.

  1. DaAWS IoT GreengrassCore SDKpagina di download, scarica ilAWS IoT GreengrassCore SDK per Python sul tuo computer.

  2. Decomprimere il pacchetto scaricato per ottenere l'SDK. Il kit SDK è la cartella greengrasssdk.

  3. Salvare la seguente funzione del codice Python nel file locale temp_monitor.py.

    import greengrasssdk import json import random client = greengrasssdk.client('iot-data') # publish to the Twilio Notifications connector through the twilio/txt topic def function_handler(event, context): temp = event['temperature'] # check the temperature # if greater than 30C, send a notification if temp > 30: data = build_request(event) client.publish(topic='twilio/txt', payload=json.dumps(data)) print('published:' + str(data)) print('temperature:' + str(temp)) return # build the Twilio request from the input data def build_request(event): to_name = event['to_name'] to_number = event['to_number'] temp_report = 'temperature:' + str(event['temperature']) return { "request": { "recipient": { "name": to_name, "phone_number": to_number, "message": temp_report } }, "id": "request_" + str(random.randint(1,101)) }
  4. Comprimere le voci seguenti nel file temp_monitor_python.zip. Al momento della creazione del file ZIP, includere solo il codice e le dipendenze, non la cartella che li contiene.

    • temp_monitor.py. La logica dell'app.

    • greengrasssdk. Libreria richiesta per le funzioni Python Greengrass Lambda che pubblicano messaggi MQTT.

    Questo file è il pacchetto di distribuzione della funzione Lambda.

Fase 5: Creazione di una funzione Lambda

Creare a questo punto una funzione Lambda che utilizzi il pacchetto di distribuzione.

  1. Crea un ruolo IAM in modo da poter passare l'ARN del ruolo quando crei la funzione.

    JSON Expanded
    aws iam create-role --role-name Lambda_empty --assume-role-policy '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }'
    JSON Single-line
    aws iam create-role --role-name Lambda_empty --assume-role-policy '{"Version": "2012-10-17", "Statement": [{"Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"},"Action": "sts:AssumeRole"}]}'
    Nota

    AWS IoT Greengrassnon utilizza questo ruolo perché le autorizzazioni delle funzioni Greengrass Lambda sono specificate nel ruolo del gruppo Greengrass. Per questo tutorial, viene creato un ruolo vuoto.

  2. Copia il valore Arn dall'output.

  3. Utilizzo dell'AWS LambdaAPI per creare il TempMonitor funzione. Il comando seguente presuppone che il file ZIP si trovi nella directory corrente.

    • Sostituire role-arn con l'Arn copiato.

    aws lambda create-function \ --function-name TempMonitor \ --zip-file fileb://temp_monitor_python.zip \ --role role-arn \ --handler temp_monitor.function_handler \ --runtime python3.7
  4. Pubblicare una versione della funzione.

    aws lambda publish-version --function-name TempMonitor --description 'First version'
  5. Creare un alias della versione pubblicata.

    I gruppi Greengrass possono fare riferimento a una funzione Lambda tramite alias (consigliato) o per versione. L'utilizzo di un alias semplifica la gestione degli aggiornamenti del codice perché non è necessario modificare la tabella di sottoscrizione o la definizione del gruppo quando il codice funzione viene aggiornato. Invece, è sufficiente puntare l'alias alla nuova versione della funzione.

    Nota

    AWS IoT Greengrassnon supporta alias Lambda per$LATESTVersioni.

    aws lambda create-alias --function-name TempMonitor --name GG_TempMonitor --function-version 1
  6. Copia il valore AliasArn dall'output. Questo valore viene utilizzato durante la configurazione della funzione per AWS IoT Greengrass e la creazione di un abbonamento.

Adesso puoi configurare la funzione per AWS IoT Greengrass.

Fase 6: Creazione della versione e della definizione della funzione

Per utilizzare una funzione Lambda su unAWS IoT Greengrasscore, è necessario creare una versione della definizione di funzione che faccia riferimento alla funzione Lambda in base all'alias e definisca la configurazione a livello di gruppo. Per ulteriori informazioni, consulta la pagina Controllo dell'esecuzione delle funzioni Greengrass Lambda utilizzando la configurazione specifica del gruppo .

  1. Creare una definizione di funzione che includa una versione iniziale.

    • Sostituire alias-arn con l'AliasArn copiato al momento della creazione dell'alias.

     

    JSON Expanded
    aws greengrass create-function-definition --name MyGreengrassFunctions --initial-version '{ "Functions": [ { "Id": "TempMonitorFunction", "FunctionArn": "alias-arn", "FunctionConfiguration": { "Executable": "temp_monitor.function_handler", "MemorySize": 16000, "Timeout": 5 } } ] }'
    JSON Single-line
    aws greengrass create-function-definition \ --name MyGreengrassFunctions \ --initial-version '{"Functions": [{"Id": "TempMonitorFunction", "FunctionArn": "alias-arn", "FunctionConfiguration": {"Executable": "temp_monitor.function_handler", "MemorySize": 16000,"Timeout": 5}}]}'
  2. Copia il valore LatestVersionArn dall'output. È possibile utilizzare questo valore per aggiungere la definizione di funzione alla versione del gruppo distribuita nel core.

  3. Copia il valore Id dall'output. È possibile utilizzare questo valore successivamente, al momento dell'aggiornamento della funzione.

Fase 7: Creazione della versione e della definizione dell'abbonamento

In questa fase, aggiungerai un abbonamento che consente alla funzione Lambda di inviare dati di input al connettore. Il connettore definisce gli argomenti MQTT a cui è sottoscritto. Pertanto, questa sottoscrizione utilizza uno degli argomenti. Si tratta dello argomento in cui la funzione di esempio effettua la pubblicazione.

In questo tutorial, crei anche sottoscrizioni che consentono alla funzione di ricevere letture simulate della temperatura da AWS IoT e che consentono a AWS IoT di ricevere informazioni sullo stato dal connettore.

  1. Creare una definizione di abbonamento che includa una versione iniziale contenente gli abbonamenti.

    • Sostituire alias-arn con l'AliasArn copiato al momento della creazione dell'alias per la funzione. Utilizzare questo ARN per entrambi gli abbonamenti.

     

    JSON Expanded
    aws greengrass create-subscription-definition --initial-version '{ "Subscriptions": [ { "Id": "TriggerNotification", "Source": "alias-arn", "Subject": "twilio/txt", "Target": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4" }, { "Id": "TemperatureInput", "Source": "cloud", "Subject": "temperature/input", "Target": "alias-arn" }, { "Id": "OutputStatus", "Source": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4", "Subject": "twilio/message/status", "Target": "cloud" } ] }'
    JSON Single-line
    aws greengrass create-subscription-definition \ --initial-version '{"Subscriptions": [{"Id": "TriggerNotification", "Source": "alias-arn", "Subject": "twilio/txt", "Target": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4"},{"Id": "TemperatureInput", "Source": "cloud", "Subject": "temperature/input", "Target": "alias-arn"},{"Id": "OutputStatus", "Source": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/4", "Subject": "twilio/message/status", "Target": "cloud"}]}'
  2. Copia il valore LatestVersionArn dall'output. È possibile utilizzare questo valore per aggiungere la definizione dell'abbonamento alla versione del gruppo distribuita nel core.

Fase 8: Creazione di una versione del gruppo

A questo punto è possibile creare una versione del gruppo che contenga tutte le voci da distribuire. A questo scopo, è necessario creare una versione di gruppo che faccia riferimento alla versione di destinazione di ciascun tipo di componente.

Ottenere innanzitutto l'ID del gruppo e l'ARN della versione della definizione del core. Questi valori sono necessari per creare la versione del gruppo.

  1. Ottenere l'ID del gruppo e la versione gruppo più recente:

    1. Ottieni gli ID del gruppo di destinazione Greengrass e la versione dei gruppi. Questa procedura presuppone che questo sia il gruppo e la versione di gruppo più recente. La query seguente restituisce il gruppo creato più di recente.

      aws greengrass list-groups --query "reverse(sort_by(Groups, &CreationTimestamp))[0]"

      In alternativa, puoi eseguire query in base al nome. I nomi dei gruppi non devono essere univoci, pertanto potrebbero essere restituiti più gruppi.

      aws greengrass list-groups --query "Groups[?Name=='MyGroup']"
      Nota

      Questi valori sono disponibili anche inAWS IoTConsole. L'ID gruppo viene visualizzato nella pagina Settings (Impostazioni) del gruppo. Gli ID della versione del gruppo vengono visualizzati nellaDistribuzionilinguetta.

    2. Copiare l'Id del gruppo di destinazione dall'output. Questo valore viene utilizzato per ottenere la versione della definizione del core e durante la distribuzione del gruppo.

    3. Copiare la LatestVersion dall'output, che corrisponde all'ID dell'ultima versione aggiunta al gruppo. Questo valore viene utilizzato per ottenere la versione della definizione del core.

  2. Per ottenere l'ARN della versione di definizione del core:

    1. Ottenere la versione del gruppo. In questa fase, si presume che la versione del gruppo più recente includa una versione della definizione del core.

      • Sostituisci group-id con l'Id copiato per il gruppo.

      • Replace (Sostituisci)group-version-idcon ilLatestVersioncopiato per il gruppo.

      aws greengrass get-group-version \ --group-id group-id \ --group-version-id group-version-id
    2. Copia il valore CoreDefinitionVersionArn dall'output.

  3. Creare una versione del gruppo.

    • Sostituisci group-id con l'Id copiato per il gruppo.

    • Replace (Sostituisci)core-definition-version-arncon ilCoreDefinitionVersionArncopiato per la versione della definizione del core.

    • Replace (Sostituisci)resource-definition-version-arncon ilLatestVersionArncopiato per la definizione di risorsa.

    • Replace (Sostituisci)connector-definition-version-arncon ilLatestVersionArncopiato per la definizione del connettore.

    • Replace (Sostituisci)function-definition-version-arncon ilLatestVersionArncopiato per la definizione della funzione.

    • Replace (Sostituisci)subscription-definition-version-arncon ilLatestVersionArncopiato per la definizione di sottoscrizione.

    aws greengrass create-group-version \ --group-id group-id \ --core-definition-version-arn core-definition-version-arn \ --resource-definition-version-arn resource-definition-version-arn \ --connector-definition-version-arn connector-definition-version-arn \ --function-definition-version-arn function-definition-version-arn \ --subscription-definition-version-arn subscription-definition-version-arn
  4. Copia il valore di Version dall'output. Questo è l'ID della versione del gruppo. È possibile utilizzare questo valore per distribuire la versione del gruppo.

Fase 9: Crea distribuzione

Distribuire il gruppo al nuovo dispositivo core.

  1. In un terminale del dispositivo core, assicurarsi che il daemon AWS IoT Greengrass sia in esecuzione.

    1. Per controllare se il daemon è in esecuzione:

      ps aux | grep -E 'greengrass.*daemon'

      Se l'output contiene una voce root per /greengrass/ggc/packages/1.11.6/bin/daemon, allora il daemon è in esecuzione.

    2. Per avviare il daemon:

      cd /greengrass/ggc/core/ sudo ./greengrassd start
  2. Creare una distribuzione.

    • Sostituisci group-id con l'Id copiato per il gruppo.

    • Replace (Sostituisci)group-version-idcon ilVersioncopiato per la nuova versione del gruppo.

    aws greengrass create-deployment \ --deployment-type NewDeployment \ --group-id group-id \ --group-version-id group-version-id
  3. Copia il valore DeploymentId dall'output.

  4. Ottenere lo stato della distribuzione.

    • Sostituisci group-id con l'Id copiato per il gruppo.

    • Sostituire deployment-id con il DeploymentId copiato per la distribuzione.

    aws greengrass get-deployment-status \ --group-id group-id \ --deployment-id deployment-id

    Se lo stato di èSuccess, la distribuzione è stata completata. Per la risoluzione dei problemi, consultare Risoluzione dei problemi relativi a AWS IoT Greengrass.

Test della soluzione

  1. SulAWS IoTHome page della console, scegliTest.

  2. PerSottoscrizione dell'argomento, utilizza i seguenti valori, quindi scegliSottoscrizione. I connettori Twilio Notifications pubblicano informazioni sullo stato in questo argomento.

    Proprietà

    Value (Valore)

    Argomento sottoscrizione

    twilio/message/status

    Visualizzazione payload MQTT

    Visualizza i payload come stringhe

  3. PerPubblicazione nell'argomento, utilizza i seguenti valori, quindi scegliPubblicareper richiamare la funzione.

    Proprietà

    Value (Valore)

    Argomento

    temperatura/input

    Messaggio

    Replace (Sostituisci)recipient-namecon un nome erecipient-phone-numbercon il numero di telefono del destinatario del messaggio di testo. Esempio: +12345000000

    { "to_name": "recipient-name", "to_number": "recipient-phone-number", "temperature": 31 }

    Se utilizzi un account di prova, devi aggiungere numeri di telefono di destinatari non Twilio a un elenco di numeri di telefono verificati. Per ulteriori informazioni, consultaVerifica del numero di telefono personale.

    Se l'operazione viene completata, il destinatario riceve il messaggio di testo e la console mostra lo stato success dai dati di output.

    A questo punto, è necessario modificare temperature nel messaggio di input in 29 e pubblicare. Poiché è un valore inferiore a 30, TempMonitor non attiverà un messaggio Twilio.

Consultare anche