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.
# 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.
1. `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
1. `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
1. `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](https://docs.aws.amazon.com//lambda/latest/api/API_Invoke.html) 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` operaciones`activateUserManager.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”,
…
}
}
```
## Cabeceras de solicitud predeterminadas
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.SendCommand``AWS.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
}
}
```
La siguiente tabla 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` o`Message`. 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 uso[Implemente AWS. DiscoverDevices operación](discover-devices-op.md), consulte[Implemente AWS. SendCommand operación](send-command-op.md), y[Envía eventos del dispositivo con la API SendConnectorEvent](send-connector-events.md).
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 en[Implemente AWS. DiscoverDevices operación](discover-devices-op.md), para un evento DEVICE\$1DISCOVERY. 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\$1DISCOVERY**»: 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\$1COMMAND\$1RESPONSE**»: 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\$1EVENT**»: 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.