本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 实现 C2C 连接器接口操作
<a name="connector-operations-overview"></a>

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

1. `AWS.ActivateUser`- AWS IoT Device Management 服务托管集成调用此 API 来检索全球唯一的用户标识符。对于 OAuth 2.0，这与提供的 OAuth 2.0 令牌相关联。可以选择使用此操作来执行账户关联过程的任何其他要求。

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

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

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

## 调用详情
<a name="invocation-details"></a>

的托管集成 AWS IoT Device Management 始终通过操作调用带有 JSON 字符串负载的 Lambda 函数。 AWS Lambda `invokeFunction`请求操作必须在每个请求负载中包含一个`operationName`字段。

**调用设置：**
+ **超时：**每次调用 2 秒
+ **重试：失**败时重试 5 次

## 实现示例
<a name="implementation-example"></a>

您为连接器实现的 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`操作。

## 请求格式示例
<a name="request-format-examples"></a>

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

**OAuth 2.0 示例：**

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

**通用授权示例：**

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

## 默认请求标头
<a name="default-request-headers"></a>

默认标题字段因授权类型而异。您的连接器必须同时处理 OAuth 2.0 和通用授权请求标头。

**OAuth 2.0 默认标头：**

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

**通用授权默认标头：**

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


**标题参数**  

|  |  |  | 
| --- |--- |--- |
| 字段 | Required/Optional | 描述 | 
| `header:auth` | 是 | C2C 连接器生成器在连接器注册期间提供的授权信息。 | 
| `header:auth:token` | 有条件 | 由第三方云提供商生成并链接到的用户的授权令牌`connectorAssociationID`。对于 OAuth 2.0 来说是必需的，对于 “一般授权” 则不存在。 | 
| `header:auth:secretsManager` | 有条件 | AWS Secrets Manager ARN 和包含授权凭证的版本 ID。通用授权是必需的，OAuth 2.0 不存在。 | 
| `header:auth:type` | 是 | 授权类型：`OAuth2.0`或`GeneralAuthorization`。 | 

**注意**  
对您的连接器的所有请求都将包含授权信息。对于 OAuth 2.0，这包括最终用户的访问令牌。对于一般授权，这包括 AWS Secrets Manager ARN 和版本 ID。您可以假设已经建立了相应的授权。

## 请求有效负载
<a name="request-payload"></a>

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

**请求有效载荷字段：**
+ `operationName`：给定请求的操作，等于以下值之一：`AWS.ActivateUser`、`AWS.SendCommand`、`AWS.DiscoverDevices`、`AWS.DeactivateUser`。
+ `operationVersion`：每个操作都经过版本控制，以允许其随着时间的推移而演变，并为第三方连接器提供稳定的接口定义。托管集成在所有请求的有效负载中传递一个版本字段。
+ `connectorId`：已向其发送请求的连接器的 ID。

## 默认响应标头
<a name="default-response-headers"></a>

每项`ACK`操作都将通过 AWS IoT Device Management 的托管集成进行响应，确认您的 C2C 连接器已收到请求并开始处理请求。

**Example 通用响应示例**  

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

**Example 响应标头格式**  

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


**默认响应标头和字段**  

|  |  |  | 
| --- |--- |--- |
| 字段 | Required/Optional | 评论 | 
| `header:responseCode` | 是 | 表示请求执行状态的值的枚举。 | 

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

## 使用 API 响应 C2C 连接器操作请求 SendConnectorEvent
<a name="connector-operation-requests"></a>

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

使用 `SendConnectorEvent` API，您的连接器应发送以下列表中的事件类型，用于`AWS.DiscoverDevices`和`AWS.SendCommand`操作以及主动设备事件（例如手动开启和关闭灯光）。

如果您的 C2C 连接器收到`DiscoverDevices`请求，则托管集成 AWS IoT Device Management 预计该请求：
+ 使用上面定义的响应格式同步响应
+ 使用 DEVICE\_DISCOVERY 事件调用 `SendConnectorEvent` API

`SendConnectorEvent`API 调用可以在您有权访问 C2C 连接器 AWS 账户 Lambda 凭证的任何地方进行。在 AWS IoT Device Management 的托管集成收到此事件之前，设备发现流程才会成功。

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

您的连接器调用此托管集成 AWS IoT Device Management API 来发送设备事件。仅接受 3 种类型的事件：
+ **“DEVICE\_DISCOVERY”**-用于发送第三方云中发现的设备列表以获取特定的访问令牌
+ **“DEVICE\_COMMAND\_RESPONSE”-用于发送作为命令**执行结果的特定设备事件
+ **“DEVICE\_EVENT”**-用于源自设备且不是基于用户的命令的直接结果的任何事件。这可以用作常规事件类型，用于主动报告设备状态变化或通知