Implemente operaciones de interfaz de conector C2C

Managed Integrations for AWS IoT Device Management define cuatro operaciones AWS Lambda que debe realizar para calificar como conector. Su conector C2C debe implementar cada una de las siguientes operaciones:

Detalles de la invocación

Managed Integrations for invoca AWS IoT Device Management siempre la función Lambda con una carga útil de cadena JSON durante la acción. AWS Lambda invokeFunction Las operaciones de solicitud deben incluir un operationName campo en cada carga útil de solicitud.

Configuración de invocación:

Ejemplo de implementación

La Lambda que implemente para su conector analizará una de la carga útil operationName de la solicitud e implementará la funcionalidad correspondiente para mapearla a la nube de terceros:

public ConnectorResponse handleRequest(final ConnectorRequest request) 
        throws OperationFailedException {
    Operation operation;
    try {
        operation = Operation.valueOf(request.payload().operationName());
    } catch (IllegalArgumentException ex) {
        throw new ValidationException(
           "Unknown operation '%s'".formatted(request.payload().operationName()), 
           ex
        );
    }

    return switch (operation) {
        case ActivateUser -> activateUserManager.activateUser(request);
        case DiscoverDevices -> deviceDiscoveryManager.listDevices(request);
        case SendCommand -> sendCommandManager.sendCommand(request);
        case DeactivateUser -> deactivateUser.deactivateUser(request);
    };
}

Ejemplos de formatos de solicitud

Los siguientes ejemplos detallan las solicitudes de conectores genéricos de las integraciones gestionadas, en las que aparecen campos comunes a todas las interfaces obligatorias. En los ejemplos, puede ver que hay un encabezado de solicitud y una carga útil de solicitud. Los encabezados de solicitud son comunes en todas las interfaces de operación.

Ejemplo de OAuth 2.0:

{
        "header": {
                "auth": { 
                        "token": "ashriu32yr97feqy7afsaf", 
                        "type": "OAuth2.0"
                }
        },
        "payload":{
                "operationName": "AWS.SendCommand",
                "operationVersion": "1.0",
                "connectorId": "exampleId",
        …
        }
}

Ejemplo de autorización general:

{
        "header": {
                "auth": { 
                        "secretsManager": {
                                "arn": "string",
                                "versionId": "string"
                        },
                        "type": "GeneralAuthorization"
                }
        },
        "payload":{
                "operationName": "AWS.SendCommand",
                "operationVersion": "1.0",
                "connectorId": "exampleId",
        …
        }
}

Encabezados de solicitud predeterminados

Los campos de encabezado predeterminados varían según el tipo de autorización. El conector debe gestionar tanto los encabezados de solicitud de OAuth 2.0 como los de autorización general.

Encabezado predeterminado de OAuth 2.0:

{
    "header": {
        "auth": {
            "token": string,    // End user's Access Token
            "type": "OAuth2.0"
        }
    }
}

Encabezado predeterminado de autorización general:

{
    "header": {
        "auth": {
            "secretsManager": {
                "arn": "string",
                "versionId": "string"
            },
            "type": "GeneralAuthorization"
        }
    }
}

Solicita la carga útil

Además de los encabezados comunes, cada solicitud tendrá una carga útil. Si bien esta carga útil tendrá campos únicos para cada tipo de operación, cada carga útil tiene un conjunto de campos predeterminados que siempre estarán presentes.

Encabezados de respuesta predeterminados

Cada operación responderá con una notificación ACK a las integraciones gestionadas para AWS IoT Device Management que confirme que su conector C2C ha recibido la solicitud y ha empezado a procesarla.

{
 	"header":{
 		"responseCode": 200 
 	},
 	"payload":{
 		"responseMessage": “Example response!”
 	}
}

{
    "header": {
        "responseCode": Integer
    }
}

Campo de encabezado de respuesta

En las distintas interfaces de conector y esquemas de API descritos en este documento, hay un campo responseMessage oMessage. Este es un campo opcional que se utiliza para que el conector C2C Lambda responda con cualquier contexto relacionado con la solicitud y su ejecución. Preferiblemente, cualquier error que dé como resultado un código de estado distinto del código 200 debe incluir un valor de mensaje que describa el error.

Responda a las solicitudes de operación del conector C2C con la API SendConnectorEvent

Managed Integrations for AWS IoT Device Management espera que su conector se comporte de forma asíncrona en todas sus operaciones. AWS.SendCommand AWS.DiscoverDevices Esto significa que la respuesta inicial a estas operaciones simplemente «reconoce» que su conector C2C ha recibido la solicitud.

Con la SendConnectorEvent API, se espera que el conector envíe los tipos de eventos de la siguiente lista para AWS.SendCommand las operaciones AWS.DiscoverDevices y los eventos proactivos del dispositivo (como el encendido y apagado manual de una luz).

Ejemplo de flujo de trabajo

Si su conector C2C recibe una DiscoverDevices solicitud, Managed Integrations for AWS IoT Device Management espera que:

La llamada a la SendConnectorEvent API puede realizarse en cualquier lugar donde tenga acceso a las credenciales Cuenta de AWS Lambda de su conector C2C. El flujo de descubrimiento de dispositivos no se realiza correctamente hasta que Managed Integrations for AWS IoT Device Management reciba este evento.

SendConnectorEvent API

Su conector lo denomina integraciones administradas para que la API AWS IoT Device Management envíe eventos de dispositivos. Solo se aceptan tres tipos de eventos: