Conector de notificações Twilio - AWS IoT Greengrass
RequisitosParâmetrosDados de entradaDados de saídaExemplo de usoLicençasChangelogConsulte também

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 notificações Twilio

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 notificações Twilio faz chamadas telefônicas automatizadas ou envia mensagens SMS por meio do Twilio. Você pode usar esse conector para enviar notificações em resposta a eventos no grupo do Greengrass. Para chamadas telefônicas, o conector pode encaminhar uma mensagem de voz para o destinatário.

Esse conector recebe informações de mensagens do Twilio em um tópico MQTT e aciona uma notificação do Twilio.

nota

Para obter um tutorial que mostra como usar o conector de notificações Twilio, consulte Conceitos básicos de conectores do Greengrass (console) ou Conceitos básicos de conectores do Greengrass (CLI).

Esse conector tem as seguintes versões.

Versão

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

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

Requisitos

Esse conector tem os seguintes requisitos:

Version 4 - 5

  • Software AWS IoT Greengrass Core v1.9.3 ou posterior. O AWS IoT Greengrass deve ser configurado para oferecer suporte a segredos locais, conforme descrito em Requisitos de segredos.

    nota

    Este requisito inclui permitir o acesso aos seus segredos do Secrets Manager. Se você estiver usando o perfil de serviço padrão do Greengrass, o Greengrass terá permissão para obter valores de segredos com nomes que começam com greengrass-.

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

  • Um SID da conta do Twilio, um token de autorização e um número de telefone habilitado para Twilio. Depois de criar um projeto do Twilio, esses valores estarão disponíveis no painel do projeto.

    nota

    Você pode usar uma conta de teste do Twilio. Se você estiver usando uma conta de teste, você deve adicionar números de telefone que não são de destinatários do Twilio a uma lista de números de telefone verificados. Para obter mais informações, consulte Como trabalhar com a sua conta de teste gratuita do Twilio.

  • Um segredo de tipo de texto no AWS Secrets Manager que armazena o token de autenticação do Twilio. Para obter mais informações, consulte Criar um segredo básico no Guia do usuário do AWS Secrets Manager.

    nota

    Para criar o segredo no console do Secrets Manager, insira seu token na guia Texto simples. Não inclua aspas ou outra formatação. Na API, especifique o token como o valor da propriedade SecretString.

  • Um recurso de segredo no grupo do Greengrass que faz referência ao segredo do Secrets Manager. Para obter mais informações, consulte Implantar segredos no núcleo do AWS IoT Greengrass.

Versions 1 - 3

  • Software AWS IoT Greengrass Core v1.7 ou posterior. O AWS IoT Greengrass deve ser configurado para oferecer suporte a segredos locais, conforme descrito em Requisitos de segredos.

    nota

    Este requisito inclui permitir o acesso aos seus segredos do Secrets Manager. Se você estiver usando o perfil de serviço padrão do Greengrass, o Greengrass terá permissão para obter valores de segredos com nomes que começam com greengrass-.

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

  • Um SID da conta do Twilio, um token de autorização e um número de telefone habilitado para Twilio. Depois de criar um projeto do Twilio, esses valores estarão disponíveis no painel do projeto.

    nota

    Você pode usar uma conta de teste do Twilio. Se você estiver usando uma conta de teste, você deve adicionar números de telefone que não são de destinatários do Twilio a uma lista de números de telefone verificados. Para obter mais informações, consulte Como trabalhar com a sua conta de teste gratuita do Twilio.

  • Um segredo de tipo de texto no AWS Secrets Manager que armazena o token de autenticação do Twilio. Para obter mais informações, consulte Criar um segredo básico no Guia do usuário do AWS Secrets Manager.

    nota

    Para criar o segredo no console do Secrets Manager, insira seu token na guia Texto simples. Não inclua aspas ou outra formatação. Na API, especifique o token como o valor da propriedade SecretString.

  • Um recurso de segredo no grupo do Greengrass que faz referência ao segredo do Secrets Manager. Para obter mais informações, consulte Implantar segredos no núcleo do AWS IoT Greengrass.

Parâmetros do conector

Esse conector oferece os seguintes parâmetros.

Version 5
TWILIO_ACCOUNT_SID

O SID da conta do Twilio que é usado para invocar a API do Twilio.

Nome de exibição no console do AWS IoT: SID da conta do Twilio

Obrigatório: true

Digite: string

Padrão válido: .+

TwilioAuthTokenSecretArn

O ARN do segredo do Secrets Manager que armazena o token de autenticação do Twilio.

nota

É usado para acessar o valor do segredo local no núcleo.

Nome de exibição no console do AWS IoT: ARN do segredo do token de autenticação do Twilio

Obrigatório: true

Digite: string

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

TwilioAuthTokenSecretArn-ResourceId

O ID do recurso de segredo no grupo do Greengrass que faz referência ao segredo para o token de autenticação do Twilio.

Nome de exibição no console do AWS IoT: Recurso do token de autenticação do Twilio

Obrigatório: true

Digite: string

Padrão válido: .+

DefaultFromPhoneNumber

O número de telefone padrão habilitado e usado pelo Twilio para enviar mensagens. O Twilio usa esse número para iniciar a mensagem ou chamada.

  • Se você não configurar um número de telefone padrão, deverá especificar um número de telefone na propriedade from_number no corpo da mensagem de entrada.

  • Se você configurar um número de telefone padrão, poderá substituir o padrão especificando a propriedade from_number no corpo da mensagem de entrada.

Nome de exibição no console do AWS IoT: Padrão de número de telefone

Obrigatório: false

Digite: string

Padrão válido: ^$|\+[0-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$

Version 1 - 4
TWILIO_ACCOUNT_SID

O SID da conta do Twilio que é usado para invocar a API do Twilio.

Nome de exibição no console do AWS IoT: SID da conta do Twilio

Obrigatório: true

Digite: string

Padrão válido: .+

TwilioAuthTokenSecretArn

O ARN do segredo do Secrets Manager que armazena o token de autenticação do Twilio.

nota

É usado para acessar o valor do segredo local no núcleo.

Nome de exibição no console do AWS IoT: ARN do segredo do token de autenticação do Twilio

Obrigatório: true

Digite: string

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

TwilioAuthTokenSecretArn-ResourceId

O ID do recurso de segredo no grupo do Greengrass que faz referência ao segredo para o token de autenticação do Twilio.

Nome de exibição no console do AWS IoT: Recurso do token de autenticação do Twilio

Obrigatório: true

Digite: string

Padrão válido: .+

DefaultFromPhoneNumber

O número de telefone padrão habilitado e usado pelo Twilio para enviar mensagens. O Twilio usa esse número para iniciar a mensagem ou chamada.

  • Se você não configurar um número de telefone padrão, deverá especificar um número de telefone na propriedade from_number no corpo da mensagem de entrada.

  • Se você configurar um número de telefone padrão, poderá substituir o padrão especificando a propriedade from_number no corpo da mensagem de entrada.

Nome de exibição no console do AWS IoT: Padrão de número de telefone

Obrigatório: false

Digite: string

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

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

O seguinte comando da CLI de exemplo cria um ConnectorDefinition com uma versão inicial que contém o conector de notificações Twilio.

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

Para obter tutoriais que mostram como adicionar o conector de notificações Twilio a um grupo, consulte Conceitos básicos de conectores do Greengrass (CLI) e Conceitos básicos de conectores do Greengrass (console).

Dados de entrada

Esse conector aceita informações de mensagens do Twilio em dois tópicos MQTT. As mensagens de entrada devem estar no formato JSON.

  • Informações de mensagens SMS no tópico twilio/txt.

  • Informações de mensagens de voz no tópico twilio/call.

nota

A carga da mensagem de entrada pode incluir uma mensagem SMS (message) ou mensagem de voz (voice_message_location), mas não as duas.

Filtro de tópico: twilio/txt
Propriedades de mensagens
request

Informações sobre a notificação do Twilio.

Obrigatório: true

Tipo: object que inclui as seguintes propriedades:

recipient

O destinatário da mensagem. Somente um destinatário tem suporte.

Obrigatório: true

Tipo: object que inclui as seguintes propriedades:

name

O nome do destinatário.

Obrigatório: true

Digite: string

Padrão válido: .*

phone_number

O número de telefone do destinatário.

Obrigatório: true

Digite: string

Padrão válido: \+[1-9]+

message

O conteúdo de texto da mensagem SMS. Somente mensagens SMS têm suporte neste tópico. Para mensagens de voz, use twilio/call.

Obrigatório: true

Digite: string

Padrão válido: .+

from_number

O número de telefone do remetente. O Twilio usa esse número de telefone para iniciar a mensagem. Essa propriedade será necessária se o parâmetro DefaultFromPhoneNumber não estiver configurado. Se DefaultFromPhoneNumber estiver configurado, você poderá usar essa propriedade para substituir o padrão.

Obrigatório: false

Digite: string

Padrão válido: \+[1-9]+

retries

O número de novas tentativas. O padrão é 0.

Obrigatório: false

Digite: integer

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.

Obrigatório: true

Digite: string

Padrão válido: .+

Exemplo de entrada
{
    "request": {
        "recipient": {
            "name": "Darla",
            "phone_number": "+12345000000",
            "message": "Hello from the edge"
        },
        "from_number": "+19999999999",
        "retries": 3
    },
    "id": "request123"
}
Filtro de tópico: twilio/call
Propriedades de mensagens
request

Informações sobre a notificação do Twilio.

Obrigatório: true

Tipo: object que inclui as seguintes propriedades:

recipient

O destinatário da mensagem. Somente um destinatário tem suporte.

Obrigatório: true

Tipo: object que inclui as seguintes propriedades:

name

O nome do destinatário.

Obrigatório: true

Digite: string

Padrão válido: .+

phone_number

O número de telefone do destinatário.

Obrigatório: true

Digite: string

Padrão válido: \+[1-9]+

voice_message_location

O URL do conteúdo de áudio para a mensagem de voz. Deve estar no formato TwiML. Somente mensagens de voz têm suporte neste tópico. Para mensagens SMS, use twilio/txt.

Obrigatório: true

Digite: string

Padrão válido: .+

from_number

O número de telefone do remetente. O Twilio usa esse número de telefone para iniciar a mensagem. Essa propriedade será necessária se o parâmetro DefaultFromPhoneNumber não estiver configurado. Se DefaultFromPhoneNumber estiver configurado, você poderá usar essa propriedade para substituir o padrão.

Obrigatório: false

Digite: string

Padrão válido: \+[1-9]+

retries

O número de novas tentativas. O padrão é 0.

Obrigatório: false

Digite: integer

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.

Obrigatório: true

Digite: string

Padrão válido: .+

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

Dados de saída

O conector publica informações de status como dados de saída em um tópico MQTT.

Filtro de tópico na assinatura

twilio/message/status

Exemplo de resultado: sucesso
{
    "response": {
        "status": "success",
        "payload": {
            "from_number": "+19999999999",
            "messages": {
                "message_status": "queued",
                "to_number": "+12345000000",
                "name": "Darla"
            }
        }
    },
    "id": "request123"
}
Exemplo de resultado: falha
{
    "response": {
        "status": "fail",
        "error_message": "Recipient name cannot be None",
        "error": "InvalidParameter",
        "payload": None
        }
    },
    "id": "request123"
}

A propriedade payload na saída é a resposta da API do Twilio quando a mensagem é enviada. Se o conector detecta que os dados de entrada são inválidos (por exemplo, se ele não especifica um campo de entrada obrigatório), o conector retorna um erro e define o valor como None. Veja as cargas de exemplo a seguir:

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

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

Os tópicos Conceitos básicos de conectores do Greengrass (console) e Conceitos básicos de conectores do Greengrass (CLI) contêm etapas de ponta a ponta que mostram como configurar, implantar e testar o conector de notificações do Twilio.

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

  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 recurso de segredode segredo necessário e conceda acesso de leitura à função do Lambda.

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

    4. 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. Este exemplo aciona uma mensagem de texto.

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

Licenças

O conector de notificações Twilio 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

5

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

4

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

3

Corrija para reduzir o registro excessivo.

2

Correções de bugs secundários e melhorias.

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