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 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:
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. En el caso de OAuth 2.0, está asociado al token de OAuth 2.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`- Managed Integrations for AWS IoT Device Management Service llama a esta API a su conector para descubrir los dispositivos de los usuarios
1. `AWS.SendCommand`- Managed Integrations for AWS IoT Device Management service llama a esta API a su conector para enviar comandos a los dispositivos de los usuarios
1. `AWS.DeactivateUser`- Managed Integrations for AWS IoT Device Management service llama a esta API a tu conector para desactivar el token de acceso del usuario y desvincularlo en tu servidor de autorización.
## 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:**
+ **Tiempo de espera:** 2 segundos por invocación
+ **Reintentos: 5 reintentos** en caso de error
## 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);
};
}
```
**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.
## 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"
}
}
}
```
**Parámetros del encabezado**
| | | |
| --- |--- |--- |
| Campo | Required/Optional | 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` | Condicional | Token de autorización del usuario generado por el proveedor de servicios en la nube externo y vinculado al `connectorAssociationID` mismo. Necesario para OAuth 2.0, no está presente para la autorización general. |
| `header:auth:secretsManager` | Condicional | AWS Secrets Manager El ARN y el ID de versión que contienen las credenciales de autorización. Necesario para la autorización general, no está presente para OAuth 2.0. |
| `header:auth:type` | Sí | El tipo de autorización: `OAuth2.0` o. `GeneralAuthorization` |
**nota**
Todas las solicitudes a su conector incluirán información de autorización. En el caso de OAuth 2.0, esto incluye el token de acceso del usuario final. Para la autorización general, esto incluye el AWS Secrets Manager ARN y el ID de versión. Puede suponer que ya se ha establecido la autorización correspondiente.
## 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.
**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. Managed Integrations incluye un campo de versión en la carga útil de todas las solicitudes.
+ `connectorId`: El ID del conector al que se envió 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.
**Example Ejemplo de respuesta genérica**
```
{
"header":{
"responseCode": 200
},
"payload":{
"responseMessage": “Example response!”
}
}
```
**Example Formato de encabezado de respuesta**
```
{
"header": {
"responseCode": Integer
}
}
```
**Cabecera y campo de respuesta predeterminados**
| | | |
| --- |--- |--- |
| Campo | Required/Optional | 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
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).
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
+ Invoca la `SendConnectorEvent` API con un evento DEVICE\_DISCOVERY
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.
**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.
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:
+ **«DEVICE\_DISCOVERY»**: se utiliza para enviar una lista de dispositivos descubiertos en una nube de terceros para obtener un token de acceso específico
+ **«DEVICE\_COMMAND\_RESPONSE»**: se utiliza para enviar un evento de dispositivo específico como resultado de la ejecución de un comando
+ **«DEVICE\_EVENT»: se utiliza para cualquier evento** que se origine en el dispositivo y que no sea el resultado directo de un comando basado en el usuario. Puede servir como un tipo de evento general para informar de forma proactiva sobre cambios o notificaciones en el estado del dispositivo