Conector do SNS - 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 do SNS

O conector do SNS publica mensagens em um tópico do Amazon SNS. Isso permite que os servidores web, endereços de e-mail e outros assinantes de mensagens respondam a eventos no grupo do Greengrass.

Esse conector recebe informações de mensagens do SNS em um tópico MQTT e envia a mensagem para um determinado tópico do SNS. Você também pode usar funções do Lambda personalizadas para implementar a lógica de formatação ou filtragem em mensagens antes que elas sejam publicadas nesse conector.

Esse conector tem as seguintes versões.

Version (Versão)

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

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

Requisitos

Esse conector tem os seguintes requisitos:

Version 3 - 4

  • Software de núcleo do AWS IoT Greengrass v1.9.3 ou versão posterior.

  • 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 tópico do SNS configurado. Para obter mais informações, consulte Criação de um tópico do Amazon SNS no Guia do desenvolvedor do Amazon Simple Notification Service.

  • A função de grupo do Greengrass configurada para permitir a ação sns:Publish no tópico de destino do Amazon SNS, conforme mostrado no exemplo de política do IAM a seguir.

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

    Esse conector permite que você substitua dinamicamente o tópico padrão na carga da mensagem de entrada. Se a sua implementação usa esse atributo, a política do IAM deve conceder a permissão sns:Publish em todos os tópicos de destino. Você pode conceder acesso granular ou condicional aos recursos (por exemplo, usando um esquema de nomeação * curinga).

    Para o requisito de função de grupo, você deve configurar a função para conceder as permissões necessárias e certificar-se de que a função tenha sido adicionada ao grupo. Para obter mais informações, consulte Gerenciar a função de grupo do Greengrass (console) ou Gerenciar a função de grupo do Greengrass (CLI).

Versions 1 - 2

  • Software AWS IoT Greengrass Core v1.7 ou posterior.

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

  • Um tópico do SNS configurado. Para obter mais informações, consulte Criação de um tópico do Amazon SNS no Guia do desenvolvedor do Amazon Simple Notification Service.

  • A função de grupo do Greengrass configurada para permitir a ação sns:Publish no tópico de destino do Amazon SNS, conforme mostrado no exemplo de política do IAM a seguir.

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

    Esse conector permite que você substitua dinamicamente o tópico padrão na carga da mensagem de entrada. Se a sua implementação usa esse atributo, a política do IAM deve conceder a permissão sns:Publish em todos os tópicos de destino. Você pode conceder acesso granular ou condicional aos recursos (por exemplo, usando um esquema de nomeação * curinga).

    Para o requisito de função de grupo, você deve configurar a função para conceder as permissões necessárias e certificar-se de que a função tenha sido adicionada ao grupo. Para obter mais informações, consulte Gerenciar a função de grupo do Greengrass (console) ou Gerenciar a função de grupo do Greengrass (CLI).

Parâmetros do conector

Esse conector oferece os seguintes parâmetros:

Version 4
DefaultSNSArn

O ARN do tópico padrão do SNS no qual publicar mensagens. O tópico de destino pode ser substituído pela propriedade sns_topic_arn na carga da mensagem de entrada.

nota

A função do grupo deve conceder a permissão sns:Publish em todos os tópicos de destino. Para ter mais informações, consulte Requisitos.

Nome de exibição no console do AWS IoT: ARN do tópico padrão do SNS

Obrigatório: true

Digite: string

Padrão válido: arn:aws:sns:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):([a-zA-Z0-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 runtime 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$

Versions 1 - 3
DefaultSNSArn

O ARN do tópico padrão do SNS no qual publicar mensagens. O tópico de destino pode ser substituído pela propriedade sns_topic_arn na carga da mensagem de entrada.

nota

A função do grupo deve conceder a permissão sns:Publish em todos os tópicos de destino. Para ter mais informações, consulte Requisitos.

Nome de exibição no console do AWS IoT: ARN do tópico padrão do SNS

Obrigatório: true

Digite: string

Padrão válido: arn:aws:sns:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):([a-zA-Z0-9-_]+)$

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

O seguinte comando da CLI cria um ConnectorDefinition com uma versão inicial que contém o conector do 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"
            }
        }
    ]
}'

No console do AWS IoT Greengrass, você pode adicionar um conector na página Conectores do grupo. Para obter mais informações, consulte Conceitos básicos de conectores do Greengrass (console).

Dados de entrada

Esse conector aceita informações de mensagens do SNS em um tópico MQTT e publica a mensagem da maneira que se encontra como um tópico do SNS de destino. As mensagens de entrada devem estar no formato JSON.

Filtro de tópico na assinatura

sns/message

Propriedades de mensagens
request

Informações sobre a mensagem a ser enviada para o tópico do SNS.

Obrigatório: true

Tipo: object que inclui as seguintes propriedades:

message

O conteúdo da mensagem como uma string ou no formato JSON. Para obter exemplos, consulte Exemplos de entrada.

Para enviar JSON, a propriedade message_structure deve ser definida como json e a mensagem deve ser uma string codificada por objeto JSON com uma chave default.

Obrigatório: true

Digite: string

Padrão válido: .*

subject

O assunto da mensagem.

Obrigatório: false

Tipo: O texto ASCII, com até 100 caracteres. Deve começar com uma letra, um número ou um sinal de pontuação. Não deve incluir quebras de linha ou caracteres de controle.

Padrão válido: .*

sns_topic_arn

O ARN do tópico do SNS no qual publicar mensagens. Se especificado, o conector publicará nesse tópico em vez do tópico padrão.

nota

A função do grupo deve conceder a permissão sns:Publish a qualquer tópico de destino. Para ter mais informações, consulte Requisitos.

Obrigatório: false

Digite: string

Padrão válido: arn:aws:sns:([a-z]{2}-[a-z]+-\d{1}):(\d{12}):([a-zA-Z0-9-_]+)$

message_structure

A estrutura da mensagem.

Obrigatório: false. Isso deve ser especificado para enviar uma mensagem JSON.

Tipo: string

Valores válidos: json

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. Quando especificada, a propriedade id no objeto de resposta é definida para esse valor. Se você não usa esse atributo, é possível omitir essa propriedade ou especificar uma string vazia.

Obrigatório: false

Digite: string

Padrão válido: .*

Limites

O tamanho da mensagem é limitado por um tamanho máximo de mensagem do SNS de 256 KB.

Exemplo de entrada: mensagem de string

Este exemplo envia uma mensagem de string. Ele especifica a propriedade opcional sns_topic_arn, que substitui o tópico de destino padrão.

{
    "request": {
        "subject": "Message subject",
        "message": "Message data",
        "sns_topic_arn": "arn:aws:sns:region:account-id:topic2-name"
    },
    "id": "request123"
}
Exemplo de entrada: mensagem JSON

Este exemplo envia uma mensagem como objeto JSON codificado por string que inclui a chave default.

{
    "request": {
        "subject": "Message subject",
        "message": "{ \"default\": \"Message data\" }",
        "message_structure": "json"
    },
    "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

sns/message/status

Exemplo de resultado: sucesso
{
    "response": {
        "sns_message_id": "f80a81bc-f44c-56f2-a0f0-d5af6a727c8a",
        "status": "success"
    },
    "id": "request123"
}
Exemplo de resultado: falha
{
   "response" : {
        "error": "InvalidInputException",
        "error_message": "SNS Topic Arn is invalid",
        "status": "fail"
   },
   "id": "request123"
}

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

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

    Para o requisito de função de grupo, você deve configurar a função para conceder as permissões necessárias e certificar-se de que a função tenha sido adicionada ao grupo. Para obter mais informações, consulte Gerenciar a função de grupo do Greengrass (console) ou Gerenciar a função de grupo do Greengrass (CLI).

  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 conector e configure seus parâmetros.

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

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

Licenças

O conector do SNS 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.

Version (Versão)

Alterações

4

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

3

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

2

Corrija para reduzir o registro excessivo.

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