Introducción a los conectores de Greengrass (CLI) - AWS IoT Greengrass
Requisitos previosCrear un secreto en Secrets ManagerCrear una versión y una definición del recursoCrear una versión y una definición del conectorCreación de un paquete de implementación de la función de LambdaCreación de una función de LambdaCrear una versión y una definición de la funciónCrear una versión y una definición de la suscripciónCree una versión del grupoCrear una implementaciónProbar la soluciónVéase también

AWS IoT Greengrass Version 1 entró en la fase de vida útil prolongada el 30 de junio de 2023. Para obtener más información, consulte la política de mantenimiento de AWS IoT Greengrass V1 Después de esta fecha, AWS IoT Greengrass V1 no se publicarán actualizaciones que proporcionen funciones, mejoras, correcciones de errores o parches de seguridad. Los dispositivos que se ejecuten AWS IoT Greengrass V1 no se verán afectados y seguirán funcionando y conectándose a la nube. Le recomendamos encarecidamente que migre a AWS IoT Greengrass Version 2, ya que añade importantes funciones nuevas y es compatible con plataformas adicionales.

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Introducción a los conectores de Greengrass (CLI)

Esta característica está disponible para AWS IoT Greengrass Core versión 1.7 y posteriores.

Este tutorial muestra cómo utilizar la AWS CLI para trabajar con conectores.

Utilice conectores para acelerar el ciclo de vida de desarrollo. Los conectores son módulos precompilados y reutilizables que puede simplificar la interacción con los servicios, los protocolos y los recursos. Pueden ayudarle a implementar la lógica de negocio en los dispositivos de Greengrass con mayor rapidez. Para obtener más información, consulte Integración con servicios y protocolos mediante conectores de Greengrass.

En este tutorial configurará e implementará el conector de Notificaciones de Twilio. El conector recibe la información del mensaje de Twilio como datos de entrada y, a continuación, desencadena un mensaje de texto de Twilio. El flujo de datos se muestra en el siguiente diagrama.

Flujo de datos de la función de Lambda al conector de Notificaciones de Twilio a Twilio.

Después de configurar el conector, debe crear una función de Lambda y una suscripción.

  • La función evalúa los datos simulados desde un sensor de temperatura. Publica condicionalmente la información del mensaje de Twilio a un tema de MQTT. Este es el tema al que se suscribe el conector.

  • La suscripción permite que la función se publique en el tema y que el conector reciba datos del tema.

El conector de Notificaciones de Twilio necesita un token de autenticación de Twilio para interactuar con la API de Twilio. El token es un secreto de tipo de texto creado en AWS Secrets Manager y al que se hace referencia desde un recurso de grupo. Esto permite a AWS IoT Greengrass crear una copia local del secreto en el núcleo de Greengrass, donde se cifra y se convierte en disponible para el conector. Para obtener más información, consulte Implementación de secretos en el núcleo de AWS IoT Greengrass.

El tutorial contiene los siguientes pasos generales:

  1. Crear un secreto en Secrets Manager

  2. Crear una versión y una definición del recurso

  3. Crear una versión y una definición del conector

  4. Creación de un paquete de implementación de la función de Lambda

  5. Creación de una función de Lambda

  6. Crear una versión y una definición de la función

  7. Crear una versión y una definición de la suscripción

  8. Cree una versión del grupo

  9. Crear una implementación

  10. Probar la solución

Completar el tutorial debería tomarle aproximadamente 30 minutos.

Uso de la API de AWS IoT Greengrass

Es útil para comprender los siguientes patrones a la hora de trabajar con componentes de grupo y grupos de Greengrass (por ejemplo, los conectores, las funciones y los recursos del grupo).

  • En la parte superior de la jerarquía, un componente tiene un objeto de definición que es un contenedor de los objetos de versión. A su vez, una versión es un contenedor para los conectores, las funciones u otros tipos de componentes.

  • Al realizar una implementación en el núcleo de Greengrass, implementará un grupo específico. Una versión de grupo puede contener una versión de cada tipo de componente. Un núcleo es obligatorio, pero los demás se incluyen según sea necesario.

  • Las versiones son inmutables, por lo que debe crear nuevas versiones cuando desee realizar cambios.

sugerencia

Si recibe un error al ejecutar un comando de la AWS CLI, añada el parámetro --debug y, a continuación, vuelva a ejecutar el comando para obtener más información sobre el error.

La API de AWS IoT Greengrass le permite crear varias definiciones para un tipo de componente. Por ejemplo, puede crear un objeto FunctionDefinition cada vez que cree un parámetro FunctionDefinitionVersion, o bien puede añadir nuevas versiones a una definición existente. Esta flexibilidad le permite personalizar su sistema de administración de versiones.

Requisitos previos

Para completar este tutorial, se necesita lo siguiente:

  • Un grupo de Greengrass y un núcleo de Greengrass (v1.9.3 o posterior). Para obtener información acerca de cómo crear un núcleo y un grupo de Greengrass, consulte Introducción a AWS IoT Greengrass. El tutorial de introducción también incluye pasos para instalar el software AWS IoT Greengrass Core.

  • Python 3.7 instalado en el dispositivo central de AWS IoT Greengrass.

  • AWS IoT Greengrass debe configurarse para admitir secretos locales, como se describe en Requisitos de secretos.

    nota

    Este requisito incluye permitir el acceso a sus secretos de Secret Manager. Si utiliza el rol de servicio predeterminado de Greengrass, Greengrass tiene permiso para obtener los valores de los secretos cuyos nombres empiecen por greengrass-.

  • Un SID de una cuenta de Twilio, un token de autenticación y un número de teléfono habilitado para Twilio. Después de crear un proyecto de Twilio, estos valores están disponibles en el panel del proyecto.

    nota

    Puede utilizar una cuenta de prueba de Twilio. Si utiliza una cuenta de prueba, debe añadir números de teléfono de destinatarios que no sean de Twilio a una lista de números de teléfono verificados. Para obtener más información, consulte Cómo trabajar con su cuenta de prueba gratuita de Twilio.

Paso 1: Crear un secreto de Secrets Manager

En este paso, utilice la API de AWS Secrets Manager para crear un secreto de secreto para su token de autenticación de Twilio.

  1. En primer lugar, cree el secreto.

    • Reemplace twilio-auth-token por su token de autenticación de Twilio.

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

    De forma predeterminada, el rol de servicio Greengrass permite a AWS IoT Greengrass obtener el valor de los secretos con nombres que comienzan por greengrass-. Para obtener más información, consulte requisitos de secretos.

  2. Copie el ARN del secreto de la salida. Puede utilizar esto para crear el recurso de secretos y configurar el conector de Notificaciones de Twilio.

Paso 2: Crear una versión y una definición del recurso

En este paso, utilice la API de AWS IoT Greengrass para crear un recurso de secretos para el secreto de Secrets Manager.

  1. Cree una definición de recurso que incluya una versión inicial.

    • Reemplace secret-arn por el ARN del secreto que copió en el paso anterior.

     

    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. Copie el parámetro LatestVersionArn de la definición de recurso de la salida. Este valor se usa para añadir la versión de la definición de recurso a la versión de grupo que implementó en el núcleo.

Paso 3: Crear una versión y una definición del conector

En este paso va a configurar parámetros para el conector Notificaciones de Twilio.

  1. Cree una definición de conector con una versión inicial.

    • Reemplace account-sid por el SID de la cuenta de Twilio.

    • Reemplace secret-arn por el ARN del secreto del Secrets Manager. El conector utiliza esto para obtener el valor del secreto local.

    • Reemplace phone-number por el número de teléfono habilitado para Twilio. Twilio lo utiliza para iniciar el mensaje de texto. Esto se puede anular en la carga de mensajes de entrada. Use el siguiente 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 es el ID que usó en el paso anterior para crear el recurso de secretos.

  2. Copie el parámetro LatestVersionArn de la definición de conector de la salida. Este valor se usa para añadir la versión de la definición de conector a la versión de grupo que se implementa en el núcleo.

Paso 4: Crear un paquete de implementación de la función de Lambda

Para crear una función de Lambda, primero debe crear un paquete de implementación de funciones de Lambda que contenga el código de la función y las dependencias. Las funciones de Lambda de Greengrass requieren el SDK de AWS IoT Greengrass Core para tareas como la comunicación con los mensajes de MQTT en el entorno principal y el acceso a los secretos locales. En este tutorial se crea una característica de Python para que utilices la versión Python del SDK en el paquete de implementación.

  1. Desde la página de descargas del Core SDK AWS IoT Greengrass, descargue el SDK AWS IoT Greengrass básico para Python en su ordenador.

  2. Descomprima el paquete descargado para obtener el SDK. El SDK es la carpeta greengrasssdk.

  3. Guarde la siguiente función de código de Python en un archivo local llamado "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. Comprima en un archivo ZIP los siguientes elementos en un archivo denominado "temp_monitor_python.zip". Al crear el archivo ZIP, incluya únicamente el código y sus dependencias, no la carpeta donde se encuentran.

    • temp_monitor.py. Lógica de la aplicación.

    • greengrasssdk. Biblioteca necesaria para las funciones de Lambda de Python Greengrass que publican mensajes MQTT.

    Este es el paquete de implementación de la función de Lambda.

Paso 5: Crear una función de Lambda

Ahora, cree una función de Lambda que use el paquete de implementación.

  1. Cree un rol de IAM para poder pasar el ARN del rol cuando cree la función.

    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 Greengrass no utiliza este rol, ya que los permisos de las funciones de Lambda de Greengrass se especifican en la función de rol de grupo de Greengrass. En este tutorial, va a crear un rol vacío.

  2. Copie la Arn del resultado.

  3. Utilice la API de AWS Lambda para crear la función TempMonitor. El siguiente comando da por hecho que el archivo ZIP está en el directorio actual.

    • Reemplace role-arn por el Arn que ha copiado.

    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. Publique una versión de la función.

    aws lambda publish-version --function-name TempMonitor --description 'First version'

  5. Cree un alias a la versión publicada.

    Los grupos de Greengrass pueden hacer referencia a una función de Lambda por versión o alias (recomendado). El uso de un alias facilita la gestión de las actualizaciones del código porque no tiene que cambiar la tabla de suscripción o la definición del grupo cuando se actualiza el código de la función. En su lugar, basta con apuntar el alias a la nueva versión de la función.

    nota

    AWS IoT Greengrass no admite alias de Lambda; para versiones de $LATEST.

    aws lambda create-alias --function-name TempMonitor --name GG_TempMonitor --function-version 1

  6. Copie la AliasArn del resultado. Este valor se usa al configurar la función para AWS IoT Greengrass y al crear una suscripción.

Ahora está listo para configurar la función para AWS IoT Greengrass.

Paso 6: Crear una versión y una definición de la función

Para utilizar una función de Lambda en una AWS IoT Greengrass core, debe crear una versión de la definición de función que haga referencia a la función de Lambda por alias y defina la configuración en el nivel de grupos. Para obtener más información, consulte Control de la ejecución de funciones de Greengrass Lambda utilizando la configuración específica del grupo.

  1. Cree una definición de función que incluya una versión inicial.

    • Reemplace alias-arn por el AliasArn que ha copiado al crear el 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. Copie la LatestVersionArn del resultado. Este valor se usa para añadir la versión de la definición de función a la versión de grupo que implementó en el núcleo.

  3. Copie la Id del resultado. Este valor se usa más tarde al actualizar la función.

Paso 7: Crear una versión y una definición de la suscripción

En este paso añadirá una suscripción que habilita la función de Lambda para enviar datos de entrada al conector. El conector define los temas de MQTT a los que se suscribe, por lo que esta suscripción utiliza uno de los temas. Este es el mismo tema en el que se publica la función de ejemplo.

En este tutorial también creará suscripciones que permitan a la función recibir lecturas de temperatura simuladas de AWS IoT y permitan a AWS IoT recibir información sobre el estado del conector.

  1. Cree una definición de suscripción que contenga una versión inicial que incluya las suscripciones.

    • Reemplace alias-arn por el AliasArn que ha copiado al crear el alias para la función. Utilice este ARN para las dos suscripciones que lo utilizan.

     

    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. Copie la LatestVersionArn del resultado. Este valor se usa para añadir la versión de la definición de suscripción a la versión de grupo que implementó en el núcleo.

Paso 8: Crear una versión del grupo

Ahora, puede crear una versión de grupo que contenga todos los elementos que desea implementar. Para ello, cree una versión de grupo que haga referencia a la versión de destino de cada tipo de componente.

En primer lugar, obtenga el ID de grupo y el ARN de la versión de la definición del núcleo. Estos valores son necesarios para crear la versión de grupo.

  1. Obtenga el ID del grupo y la última versión del grupo:

    1. Obtenga los ID de la versión de grupo y grupo de Greengrass de destino. En este procedimiento, suponemos que estos son el último grupo y la última versión de grupo. La siguiente consulta devuelve el grupo creado más recientemente.

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

      También puede hacer la consulta por nombre. No es necesario que los nombres de grupo sean únicos, por lo que podrían devolverse varios grupos.

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

      También puede encontrar estos valores en la consola de AWS IoT. El ID de grupo se muestra en la página Settings (Configuración) del grupo. Los ID de versión del grupo se muestran en la pestaña Implementaciones del grupo.

    2. Copie el Id del grupo de destino de la salida. Puede utilizar esto para obtener la versión de la definición de núcleo y al implementar el grupo.

    3. Copie el LatestVersion del resultado, que es el ID de la última versión añadida al grupo. Puede utilizar esto para obtener la versión de la definición de núcleo.

  2. Obtenga el ARN de la versión de la definición principal:

    1. Obtenga la versión de grupo. En este paso, suponemos que la última versión de grupo incluye una versión de la definición de núcleo.

      • Reemplace id-grupo con el Id que ha copiado para el grupo.

      • Reemplace group-version-id por el parámetro LatestVersion que ha copiado para el grupo.

      aws greengrass get-group-version \
--group-id group-id \
--group-version-id group-version-id

    2. Copie la CoreDefinitionVersionArn del resultado.

  3. Cree una versión de grupo.

    • Reemplace id-grupo con el Id que ha copiado para el grupo.

    • Reemplace core-definition-version-arn por el CoreDefinitionVersionArn que ha copiado para la nueva versión de la definición de núcleo.

    • Reemplace resource-definition-version-arn por el parámetro LatestVersionArn que ha copiado para la definición del recurso.

    • Reemplace connector-definition-version-arn con el valor LatestVersionArn que copió para la definición de conector.

    • Reemplace function-definition-version-arn por el parámetro LatestVersionArn que ha copiado para la definición de función.

    • Reemplace subscription-definition-version-arn por el parámetro LatestVersionArn que ha copiado para la definición de suscripción.

    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. Copie el valor de Version del resultado. Este es el ID de la versión del grupo. Este valor se usa para implementar la versión de grupo.

Paso 9: Crear una implementación

Implemente el grupo en el dispositivo del núcleo.

  1. Asegúrese de que el daemon de AWS IoT Greengrass se está ejecutando en el terminal del dispositivo del núcleo.

    1. Para comprobar si el demonio está en ejecución:

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

      Si la salida contiene una entrada root para /greengrass/ggc/packages/1.11.6/bin/daemon, el demonio está en ejecución.

    2. Iniciar el daemon:

      cd /greengrass/ggc/core/
sudo ./greengrassd start

  2. Cree una implementación de .

    • Reemplace id-grupo con el Id que ha copiado para el grupo.

    • Reemplace id-versión-grupo con el Version que ha copiado para el nuevo grupo.

    aws greengrass create-deployment \
--deployment-type NewDeployment \
--group-id group-id \
--group-version-id group-version-id

  3. Copie la DeploymentId del resultado.

  4. Obtenga el estado de las implementaciones.

    • Reemplace id-grupo con el Id que ha copiado para el grupo.

    • Reemplace deployment-id por el parámetro DeploymentId que ha copiado para la implementación.

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

    Si el estado es Success, la implementación fue correcta. Para obtener ayuda sobre la resolución de problemas, consulte Solución de problemas de AWS IoT Greengrass.

Probar la solución

  1. En la página de inicio de la consola AWS IoT, elija Pruebas.

  2. Para Suscribirse al tema, utilice los siguientes valores y, a continuación, seleccione Suscribirse. El conector Notificaciones de Twilio publica información sobre el estado en este tema.

    Propiedad

    Valor

    Subscription topic

    twilio/message/status

    Visualización de la carga de MQTT

    Display payloads as strings

  3. Para Publicar en tema, utilice los siguientes valores y, a continuación, seleccione Publicar para invocar la función.

    Propiedad

    Valor

    Tema

    temperature/input

    Mensaje

    Sustituya recipient-name con un nombre y recipient-phone-number con el número de teléfono del destinatario del mensaje de texto. Ejemplo: +12345000000

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

    Si utiliza una cuenta de prueba, debe añadir números de teléfono de destinatarios que no sean de Twilio a una lista de números de teléfono verificados. Para obtener más información, consulte Verificar su número de teléfono personal.

    Si se ejecuta correctamente, el destinatario recibe el mensaje de texto y la consola muestra el estado success de los datos de salida.

    Ahora, cambie el valor de temperature en el mensaje de entrada a 29 y publíquelo. Dado que es menos de 30, la función TempMonitor no activa un mensaje de Twilio.

Véase también