Connettore notifiche Twilio - 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 notifiche Twilio

avvertimento

Questo connettore è stato spostato nelFase di vitaeAWS IoT Greengrassnon rilascerà aggiornamenti che forniscono funzionalità, miglioramenti alle funzionalità esistenti, patch di sicurezza o correzioni di bug. Per ulteriori informazioni, consulta la pagina AWS IoT Greengrass Version 1politica di manutenzione .

Le notifiche di Twilioconnettoreeffettua automaticamente telefonate o invia messaggi di testo tramite Twilio. Puoi utilizzare questo connettore per inviare notifiche in risposta a eventi nel gruppo Greengrass. Per le telefonate, il connettore è in grado di inoltrare un messaggio vocale al destinatario.

Questo connettore riceve le informazioni sui messaggi Twilio in un argomento MQTT, quindi attiva una notifica Twilio.

Nota

Per un tutorial che mostra come utilizzare il connettore notifiche Twilio Notifications, consultaNozioni di base sui connettori Greengrass (console)oNozioni di base sui connettori Greengrass (CLI).

Questo connettore dispone delle versioni seguenti.

Versione

ARN

5

arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/5

4

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

3

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

2

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

1

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

Per informazioni sulle modifiche di ogni versione, consulta Changelog.

Requisiti

Questo connettore presenta i seguenti requisiti:

Version 4 - 5

  • AWS IoT GreengrassSoftware Core v1.9.3 o versioni successive.AWS IoT Greengrassdeve essere configurato per supportare segreti locali, come descritto inRequisiti 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 congreengrass -.

  • Pitoneversione 3.7 o 3.8 installata sul dispositivo core e aggiunta alla variabile di ambiente PATH.

    Nota

    Per utilizzare Python 3.8, eseguire 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.

  • 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, consultaOperazioni con l'account di prova Twilio gratuito.

  • Un segreto in formato testo di AWS Secrets Manager in cui viene memorizzato il token di autorizzazione Twilio. Per ulteriori informazioni, consultaCreazione di un segreto di basenellaAWS Secrets ManagerGuida per l’utente di.

    Nota

    Per creare il segreto nella console di Secrets Manager, inserisci il tuo token nellaTesto normale.Scheda. Non includere virgolette o altra formattazione. Nell'API, specificare il token come valore per ilSecretStringproprietà.

  • Una risorsa segreta nel gruppo Greengrass che fa riferimento al segreto di Secrets Manager. Per ulteriori informazioni, consulta la pagina Distribuzione dei segreti nel core AWS IoT Greengrass .

Versions 1 - 3

  • AWS IoT GreengrassSoftware Core v1.7 o versioni successive.AWS IoT Greengrassdeve essere configurato per supportare segreti locali, come descritto inRequisiti 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 congreengrass -.

  • Pitoneversione 2.7 installata sul dispositivo core e aggiunta alla variabile di ambiente PATH.

  • 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, consultaOperazioni con l'account di prova Twilio gratuito.

  • Un segreto in formato testo di AWS Secrets Manager in cui viene memorizzato il token di autorizzazione Twilio. Per ulteriori informazioni, consultaCreazione di un segreto di basenellaAWS Secrets ManagerGuida per l’utente di.

    Nota

    Per creare il segreto nella console di Secrets Manager, inserisci il tuo token nellaTesto normale.Scheda. Non includere virgolette o altra formattazione. Nell'API, specificare il token come valore per ilSecretStringproprietà.

  • Una risorsa segreta nel gruppo Greengrass che fa riferimento al segreto di Secrets Manager. Per ulteriori informazioni, consulta la pagina Distribuzione dei segreti nel core AWS IoT Greengrass .

Parametri del connettore

Questo connettore fornisce i seguenti parametri.

Version 5
TWILIO_ACCOUNT_SID

Il SID dell'account Twilio utilizzato per chiamare l'API Twilio.

Nome visualizzato nellaAWS IoTConsole : Twilio account

Campo: campo.true

Tipo: string

Modello:.+

TwilioAuthTokenSecretArn

L'ARN del segreto Secrets Manager in cui viene memorizzato il token di autorizzazione Twilio.

Nota

Viene utilizzato per accedere al valore del segreto locale nel core.

Nome visualizzato nellaAWS IoTConsole : ARN del segreto del token di autorizzazione Twilio

Campo: campo.true

Tipo: string

Modello:arn:aws:secretsmanager:[a-z0-9\-]+:[0-9]{12}:secret:([a-zA-Z0-9\\]+/)*[a-zA-Z0-9/_+=,.@\-]+-[a-zA-Z0-9]+

TwilioAuthTokenSecretArn-ResourceId

L'ID della risorsa segreta del gruppo Greengrass che fa riferimento al segreto del token di autorizzazione Twilio.

Nome visualizzato nellaAWS IoTConsole : Risorsa token di autorizzazione Twilio

Campo: campo.true

Tipo: string

Modello:.+

DefaultFromPhoneNumber

Il numero di telefono predefinito abilitato per Twilio che Twilio utilizza per l'invio di messaggi. Twilio utilizza questo numero per iniziare il messaggio di testo o la chiamata.

  • Se non configuri un numero di telefono predefinito, dovrai specificare un numero di telefono nella proprietà from_number nel corpo del messaggio di input.

  • Se configuri un numero di telefono predefinito, potrai ignorarlo specificando la proprietà from_number nel corpo del messaggio di input.

Nome visualizzato nellaAWS IoTConsole : Numero di telefono predefinito

Campo: campo.false

Tipo: string

Modello:^$|\+[0-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 nellaAWS IoTConsole : modalità di isolamento del container

Campo: campo.false

Tipo: string

Valori validi: GreengrassContainer o NoContainer

Modello:^NoContainer$|^GreengrassContainer$

Version 1 - 4
TWILIO_ACCOUNT_SID

Il SID dell'account Twilio utilizzato per chiamare l'API Twilio.

Nome visualizzato nellaAWS IoTConsole : Twilio account

Campo: campo.true

Tipo: string

Modello:.+

TwilioAuthTokenSecretArn

L'ARN del segreto Secrets Manager in cui viene memorizzato il token di autorizzazione Twilio.

Nota

Viene utilizzato per accedere al valore del segreto locale nel core.

Nome visualizzato nellaAWS IoTConsole : ARN del segreto del token di autorizzazione Twilio

Campo: campo.true

Tipo: string

Modello:arn:aws:secretsmanager:[a-z0-9\-]+:[0-9]{12}:secret:([a-zA-Z0-9\\]+/)*[a-zA-Z0-9/_+=,.@\-]+-[a-zA-Z0-9]+

TwilioAuthTokenSecretArn-ResourceId

L'ID della risorsa segreta del gruppo Greengrass che fa riferimento al segreto del token di autorizzazione Twilio.

Nome visualizzato nellaAWS IoTConsole : Risorsa token di autorizzazione Twilio

Campo: campo.true

Tipo: string

Modello:.+

DefaultFromPhoneNumber

Il numero di telefono predefinito abilitato per Twilio che Twilio utilizza per l'invio di messaggi. Twilio utilizza questo numero per iniziare il messaggio di testo o la chiamata.

  • Se non configuri un numero di telefono predefinito, dovrai specificare un numero di telefono nella proprietà from_number nel corpo del messaggio di input.

  • Se configuri un numero di telefono predefinito, potrai ignorarlo specificando la proprietà from_number nel corpo del messaggio di input.

Nome visualizzato nellaAWS IoTConsole : Numero di telefono predefinito

Campo: campo.false

Tipo: string

Modello:^$|\+[0-9]+

Esempio di creazione di un connettore (AWS CLI)

Il seguente comando CLI di esempio crea unConnectorDefinitioncon una versione iniziale che contiene il connettore notifiche Twilio Notifications.

aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
    "Connectors": [
        {
            "Id": "MyTwilioNotificationsConnector",
            "ConnectorArn": "arn:aws:greengrass:region::/connectors/TwilioNotifications/versions/5",
            "Parameters": {
                "TWILIO_ACCOUNT_SID": "abcd12345xyz",
                "TwilioAuthTokenSecretArn": "arn:aws:secretsmanager:region:account-id:secret:greengrass-secret-hash",
                "TwilioAuthTokenSecretArn-ResourceId": "MyTwilioSecret",
                "DefaultFromPhoneNumber": "+19999999999",
                "IsolationMode" : "GreengrassContainer"
            }
        }
    ]
}'

Per i tutorial che mostrano come aggiungere il connettore notifiche Twilio a un gruppo, consultaNozioni di base sui connettori Greengrass (CLI)eNozioni di base sui connettori Greengrass (console).

Dati di input

Questo connettore accetta le informazioni sui messaggi di Twilio in due argomenti MQTT. I messaggi di input devono essere in formato JSON.

  • Informazioni sui messaggi di testo nell'argomento twilio/txt.

  • Informazioni sui messaggi vocali nell'argomento twilio/call.

Nota

Il payload del messaggio di input può includere un messaggio di testo (message) o un messaggio vocale (voice_message_location), ma non entrambi.

Filtro di argomenti: twilio/txt
Proprietà dei messaggi
request

Informazioni sulla notifica Twilio.

Campo: campo.true

Tipo:objectcon le seguenti proprietà:

recipient

Il destinatario del messaggio. È supportato solo un destinatario.

Campo: campo.true

Tipo:objectcon le seguenti proprietà:

name

Il nome del destinatario.

Campo: campo.true

Tipo: string

Modello:.*

phone_number

Il numero di telefono del destinatario.

Campo: campo.true

Tipo: string

Modello:\+[1-9]+

message

Il contenuto del messaggio di testo. In questo argomento sono supportati solo i messaggi di testo. Per i messaggi vocali, utilizzare twilio/call.

Campo: campo.true

Tipo: string

Modello:.+

from_number

Il numero di telefono del mittente. Twilio utilizza questo numero di telefono per iniziare il messaggio. Questa proprietà è obbligatoria se il parametro DefaultFromPhoneNumber non è configurato. Se DefaultFromPhoneNumber è stato configurato, puoi utilizzare questa proprietà per ignorare quello predefinito.

Campo: campo.false

Tipo: string

Modello:\+[1-9]+

retries

Il numero di tentativi. Il valore predefinito è 0.

Campo: campo.false

Tipo: integer

id

Un ID arbitrario della richiesta. Questa proprietà viene utilizzata per associare una richiesta di input a una risposta di output.

Campo: campo.true

Tipo: string

Modello:.+

Input di esempio
{
    "request": {
        "recipient": {
            "name": "Darla",
            "phone_number": "+12345000000",
            "message": "Hello from the edge"
        },
        "from_number": "+19999999999",
        "retries": 3
    },
    "id": "request123"
}
Filtro di argomenti: twilio/call
Proprietà dei messaggi
request

Informazioni sulla notifica Twilio.

Campo: campo.true

Tipo:objectcon le seguenti proprietà:

recipient

Il destinatario del messaggio. È supportato solo un destinatario.

Campo: campo.true

Tipo:objectcon le seguenti proprietà:

name

Il nome del destinatario.

Campo: campo.true

Tipo: string

Modello:.+

phone_number

Il numero di telefono del destinatario.

Campo: campo.true

Tipo: string

Modello:\+[1-9]+

voice_message_location

L'URL del contenuto audio del messaggio vocale. Deve essere in formato TwiML. In questo argomento sono supportati solo i messaggi vocali. Per i messaggi di testo, utilizzare twilio/txt.

Campo: campo.true

Tipo: string

Modello:.+

from_number

Il numero di telefono del mittente. Twilio utilizza questo numero di telefono per iniziare il messaggio. Questa proprietà è obbligatoria se il parametro DefaultFromPhoneNumber non è configurato. Se DefaultFromPhoneNumber è stato configurato, puoi utilizzare questa proprietà per ignorare quello predefinito.

Campo: campo.false

Tipo: string

Modello:\+[1-9]+

retries

Il numero di tentativi. Il valore predefinito è 0.

Campo: campo.false

Tipo: integer

id

Un ID arbitrario della richiesta. Questa proprietà viene utilizzata per associare una richiesta di input a una risposta di output.

Campo: campo.true

Tipo: string

Modello:.+

Input di esempio
{
    "request": {
        "recipient": {
            "name": "Darla",
            "phone_number": "+12345000000",
            "voice_message_location": "https://some-public-TwiML"
        },
        "from_number": "+19999999999",
        "retries": 3
    },
    "id": "request123"
}

Dati di output

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

Filtro argomento in sottoscrizione

twilio/message/status

Output di esempio: Riuscito
{
    "response": {
        "status": "success",
        "payload": {
            "from_number": "+19999999999",
            "messages": {
                "message_status": "queued",
                "to_number": "+12345000000",
                "name": "Darla"
            }
        }
    },
    "id": "request123"
}
Output di esempio: Errore
{
    "response": {
        "status": "fail",
        "error_message": "Recipient name cannot be None",
        "error": "InvalidParameter",
        "payload": None
        }
    },
    "id": "request123"
}

La proprietà payload nell'output è la risposta dall'API Twilio al momento dell'invio del messaggio. Se il connettore rileva che i dati di input non sono validi (ad esempio, non è specificato un campo di input obbligatorio), il connettore restituisce un errore e imposta il valore su None. Di seguito vengono riportati payload di esempio:

{
    'from_number':'+19999999999',
    'messages': {
        'name':'Darla',
        'to_number':'+12345000000',
        'message_status':'undelivered'
    }
}
{
    'from_number':'+19999999999',
    'messages': {
        'name':'Darla',
        'to_number':'+12345000000',
        'message_status':'queued'
    }
}

Esempio di utilizzo

Utilizza i seguenti passaggi di alto livello per impostare un esempio di funzione Lambda Python 3.7 che puoi utilizzare per provare il connettore.

Nota

LaNozioni di base sui connettori Greengrass (console)eNozioni di base sui connettori Greengrass (CLI)gli argomenti contengono end-to-end passaggi che mostrano come configurare, distribuire e testare il connettore notifiche Twilio Notifications.

  1. Assicurarsi di soddisfare i requisiti per il connettore.

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

    Salvare il codice di esempio come file PY. Scarica e decomprimi il fileAWS IoT GreengrassSDK di base 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 caricato suAWS Lambda.

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

  3. Configurare il gruppo Greengrass.

    1. Aggiungi la funzione Lambda con il suo alias (scelta consigliata). Configura il ciclo di vita Lambda su lunga durata (o"Pinned": truenella CLI).

    2. Aggiungi la risorsa segreta richiesta e concedi l'accesso in lettura alla funzione Lambda.

    3. Aggiungere il connettore e configurarne i relativi parametri.

    4. 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 l'argomento di input supportato.

      • Imposta il connettore come origine, AWS IoT Core come destinazione e utilizza un filtro per l’argomento di output supportato. Utilizza questa sottoscrizione per visualizzare i messaggi di stato inAWS IoTConsole.

  4. Distribuisci il gruppo.

  5. NellaAWS IoTconsole, sulTest, sottoscrivi l'argomento dei dati di output per visualizzare i messaggi di stato dal connettore. La funzione Lambda di esempio ha una lunga durata e inizia a inviare messaggi immediatamente dopo la distribuzione del gruppo.

    Al termine del test, puoi impostare il ciclo di vita Lambda su «on demand» (o"Pinned": falsenella CLI) e distribuire il gruppo. Ciò impedisce alla funzione di inviare messaggi.

Esempio

La funzione Lambda di esempio seguente invia un messaggio di input al connettore. Questo esempio attiva un messaggio di testo.

import greengrasssdk
import json

iot_client = greengrasssdk.client('iot-data')
TXT_INPUT_TOPIC = 'twilio/txt'
CALL_INPUT_TOPIC = 'twilio/call'

def publish_basic_message():

    txt = {
        "request": {
            "recipient" : {
                "name": "Darla",
                "phone_number": "+12345000000",
                "message": 'Hello from the edge'
            },
            "from_number" : "+19999999999"
        },
        "id" : "request123"
    }
    
    print("Message To Publish: ", txt)

    client.publish(topic=TXT_INPUT_TOPIC,
                   payload=json.dumps(txt))

publish_basic_message()

def lambda_handler(event, context):
    return

Licenze

Il connettore notifiche Twilio include il software e le licenze di terze parti indicati di

Questo connettore viene rilasciato sotto ilAccordo di licenza del software Greengrass Core.

Changelog

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

Versione

Modifiche

5

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

4

Aggiornato il runtime Lambda a Python 3.7, che modifica il requisito di runtime.

3

Correggere per ridurre l'eccessiva registrazione di log.

2

Miglioramenti e correzioni di bug minori.

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