Implemente las operaciones de la interfaz del conector C2C

Las integraciones gestionadas AWS IoT Device Management definen cuatro operaciones AWS Lambda que debe realizar para calificar como conector. Su conector C2C debe implementar cada una de las siguientes operaciones:

1. AWS.ActivateUser- Managed Integrations for AWS IoT Device Management Service llama a esta API para recuperar un identificador de usuario único a nivel mundial asociado al token OAuth2 .0 proporcionado. Esta operación se puede utilizar opcionalmente para realizar cualquier requisito adicional para el proceso de vinculación de cuentas.

2. AWS.DiscoverDevices- las integraciones gestionadas para el servicio AWS IoT Device Management llaman a esta API a su conector para descubrir los dispositivos de los usuarios

3. AWS.SendCommand- las integraciones gestionadas para el servicio AWS IoT Device Management llaman a esta API a su conector para enviar comandos a los dispositivos de los usuarios

4. AWS.DeactivateUser- las integraciones gestionadas para el servicio AWS IoT Device Management llaman a esta API a su conector para desactivar el token de acceso del usuario y desvincularlo en su servidor de autorización.

Las integraciones gestionadas AWS IoT Device Management siempre invocan 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. Para obtener más información, consulta Invoke in AWS Lambda API Reference.

El tiempo de espera de cada invocación se establece en dos segundos y, si la invocación falla, se volverá a intentar cinco veces.

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);
    };
}

nota

El desarrollador del conector debe implementar las deactivateUser.deactivateUser operacionesactivateUserManager.activateUser(request), deviceDiscoveryManager.listDevices(request)sendCommandManager.sendCommand(request), y enumeradas en el ejemplo anterior.

El siguiente ejemplo detalla una solicitud de conector genérica de las integraciones gestionadas, en la que aparecen campos comunes a todas las interfaces requeridas. En el ejemplo, 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.

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

Encabezados de solicitud predeterminados

Los campos de encabezado predeterminados son los siguientes.

{
    "header": {
        "auth": {                 
            "token": string,    // end user's Access Token
            "type": ENUM ["OAuth2.0"], 
        }
    }
}

Cualquier API alojada en un conector debe procesar los siguientes parámetros de encabezado:

Cabeceras y campos predeterminados

Campo	Obligatorio/opcional	Descripción
header:auth	Sí	Información de autorización proporcionada por el fabricante del conector C2C durante el registro del conector.
header:auth:token	Sí	Token de autorización del usuario generado por el proveedor de servicios en la nube externo y vinculado al connectorAssociationID mismo.
header:auth:type	Sí	El tipo de autorización necesaria.

nota

Todas las solicitudes a su conector llevarán adjunto el token de acceso del usuario final. Puede suponer que la vinculación de cuentas entre el usuario final y el cliente de integraciones gestionadas ya se ha realizado.

Carga de solicitud

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.

Campos de carga útil de solicitud:

• operationName: La operación de una solicitud determinada, igual a uno de los siguientes valores:AWS.ActivateUser,, AWS.SendCommandAWS.DiscoverDevices,AWS.DeactivateUser.

• operationVersion: Cada operación está versionada para permitir su evolución a lo largo del tiempo y proporcionar una definición de interfaz estable para conectores de terceros. Las integraciones gestionadas incluyen un campo de versión en la carga útil de todas las solicitudes.

• connectorId: el ID del conector al que se ha enviado la solicitud.

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. El siguiente es un ejemplo genérico de dicha respuesta:

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

Cada respuesta de operación debe tener el siguiente encabezado común:

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

En la siguiente tabla se muestra el encabezado de respuesta predeterminado:

Cabecera y campo de respuesta predeterminados

Campo	Obligatorio/opcional	Comentario
header:responseCode	Sí	ENUM de valores que indican el estado de ejecución de la solicitud.

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

Las integraciones gestionadas AWS IoT Device Management esperan 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.

Al utilizar la SendConnectorEvent API, se espera que el conector envíe los tipos de eventos de la lista siguiente a los relacionados con AWS.SendCommand las operaciones AWS.DiscoverDevices y las operaciones, así como los eventos proactivos del dispositivo (como el encendido y apagado manual de una luz). Para leer una explicación detallada de estos tipos de eventos y sus casos de usoImplemente AWS. DiscoverDevices operación, consulteImplemente AWS. SendCommand operación, yEnvía eventos del dispositivo con la API SendConnectorEvent.

Por ejemplo, si su conector C2C recibe una DiscoverDevices solicitud, Managed Integrations for AWS IoT Device Management espera que responda de forma sincrónica con el formato de respuesta definido anteriormente. A continuación, debe invocar la SendConnectorEvent API con la estructura de solicitudes definida enImplemente AWS. DiscoverDevices operación, para un evento DEVICE_DISCOVERY. La llamada a la API puede realizarse SendConnectorEvent 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.

nota

Como alternativa, la llamada a la SendConnectorEvent API puede producirse antes de la respuesta de invocación Lambda del conector C2C, si es necesario. Sin embargo, este flujo contradice el modelo asíncrono de desarrollo de software.

• SendConnectorEvent- Su conector lo denomina integraciones administradas para la API de administración de dispositivos de AWS IoT para enviar eventos de dispositivos a las integraciones administradas de AWS IoT Device Management. Las integraciones gestionadas solo aceptan tres tipos de eventos:

  • «DEVICE_DISCOVERY»: esta operación de evento se utilizará para enviar una lista de dispositivos descubiertos a una nube de terceros para obtener un token de acceso específico.

  • «DEVICE_COMMAND_RESPONSE»: esta operación de evento se utilizará para enviar un evento de dispositivo específico como resultado de la ejecución de un comando.

  • «DEVICE_EVENT»: esta operación de evento se utilizará para cualquier evento que se origine en el dispositivo y que no sea el resultado directo de un comando basado en el usuario. Esto puede servir como un tipo de evento general para informar de forma proactiva sobre cambios o notificaciones en el estado del dispositivo.