实现 C2C 连接器接口操作

的托管集成 AWS IoT Device Management 定义了您 AWS Lambda 必须处理的四个操作才有资格成为连接器。您的 C2C 连接器必须实现以下每项操作：

1. AWS.ActivateUser- AWS IoT Device Management 服务的托管集成会调用此 API 来检索与所提供的 OAuth2 .0 令牌关联的全局唯一用户标识符。可以选择使用此操作来执行账户关联过程的任何其他要求。

2. AWS.DiscoverDevices-AWS IoT Device Management 服务的托管集成会将此 API 调用到您的连接器以发现用户的设备

3. AWS.SendCommand-AWS IoT Device Management 服务的托管集成会将此 API 调用到您的连接器，以便为用户设备发送命令

4. AWS.DeactivateUser-AWS IoT Device Management 服务的托管集成会将此 API 调用您的连接器，以停用用户的访问令牌，以便在您的授权服务器中取消链接。

的托管集成 AWS IoT Device Management 始终通过操作调用带有 JSON 字符串负载的 Lambda 函数。 AWS Lambda invokeFunction请求操作必须在每个请求负载中包含一个operationName字段。有关更多信息，请参阅 AWS Lambda API 参考中的调用。

每次调用超时设置为两秒，如果调用失败，则将重试五次。

您为连接器实现的 Lambda 将operationName从请求有效负载中解析一个，并实现相应的功能以映射到第三方云：

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

注意

连接器的开发者必须实现前面示例中列出的activateUserManager.activateUser(request)deviceDiscoveryManager.listDevices(request)sendCommandManager.sendCommand(request)、、和deactivateUser.deactivateUser操作。

以下示例详细介绍了来自托管集成的通用连接器请求，其中包含每个必需接口的公共字段。从示例中，您可以看到既有请求标头，又有请求负载。请求标头在每个操作接口中都很常见。

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

默认请求标头

默认标题字段如下所示。

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

连接器托管的任何 API 都必须处理以下标头参数：

默认标题和字段

字段	必填/可选	描述
header:auth	是	C2C 连接器生成器在连接器注册期间提供的授权信息。
header:auth:token	是	由第三方云提供商生成并链接到的用户的授权令牌connectorAssociationID。
header:auth:type	是	所需的授权类型。

注意

对您的连接器的所有请求都将附加最终用户的访问令牌。您可以假设最终用户与托管集成客户之间已经存在账户关联。

请求负载

除了常用标头外，每个请求都将有一个有效负载。虽然此有效载荷对每种操作类型都有唯一的字段，但每个有效载荷都有一组默认字段，这些字段将始终存在。

请求有效载荷字段：

• operationName：给定请求的操作，等于以下值之一：AWS.ActivateUser、AWS.SendCommand、AWS.DiscoverDevices、AWS.DeactivateUser。

• operationVersion：每个操作都有版本控制，以允许其随着时间的推移而演变，并为第三方连接器提供稳定的接口定义。托管集成在所有请求的有效载荷中传递一个版本字段。

• connectorId：已向其发送请求的连接器的 ID。

默认响应标头

每项ACK操作都将通过 AWS IoT Device Management 的托管集成进行响应，确认您的 C2C 连接器已收到请求并开始处理请求。以下是上述回复的通用示例：

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

每个操作响应都必须具有以下通用标头：

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

下表列出了默认的响应标头：

默认响应标头和字段

字段	必填/可选	评论
header:responseCode	是	表示请求执行状态的值的枚举。

在本文档中描述的各种连接器接口和 API 架构中，都有一个responseMessage或Message字段。这是一个可选字段，用于 C2C 连接器 Lambda 使用与请求及其执行有关的任何上下文进行响应。最好是，任何导致状态码之外的错误都200应包含描述错误的消息值。

使用 API 响应 C2C 连接器操作请求 SendConnectorEvent

的托管集成要求 AWS IoT Device Management 您的连接器在每个 and 操作中都以异步方式运行AWS.SendCommand。AWS.DiscoverDevices这意味着对这些操作的初始响应只是 “确认” 您的 C2C 连接器已收到请求。

使用 SendConnectorEvent API，您的连接器应将以下列表中的事件类型发送到 for and operations，以及主动设备事件（例如手动开启和关闭灯光）。AWS.DiscoverDevices AWS.SendCommand要阅读有关这些事件类型及其用例的详细说明，请参阅实施 AWS。 DiscoverDevices 操作实施 AWS。 SendCommand 操作、和使用 SendConnectorEvent API 发送设备事件。

例如，如果您的 C2C 连接器收到DiscoverDevices请求，则 AWS IoT Device Management 的托管集成希望它与上面定义的响应格式同步响应。然后，您必须使用中实施 AWS。 DiscoverDevices 操作定义的请求结构为 DEVICE_DISCOVERY 事件调用 SendConnectorEvent API。API 调用可以在任何您有权访问 C2C 连接器 AWS 账户 Lambda 凭证的地方进行。SendConnectorEvent在 AWS IoT Device Management 的托管集成收到此事件之前，设备发现流程才会成功。

注意

或者，如有必要，SendConnectorEventAPI 调用可以在 C2C 连接器 Lambda 调用响应之前进行。但是，这种流程与软件开发的异步模型相矛盾。

• SendConnectorEvent-您的连接器调用 AWS IoT Device Management API 的托管集成，将设备事件发送到 AWS IoT Device Management 的托管集成。托管集成仅接受三种类型的事件：

  • “DEV ICE_DISCOVERY” — 此事件操作应用于发送第三方云中发现的设备列表以获取特定的访问令牌。

  • “DEVICE_COMMAND_RESPONSE” — 此事件操作应用于发送作为命令执行结果的特定设备事件。

  • “DEVICE_EV ENT”-此事件操作应用于源自设备且不是基于用户的命令的直接结果的任何事件。这可以作为一种常规事件类型，用于主动报告设备状态变化或通知。