本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Cloud-to-Cloud (C2C) 连接器 cloud-to-cloud连接器允许您创建和促进第三方设备与之间的双向通信。 AWS **Topics** + [什么是 cloud-to-cloud (C2C) 连接器？](#concepts-what-is-c2c-connector) + [C2C 连接器目录是什么？](#concepts-connector-catalog) + [AWS Lambda 用作 C2C 连接器](#lambda-connector) + [托管集成连接器工作流程](#c2c-workflow) + [使用 C2C (cloud-to-cloud) 连接器的指导原则](#c2c-cloud-connector-disclaimer) + [构建 C2C（云到云）连接器](concepts-building-connector.md) + [使用 C2C（云到云）连接器](use-c2c-create-cloud-connector.md) ## 什么是 cloud-to-cloud (C2C) 连接器？ cloud-to-cloud连接器是一种预先构建的软件包，可将安全地链接 AWS 云 到第三方云提供商的端点。使用 C2C 连接器，解决方案提供商可以利用 AWS IoT Device Management 的托管集成来控制连接到第三方云的设备。 托管集成包括连接器目录， AWS 客户可以在其中查看和选择他们想要集成的连接器。有关更多信息，请参阅 [C2C 连接器目录是什么？](#concepts-connector-catalog)。 托管集成要求将每个连接器作为一个 AWS Lambda 功能来实现。 ## C2C 连接器目录是什么？ AWS IoT Device Management 的托管集成连接器目录是一系列 C2C 连接器，可促进 AWS IoT Device Management 的托管集成与第三方云提供商之间的双向通信。您可以在 AWS 管理控制台 或中查看连接器 AWS CLI。 **使用控制台查看托管集成连接器目录** 1. 打开[托管集成控制](https://console.aws.amazon.com/iot/home#/managed-integrations/intro)台 1. 在左侧导航窗格中，选择**托管集成** 1. 在托管集成控制台的左侧导航窗格中，选择**目录**。 ## AWS Lambda 用作 C2C 连接器 每个 C2C 连接器 Lambda 函数在托管集成和第三方平台上的相应操作之间转换和传输命令和事件。有关 Lambda 的更多信息，请参阅[什么是](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)。 AWS Lambda 例如，假设最终用户拥有由第三方 OEM 制造的智能灯泡。借助 C2C 连接器，最终用户可以通过托管集成平台发出开启或关闭此灯的命令。然后，该命令将被转发到连接器中托管的 Lambda 函数，该函数会将请求转换为针对第三方平台的 API 调用，以打开或关闭设备。 当您调用 API 时，需要使用 Lambda 函数。`CreateCloudConnector`部署到 Lambda 函数中的代码必须实现中提到的所有接口和功能。[构建 C2C（云到云）连接器](concepts-building-connector.md) ## 托管集成连接器工作流程 开发人员必须使用托管集成注册 C2C 连接器。 AWS IoT Device Management此注册过程会创建逻辑连接器资源，客户可以访问该资源以使用该连接器。 **注意** C2C 连接器是在托管集成中为 AWS IoT Device Management 创建的一组元数据，用于描述连接器。 下图描述了 C2C 连接器在将命令从移动应用程序发送到连接云的设备时所扮演的角色。C2C 连接器充当 AWS IoT Device Management 托管集成和第三方云平台之间的转换层。 ![\[连接器工作流程\]](http://docs.aws.amazon.com/zh_cn/iot-mi/latest/devguide/images/app-to-oem-device-workflow.png) ## 使用 C2C (cloud-to-cloud) 连接器的指导原则 您创建的任何 C2C 连接器都是您的内容，而您访问的由其他客户创建的任何 C2C 连接器都是第三方内容。 AWS 不创建或管理任何 C2C 连接器作为托管集成的一部分。 您可以与其他托管集成客户共享您的 C2C 连接器。如果您这样做，则您授权 AWS 作为您的服务提供商在 AWS 控制台上列出这些 C2C 连接器和相关联系信息，并且您知道其他 AWS 客户可能会与您联系。您全权负责授予客户访问您的 C2C 连接器的权限，以及管理其他 AWS 客户访问您的 C2C 连接器的任何条款。 # 构建 C2C（云到云）连接器 以下各节介绍为 AWS IoT Device Management 的托管集成构建 C2C（云到云）连接器的步骤。 **Topics** + [先决条件](#c2c-connector-prerequisites) + [C2C 连接器要求](#c2c-connector-requirements) + [OAuth 2.0 账户关联要求](concepts-account-linking.md) + [实现 C2C 连接器接口操作](connector-operations-overview.md) + [调用你的 C2C 连接器](allow-iot-smart-home.md) + [为您的 IAM 角色添加权限](adding-permissions-to-iam-role.md) + [手动测试您的 C2C 连接器](manually-testing-connector.md) ## 先决条件 在创建 C2C（云到云）连接器之前，您需要满足以下条件： + AWS 账户 用于托管您的 C2C 连接器并通过托管集成进行注册。有关更多信息，请参阅[创建 AWS 账户](https://docs.aws.amazon.com//accounts/latest/reference/manage-acct-creating.html)。 + 在构建连接器时，您需要某些 IAM 权限。要再次使用 + 确保连接器所针对的第三方云提供商支持 OAuth 2.0 授权。有关更多信息，请参阅 [OAuth 2.0 账户关联要求](concepts-account-linking.md)。 此外，要测试连接器，连接器的开发人员必须具备以下条件： + 来自第三方云的客户端 ID，用于与 C2C 连接器关联 + 来自第三方云的客户端密钥，用于与您的 C2C 连接器关联 + OAuth 2.0 授权网址 + OAuth 2.0 代币网址 + 您的第三方 API 所需的任何 API 密钥 + 您的第三方 API 注册或托管的 OAuth 回传网址许可名单所需的任何 API 密钥。 AWS一些第三方明确 OAuth 将重定向 URL 列入许可名单，而另一些第三方则有用户可以登录和注册该 OAuth URL 的工作流程。请咨询特定的第三方，了解将托管集成 OAuth 重定向端点列入许可名单需要什么 ### 所需的权限 在构建连接器时，您需要某些 IAM 权限。除了操作`iotmanagedintegrations:`权限外，您还需要以下权限： + [CreateAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateAccountAssociation.html)、[CreateConnectorDestination[GetAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetAccountAssociation.html)](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateConnectorDestination.html)、和 [StartAccountAssociationRefresh](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_StartAccountAssociationRefresh.html)，要求 `secretsmanager:GetSecretValue` + [CreateCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateCloudConnector.html) 需要 `lambda:Invoke` 有关`iotmanagedintegrations:`权限和操作的更多信息，请参阅[AWS 托管集成定义的操作](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiotmanagedintegrations.html#awsiotmanagedintegrations-actions-as-permissions) ## C2C 连接器要求 您开发的 [C2C 连接器](concepts-c2c-connector.md#concepts-what-is-c2c-connector)促进了 AWS IoT Device Management 的托管集成与第三方供应商云之间的双向通信。连接器必须实现托管集成的接口，AWS IoT Device Management 才能代表最终用户执行操作。这些接口提供了发现最终用户设备、启动从 AWS IoT Device Management 托管集成发送的设备命令以及基于访问令牌识别用户的功能。为了支持设备操作，连接器必须管理 AWS IoT Device Management 托管集成与相关第三方平台之间的请求和响应消息的转换。 **以下是 C2C 连接器的要求：** + 第三方授权服务器必须符合 OAuth 2.0 标准以及中列出的配置[OAuth 配置要求](concepts-account-linking.md#oauth-config-requirements)。 + 需要使用 C2C 连接器来解释物质数据模型 AWS 实现中的标识符，并且必须发出符合物质数据模型 AWS 实现的响应和事件。有关更多信息，请参阅 [AWS 物质数据模型的实现](matter-data-model.md)。 + C2C 连接器必须能够通过身份验证调用 AWS IoT Device Manag APIs ement 的托管集成。`SigV4`对于 SendConnectorEvent 通过 API 发送的异步事件，必须使用用于注册连接器的相同 AWS 账户 凭据来签署相关 SendConnectorEvent 请求。 + 连接器必须实现`AWS.ActivateUser`、`AWS.DiscoverDevices``AWS.SendCommand`、和`AWS.DeactivateUser`操作。 + 当您的 C2C 连接器收到与设备命令响应或设备发现相关的第三方事件时，它必须将其转发到与 API 的托管集成。`SendConnectorEvent`有关这些事件和 `SendConnectorEvent` API 的更多信息，请参阅[SendConnectorEvent](https://amazonaws.com/iot-mi/latest/APIReference/API_SendConnectorEvent.html)。 **注意** `SendConnectorEvent`API 是托管集成 SDK 的一部分，用于代替手动构建和签署请求。 # OAuth 2.0 账户关联要求 每个 C2C 连接器都依赖 OAuth 2.0 授权服务器对最终用户进行身份验证。通过此服务器，最终用户将其第三方账户与客户的设备平台关联起来。账户关联是最终用户使用 C2C 连接器支持的设备所需的第一步。有关账户关联和 OAuth 2.0 中不同角色的更多信息，请参阅[账户关联角色](roles-account-linking.md)。 虽然您的 C2C 连接器不需要实现特定的业务逻辑来支持授权流程，但与 C2C 连接器关联的 OAuth2 .0 授权服务器必须满足。[OAuth 配置要求](#oauth-config-requirements) **注意** AWS IoT Device Management 仅适用于的托管集成支持带有授权代码流的 OAuth 2.0。有关更多信息，请参阅 [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1)。 账户关联是一个允许托管集成和连接器使用访问令牌访问最终用户设备的过程。此令牌为最终用户许可的 AWS IoT Device Management 提供托管集成，以便连接器可以通过 API 调用与最终用户的数据进行交互。有关更多信息，请参阅 [账户关联工作流程](account-linking-flow.md)。 我们建议您不要将这些敏感令牌记录在任何日志中。但是，如果它们存储在日志中，我们建议您使用 CloudWatch 日志数据保护策略来屏蔽日志中的令牌。有关更多信息，请参阅 [Help protect sensitive log data with masking](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/mask-sensitive-log-data.html)。 的托管集成 AWS IoT Device Management 不会直接获得访问令牌；而是通过授权码授权类型获得访问令牌。首先，AWS IoT Device Management 的托管集成必须获得授权码。然后，它将代码交换为访问令牌和刷新令牌。刷新令牌用于在旧访问令牌过期时请求新的访问令牌。如果访问令牌和刷新令牌都已过期，则必须再次执行账户关联流程。你可以通过 `StartAccountAssociationRefresh` API 操作来做到这一点。 **重要** 发放的访问令牌的作用域必须按用户划分，但不能按 OAuth 客户机划分。该令牌不应提供对客户端下所有用户的所有设备的访问权限。 授权服务器必须执行以下操作之一： 发行包含可提取的最终用户（资源所有者）ID 的访问令牌，例如 JWT-Token。 返回每个已颁发的访问令牌的最终用户 ID。 ## OAuth 配置要求 下表说明了 OAuth 授权服务器中用于托管集成 AWS IoT Device Management 以执行[账户关联](account-linking-flow.md)所需的参数： **OAuth 服务器参数** | | | | | --- |--- |--- | | 字段 | 必填 | 评论 | | `clientId` | 是 | 您的应用程序的公共标识符。它用于启动身份验证流程，并且可以公开共享。 | | `clientSecret` | 是 | 用于通过授权服务器对应用程序进行身份验证的密钥，尤其是在使用授权码交换访问令牌时。应将其保密，不得公开共享。 | | `authorizationType` | 是 | 此授权配置支持的授权类型。当前，“OAuth 2.0” 是唯一支持的值。 | | `authUrl` | 是 | 第三方云提供商的授权 URL。 | | `tokenUrl` | 是 | 第三方云提供商的令牌 URL。 | | `tokenEndpointAuthenticationScheme` | 是 | “HTTP\$1BASIC” 或 “REQUEST\$1BODY\$1CREDENTIALS” 的身份验证方案。HTTP\$1BASIC 表示客户端凭证包含在授权标头中，而阶梯表示它们包含在请求正文中。 | 必须对您使用的 OAuth 服务器进行配置，使访问令牌字符串值必须使用 UTF-8 字符集进行 Base64 编码。 # 账户关联角色 要创建 C2C 连接器，你需要一个 OAuth 2.0 授权服务器和账户关联。有关更多信息，请参阅 [账户关联工作流程](account-linking-flow.md)。 OAuth 2.0 在实现账户关联时定义了以下四个角色： 1. 授权服务器 1. 资源所有者（最终用户） 1. 资源服务器 1. 客户端 以下内容定义了这些 OAuth 角色中的每一个： **授权服务器** 授权服务器是识别和验证第三方云中最终用户身份的服务器。此服务器提供的访问令牌可以将 AWS 最终用户的客户平台帐户与其第三方平台帐户关联起来。此过程称为账户关联。 授权服务器通过提供以下内容来支持账户关联： + 显示登录页面，供最终用户登录您的系统。这通常被称为授权端点。 + 对系统中的最终用户进行身份验证。 + 生成用于识别最终用户的授权码。 + 将授权码传递给 AWS IoT Device Management 的托管集成。 + 接受 AWS IoT Device Management 托管集成的授权码，并返回访问令牌，AWS IoT Device Management 的托管集成可用于访问系统中最终用户的数据。这通常通过单独的 URI（称为令牌 URI 或端点）完成。 授权服务器必须支持 OAuth 2.0 授权码流程，才能与 AWS IoT Device Management Connector 的托管集成一起使用。AWS IoT Device Management 的托管集成还支持带有代码[交换证明密钥 (PKCE) 的授权代码](https://www.rfc-editor.org/rfc/rfc7636)流。 授权服务器必须： + 发布包含可提取的最终用户或资源所有者 ID 的访问令牌，例如 jwt-Tokens + 能够返回每个已发放的访问令牌的最终用户 ID 否则，您的连接器将无法支持所需的`AWS.ActivateUser`操作。这将防止在托管集成中使用连接器。 如果连接器开发者或所有者没有维护自己的授权服务器，则使用的授权服务器必须为连接器开发者第三方平台管理的资源提供授权。这意味着托管集成从授权服务器接收的任何令牌都必须在设备（资源）上提供有意义的安全边界。例如，最终用户令牌不允许在另一台最终用户设备上执行命令；该令牌提供的权限会映射到平台内的资源。以 L *ights 公司*为例。当最终用户启动与其连接器的账户关联流程时，他们将被重定向到授权服务器正面的 L *ights In* corporated 登录页面。一旦他们登录并向客户端授予权限，他们就会提供一个令牌，允许连接器访问其 L *ights In* corporated 账户中的资源。 **资源所有者（最终用户）** 作为资源所有者，您可以通过执行账户关联来允许 AWS IoT Device Management 客户通过托管集成访问与您的账户关联的资源。例如，以最终用户已登录 Lights *Incorporated 移动应用程序的智能灯*泡为例。资源所有者是指购买并登录设备的最终用户账户。在我们的示例中，资源所有者被建模为 L *ights In* OAuth2 corporated .0 账户。作为资源所有者，此账户提供发出命令和管理设备的权限。 **资源服务器** 这是托管需要授权才能访问的受保护资源（设备数据）的服务器。 AWS 客户需要代表最终用户访问受保护的资源，他们可以通过账户关联后的 AWS IoT Device Management 连接器的托管集成来访问受保护的资源。以之前的智能灯泡为例，资源服务器是L *ights In* corporated拥有的一项基于云的服务，用于在灯泡上线后对其进行管理。通过资源服务器，资源所有者可以向智能灯泡发出命令，例如将其打开和关闭。受保护的资源仅向最终用户的账户以及 accounts/entities 他们可能已提供权限的其他账户提供权限。 **客户端** 在这种情况下，客户端就是您的 C2C 连接器。客户机被定义为代表最终用户授予对资源服务器内资源的访问权限的应用程序。账户关联过程代表连接器（客户端），请求访问第三方云中最终用户的资源。 尽管连接器是 OAuth 客户端，但 AWS IoT Device Management 的托管集成代表连接器执行操作。例如，AWS IoT Device Management 的托管集成向授权服务器发出获取访问令牌的请求。连接器仍被视为客户端，因为它是访问资源服务器中受保护资源（设备数据）的唯一组件。 以最终用户安装的智能灯泡为例。在客户平台和L *ights In* corporated授权服务器之间完成账户关联后，连接器本身将与资源服务器通信，以检索有关最终用户智能灯泡的信息。然后，连接器可以接收来自最终用户的命令。这包括通过 Lights *Incorporated 资源服务器代表他们打开或关闭灯*。因此，我们将连接器指定为客户端。 # 账户关联工作流程 对于客户通过 C2C 连接器与 AWS IoT Device Management 平台上的终端用户设备进行交互的托管集成，它会通过以下工作流程获取访问令牌： 1. 当用户通过客户应用程序启动第三方设备的启动时，AWS IoT Device Management 的托管集成会返回授权 URI 以及. AssociationId 1. 应用程序前端存储 AssociationId 并将最终用户重定向到第三方平台的登录页面。 1. 最终用户登录。最终用户授予客户端访问其设备数据的权限。 1. 第三方平台创建授权码。最终用户将被重定向到 AWS IoT Device Management 平台回调 URI 的托管集成，包括重定向请求所附的代码。 1. 托管集成会将此代码与第三方平台令牌 URI 交换。 1. 令牌 URI 验证授权码并返回与最终用户关联的 OAuth2 .0 访问令牌和刷新令牌。 1. 托管集成调用 C2C 连接器并进行`AWS.ActivateUser`操作，以完成账户关联流程并获取。 UserId 1. 托管集成 OAuthRedirectUrl （从连接器策略配置）将成功的身份验证页面返回到客户应用程序。 **注意** 如果出现故障，AWS IoT Device Management 的托管集成会将错误和 error\$1 description 查询参数附加到向客户应用程序提供错误详细信息的网址。 1. 客户应用程序将最终用户重定向到。 OAuth RedirectUrl此时，应用程序前端从第一步就知道 AssociationId 了关联。 通过 C2C 连接器向 AWS IoT Device Management 托管集成向第三方云平台发出的所有后续请求，例如发现设备和发送命令的命令，都将包含 OAuth2 .0 访问令牌。 下图显示了账户关联的关键组成部分之间的关系： ![\[C2C 连接器账户将工作流程与 OAuth 授权关联起来\]](http://docs.aws.amazon.com/zh_cn/iot-mi/latest/devguide/images/account-linking-workflow.png) # 实现 C2C 连接器接口操作 的托管集成 AWS IoT Device Management 定义了您 AWS Lambda 必须处理的四个操作才有资格成为连接器。您的 C2C 连接器必须实现以下每项操作： 1. `AWS.ActivateUser`- AWS IoT Device Management 服务的托管集成会调用此 API 来检索与所提供的 OAuth2 .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 调用您的连接器，以停用用户的访问令牌，以便在您的授权服务器中取消链接。 的托管集成 AWS IoT Device Management 始终通过操作调用带有 JSON 字符串负载的 Lambda 函数。 AWS Lambda `invokeFunction`请求操作必须在每个请求负载中包含一个`operationName`字段。有关更多信息，请参阅 AWS Lambda API 参考中的[调](https://docs.aws.amazon.com//lambda/latest/api/API_Invoke.html)用。 每次调用超时设置为两秒，如果调用失败，则将重试五次。 您为连接器实现的 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 操作](discover-devices-op.md)[实施 AWS。 SendCommand 操作](send-command-op.md)、和[使用 SendConnectorEvent API 发送设备事件](send-connector-events.md)。 例如，如果您的 C2C 连接器收到`DiscoverDevices`请求，则 AWS IoT Device Management 的托管集成希望它与上面定义的响应格式同步响应。然后，您必须使用中[实施 AWS。 DiscoverDevices 操作](discover-devices-op.md)定义的请求结构为 DEVICE\$1DISCOVERY 事件调用 `SendConnectorEvent` API。API 调用可以在任何您有权访问 C2C 连接器 AWS 账户 Lambda 凭证的地方进行。`SendConnectorEvent`在 AWS IoT Device Management 的托管集成收到此事件之前，设备发现流程才会成功。 **注意** 或者，如有必要，`SendConnectorEvent`API 调用可以在 C2C 连接器 Lambda 调用响应之前进行。但是，这种流程与软件开发的异步模型相矛盾。 + **SendConnectorEvent**-您的连接器调用 AWS IoT Device Management API 的托管集成，将设备事件发送到 AWS IoT Device Management 的托管集成。托管集成仅接受三种类型的事件： + “DEV **ICE\$1DISCOVERY**” — 此事件操作应用于发送第三方云中发现的设备列表以获取特定的访问令牌。 + **“DEVICE\$1COMMAND\$1RESPONSE” — 此事件操作应用于发送作为命令**执行结果的特定设备事件。 + **“DEVICE\$1EV** ENT”-此事件操作应用于源自设备且不是基于用户的命令的直接结果的任何事件。这可以作为一种常规事件类型，用于主动报告设备状态变化或通知。 # 实施 AWS。 ActivateUser 操作 AWS IoT Device Management 的托管集成需要执行该`AWS.ActivateUser`操作，才能从最终用户的 OAuth2 .0 令牌中检索用户标识符。的托管集成 AWS IoT Device Management 将在请求标头中传递 OAuth令牌，并期望您的连接器在响应负载中包含全局唯一的用户标识符。此操作发生在账户关联流程成功之后。 以下列表概述了连接器的要求，以促进成功的`AWS.Activate`用户流。 + 您的 C2C 连接器 Lambda 可以处理来自 AWS `AWS.ActivateUser` IoT Device Management 托管集成的操作请求消息。 + 您的 C2C 连接器 Lambda 可以根据 OAuth2提供的.0 令牌确定唯一的用户标识符。通常，如果是 JWT 令牌，则可以从令牌本身中提取，也可以通过令牌从授权服务器请求该令牌。 **`AWS.ActivateUser` 工作流** 1. 的托管集成使用以下有效负 AWS IoT Device Management 载调用您的 C2C 连接器 Lambda： ``` { "header": { "auth": { "token": "ashriu32yr97feqy7afsaf", "type": "OAuth2.0" } }, "payload": { "operationName": "AWS.ActivateUser", "operationVersion": "1.0.0", "connectorId": "Your-Connector-ID", } } ``` 1. C2C 连接器通过令牌或通过查询您的第三方资源服务器来确定要包含在`AWS.ActivateUser`响应中的用户 ID。 1. C2C 连接器会响应 Lambda `AWS.ActivateUser` 操作调用，包括默认负载以及字段内相应的用户标识符。`userId` ``` { "header": { "responseCode":200 }, "payload": { "responseMessage": "Successfully activated user with connector-id `Your-Connector-Id.”, "userId": "123456" } } ``` # 实施 AWS。 DiscoverDevices 操作 设备发现会将最终用户拥有的物理设备列表与 AWS IoT Device Management 托管集成中维护的最终用户设备的数字表示形式保持一致。只有在用户与 AWS IoT Device Management 的托管集成之间完成账户关联后， AWS 客户才会在最终用户拥有的设备上执行此操作。设备发现是一个异步过程，其中 AWS IoT Device Management 的托管集成会调用连接器来启动设备发现请求。C2C 连接器异步返回已发现的最终用户设备列表，其中包含托管集成生成的参考标识符（称为`deviceDiscoveryId`）。 下图说明了 AWS IoT Device Management 的最终用户和托管集成之间的设备发现工作流程： ![\[AWS。 DiscoverDevices 工作流程\]](http://docs.aws.amazon.com/zh_cn/iot-mi/latest/devguide/images/device-discovery-workflow.png) **AWS。 DiscoverDevices 工作流程** 1. 客户代表最终用户启动设备发现流程。 1. 的托管集成 AWS IoT Device Management 会生成一个参考标识符，该标识符调`deviceDiscoveryId`用 AWS 客户生成的设备发现请求。 1. 的托管集成使用`AWS.DiscoverDevices`操作界面向 C2C 连接器 AWS IoT Device Management 发送设备发现请求，包括有效 OAuth`accessToken`的最终用户以及. `deviceDiscoveryId` 1. 您的连接器存储`deviceDiscoveryId`以包含在`DEVICE_DISCOVERY`活动中。此事件还将包含已发现的最终用户设备的列表，并且必须将其发送到 AWS IoT Device Management 的托管集成，并将 `SendConnectorEvent` API 作为`DEVICE_DISCOVERY`事件发送。 1. 您的 C2C 连接器应调用资源服务器来获取最终用户拥有的所有设备。 1. 您的 C2C 连接器 Lambda 会响应 Lambda 调用 `invokeFunction` ()，并向 AWS IoT Device Management 的托管集成发出 ACK 响应，作为操作的初始响应。`AWS.DiscoverDevices`托管集成通过 ACK 通知客户已启动的设备发现流程。 1. 您的资源服务器会向您发送最终用户拥有和操作的设备列表。 1. 您的连接器将每台最终用户设备转换为 AWS IoT Device Management 所需设备格式的托管集成 `ConnectorDeviceId``ConnectorDeviceName`，包括每台设备的能力报告。 1. C2C 连接器还提供`UserId`已发现设备所有者的信息。它可以作为设备列表的一部分从您的资源服务器中检索，也可以根据您的资源服务器实现情况在单独的调用中检索。 1. 接下来，您的 C2C 连接器将使用 AWS 账户 凭证并将操作参数设置为 “DEVICE\$1DISCOVERY”`SendConnectorEvent`，通过 sigv4 调用 AWS IoT 设备管理 API 的托管集成。发送到 AWS IoT Device Management 托管集成的设备列表中的每台设备都将由设备特定的参数表示`connectorDeviceId`，例如`connectorDeviceName`、和 a。`capabilityReport` 1. 根据您的资源服务器响应，您需要相应地通知 AWS IoT Device Management 的托管集成。 例如，如果您的资源服务器对最终用户发现的设备列表进行了分页响应，那么对于每次轮询，您都可以发送一个`statusCode`参数为的`3xx`单个`DEVICE_DISCOVERY`操作事件。如果您的设备发现仍在进行中，请重复步骤 5、6 和 7。 1. 的托管集成会向客户 AWS IoT Device Management 发送有关已发现最终用户设备的通知。 1. 如果您的 C2C 连接器发送的`DEVICE_DISCOVERY`操作事件`statusCode`参数更新为 200，则托管集成将通知客户设备发现工作流程已完成。 **重要** 如果需要，步骤 7 到 11 可以在步骤 6 之前进行。例如，如果您的第三方平台有一个用于列出最终用户设备的 API，则可以在 C2C 连接器 Lambda 使用典型的 ACK 响应`SendConnectorEvent`之前发送 DEVICE\$1DISCOVERY 事件。 ## 设备发现时的 C2C 连接器要求 以下列表概述了 C2C 连接器的要求，以便于成功发现设备。 + C2C 连接器 Lambda a 可以处理来自 AWS IoT Device Management 托管集成的设备发现请求消息并处理操作。`AWS.DiscoverDevices` + 您的 C2C 连接器可以使用用于注册连接器的凭证 APIs 通过 Sigv4 调用 AWS IoT Device Management 的 AWS 账户 托管集成。 ## 设备发现过程 以下步骤概述了使用您的 C2C 连接器和托管集成 AWS IoT Device Management 的设备发现过程。 **设备发现过程** 1. 托管集成会触发设备发现： 1. 使用以下 JSON 负载`DiscoverDevices`向发送 POST 请求： ``` /DiscoverDevices { "header": { "auth": { "token": "ashriu32yr97feqy7afsaf", "type": "OAuth2.0" } }, "payload": { "operationName": "AWS.DiscoverDevices", "operationVersion": "1.0", "connectorId": "Your-Connector-Id", "deviceDiscoveryId": "12345678" } } ``` 1. 连接器确认发现： 1. 连接器发送带有以下 JSON 响应的确认： ``` { "header": { "responseCode":200 }, "payload": { "responseMessage": "Discovering devices for discovery-job-id '12345678' with connector-id `Your-Connector-Id`" } } ``` 1. 连接器发送设备发现事件： 1. 使用以下 JSON 负载`/connector-event/{your_connector_id}`向发送 POST 请求： ``` AWS API - /SendConnectorEvent URI – POST /connector-event/{your_connector_id} { "UserId": "6109342", "Operation": "DEVICE_DISCOVERY", "OperationVersion": "1.0", "StatusCode": 200, "DeviceDiscoveryId": "12345678", "ConnectorId": "Your_connector_Id", "Message": "Device discovery for discovery-job-id '12345678' successful", "Devices": [ { "ConnectorDeviceId": "Your_Device_Id_1", "ConnectorDeviceName": "Your-Device-Name", "CapabilityReport": { "nodeId":"1", "version":"1.0.0", "endpoints":[{ "id":"1", "deviceTypes":["Camera"], "clusters":[{ "id":"0x0006", "revision":1, "attributes":[{ "id":"0x0000", }], "commands":["0x00","0x01"], "events":["0x00"] }] }] } } ] } ``` ## 为 DISCOVER\$1D CapabilityReport EVICES 事件构造一个 如上面定义的事件结构所示，在 DISCOVER\$1DEVICES 事件中报告的每台设备作为对`AWS.DiscoverDevices`操作的响应，都需要 CapbilityReport 来描述相应设备的功能。`CapabilityReport`以符合 Matter 的格式表示 AWS IoT Device Management 设备功能的托管集成。` CapabilityReport`中必须提供以下字段： + `nodeId`，字符串：包含以下内容的设备节点的标识符 `endpoints` + `version`，String：此设备节点的版本，由连接器开发者设置 + `endpoints`，列表：此设备端点支持的案件数据模型 AWS 实现列表。 + `id`，字符串：连接器开发者设置的端点标识符 + `deviceTypes`，列表：此端点捕获的设备类型列表，即 “摄像头”。 + `clusters`，Lis t：此端点支持的案件数据模型的 AWS 实现列表。 + `id`，字符串：Matter 标准定义的集群标识符。 + `revision`，整数：Matter 标准定义的集群修订版号。 + `attributes`， 地图：属性标识符及其对应的当前设备状态值的映射，标识符和有效值由问题标准定义。 + `id`，字符串：案件数据模型的 AWS 实现所定义的属性 ID。 + `value`，对象：由属性 ID 定义的属性的当前值。“值” 的类型可以根据属性而变化。该`value`字段对于每个属性都是可选的，只有当您的连接器 lambda 可以在发现期间确定当前状态时，才应包含该字段。 + `commands`，列表：按照 Matter 标准的定义，此集群 IDs 支持的命令列表。 + `events`，列表：根据 Matter 标准的定义，此集群 IDs 支持的事件列表。 有关[物质数据模型支持的功能及其相应AWS 实现的](matter-data-model.md)当前列表，请参阅最新版本的数据模型文档。 # 实施 AWS。 SendCommand 操作 该`AWS.SendCommand`操作允许 AWS IoT Device Management 的托管集成通过 AWS 客户将最终用户启动的命令发送到您的资源服务器。您的资源服务器可能支持多种类型的设备，其中每种类型都有自己的响应模型。命令执行是一个异步过程，其中 AWS IoT Device Management 的托管集成发送带有 “TraceID” 的命令执行请求，您的连接器将包含在通过 “API” SendConnectorEvent 发送回托管集成的命令响应中。AWS IoT Device Management 的托管集成期望资源服务器返回一个确认已收到命令的响应，但不一定表示命令已执行。 下图说明了命令执行流程，并举例说明了最终用户尝试打开房屋灯光的示例： ![\[设备命令执行工作流程\]](http://docs.aws.amazon.com/zh_cn/iot-mi/latest/devguide/images/send-command-workflow.png) **设备命令执行工作流程** 1. 最终用户使用 AWS 客户的应用程序发送开灯的命令。 1. 客户将命令信息与最终用户的设备信息传递给 AWS IoT Device Management 的托管集成。 1. 托管集成会生成 “TraceID”，您的连接器将在将命令响应发送回服务时使用它。 1. AWS IoT Device Management 的托管集成使用`AWS.SendCommand`操作界面向您的连接器发送命令请求。 1. 此接口定义的有效载荷包括设备标识符、以 Matter 形式制定的设备命令endpoints/clusters/commands、最终用户的访问令牌以及其他必需的参数。 1. 您的连接器存储`traceId`要包含在命令响应中的内容。 1. 您的连接器会将托管集成命令请求转换为资源服务器的相应格式。 1. 您的连接器`UserId`从提供的最终用户的访问令牌中获取，并将其与命令相关联。 1. 如果是 JWT 和类似的令牌，则可以使用单独的调用从您的资源服务器中检索，也可以从访问令牌中提取。`UserId` 1. 实现取决于您的资源服务器和访问令牌的详细信息。 1. 您的连接器调用资源服务器以 “打开” 最终用户的灯。 1. 资源服务器与设备交互。 1. 连接器中继到资源服务器已下发命令的 AWS IoT IoT Device Management 托管集成，并以 ACK 作为初始同步命令响应进行响应。 1. 然后，托管集成将其中继回客户应用程序。 1. 设备开灯后，您的资源服务器会捕获该设备事件。 1. 您的资源服务器将设备事件发送到连接器。 1. 您的连接器将资源服务器生成的设备事件转换为托管集成 DEVICE\$1COMMAND\$1RESPONSE 事件操作类型。 1. 您的连接器调用 `SendConnectorEvent` API，操作为 “设备\$1命令\$1响应”。 1. 它会在初始请求中附上由 AWS IoT Device Management 托管集成`traceId`提供的内容。 1. 托管集成会通知客户有关最终用户的设备状态变化。 1. 客户通知最终用户设备灯已亮起。 **注意** 您的资源服务器配置决定了处理失败的设备命令请求和响应消息的逻辑。这包括对命令使用相同的 referenceId 进行消息重试尝试。 ## 执行设备命令的 C2C 连接器要求 以下列表概述了 C2C 连接器的要求，以促进设备命令的成功执行。 + C2C 连接器 Lambda 可以`AWS.SendCommand`处理来自 AWS IoT Device Management 托管集成的操作请求消息。 + 您的 C2C 连接器必须跟踪发送到您的资源服务器的命令，并将其映射到相应的 “TraceID”。 + 您可以使用用于注册 C2C 连接器的 AWS 凭证通过 Sigv4 调用 AWS IoT Device Management 服务 API 的 AWS 账户 托管集成。 1. 托管集成向连接器发送命令（请参阅上图中的步骤 4）。 1. ``` /Send-Command { "header": { "auth": { "token": "ashriu32yr97feqy7afsaf", "type": "OAuth2.0" } }, "payload": { "operationName": "AWS.SendCommand", "operationVersion": "1.0", "connectorId": "Your-Connector-Id", "connectorDeviceId": "Your_Device_Id", "traceId": "traceId-3241u78123419", "endpoints": [{ "id": "1", "clusters": [{ "id": "0x0202", "commands": [{ "0xff01": { "0x0000": "3” } }] }] }] } } ``` 1. C2C 连接器 ACK 命令（请参阅前一图表中的步骤 7，其中连接器向 AWS IoT 设备管理服务的托管集成发送 ACK）。 1. ``` { "header":{ "responseCode":200 }, "payload":{ "responseMessage": "Successfully received send-command request for connector 'Your-Connector-Id' and connector-device-id 'Your_Device_Id'" } } ``` 1. 连接器发送设备命令响应事件（请参阅上图中的步骤 11）。 1. ``` AWS-API: /SendConnectorEvent URI: POST /connector-event/{Your-Connector-Id} { "UserId": "End-User-Id", "Operation": "DEVICE_COMMAND_RESPONSE", "OperationVersion": "1.0", "StatusCode": 200, "Message": “Example message”, "ConnectorDeviceId": "Your_Device_Id", "TraceId": "traceId-3241u78123419", "MatterEndpoint": { "id": "1", "clusters": [{ "id": "0x0202", "attributes": [ { "0x0000": “3” } ], "commands": [ "0xff01": { "0x0000": "3” } ] }] } } ``` **注意** 在通过 API 收到相应的 DEVICE\$1COMMAND\$1RESPONSE 事件之前，由于命令执行而导致的设备状态变化不会反映在 AWS IoT Device Management 的托管集成中。 SendConnectorEvent 这意味着，在托管集成收到前面步骤 3 的事件之前，无论您的连接器调用响应是否表示成功，都不会更新设备状态。 ## 解释 AWS 中包含的 “终端节点”。 SendCommand 请求 托管集成将使用设备发现期间报告的设备功能来确定设备可以接受哪些命令。每个设备功能都是通过 AWS 实现物质数据模型进行建模的；因此，所有传入的命令都将从给定集群中的 “commands” 字段派生。您的连接器负责解析 “端点” 字段，确定相应的 Matter 命令，然后对其进行翻译，以便正确的命令到达设备。通常，这意味着将 Matter 数据模型转换为相关的 API 请求。 执行命令后，您的连接器将确定由物质数据模型的 AWS 实现定义的哪些 “属性” 因此发生了变化。然后，这些更改将通过 API 发送的 API DEVICE\$1COMMAND\$1RESPONSE 事件报告给 AWS IoT Device Management 的托管集成。`SendConnectorEvent` 考虑以下示例负载中包含的 “端点” 字段：`AWS.SendCommand` ``` "endpoints": [{ "id": "1", "clusters": [{ "id": "0x0202", "commands": [{ "0xff01": { "0x0000": "3” } }] }] }] ``` **通过此对象，连接器可以确定以下内容：** 1. 设置终端节点和集群信息： 1. 将端点设置`id`为 “1”。 **注意** 如果设备定义了多个端点，例如单个集群（例如On/Off) can control multiple capabilities (i.e. turn a light on/off as well as turning a strobe on/off），则使用此 ID 将命令路由到正确的功能。 1. 将集群设置`id`为 “0x0202”（风扇控制集群）。 1. 设置命令信息： 1. 将命令标识符设置为 “0xff01”（更新状态命令由定义）。 AWS 1. 使用请求中提供的值更新包含的属性标识符。 1. 更新属性： 1. 将属性标识符设置为 “0x0000”（风扇控制集FanMode 群的属性）。 1. 将属性值设置为 “3”（高风扇速度）。 托管集成定义了两种 “自定义” 命令类型，这些类型不是由物质数据模型的 AWS 实现严格定义的： ReadState 和 UpdateState 命令。要获取和设置 Matter 定义的集群属性，托管集成将向您的连接器发送一个`AWS.SendCommand`请求，其中包含与 UpdateState (id: 0xff01) 或 ReadState (id: 0xff02) IDs 相关的命令，以及必须更新或读取的相应属性参数。对于设置为可变（可更新）或可检索（可读取）的属性，可以为任何设备类型调用这些命令，这些属性可以从相应的 Matter 数据模型 AWS 实现中调用。 # 使用 SendConnectorEvent API 发送设备事件 ## 设备启动的事件概述 虽然 `SendConnectorEvent` API 用于异步响应`AWS.SendCommand`和`AWS.DiscoverDevices`操作，但它也用于将任何设备启动的事件通知托管集成。设备启动的事件可以定义为设备在没有用户启动命令的情况下生成的任何事件。这些设备事件可能包括但不限于设备状态变化、运动检测、电池电量等。您可以使用带操作 DEV **IC** E\$1EVENT 的 `SendConnectorEvent` API 将这些事件发送回托管集成。 以下部分以安装在家中的智能摄像头为例，进一步说明这些事件的工作流程： ![\[设备事件工作流程\]](http://docs.aws.amazon.com/zh_cn/iot-mi/latest/devguide/images/device-events-workflow.png) **设备事件工作流程** 1. 您的摄像机会检测到动作，并为此生成一个发送到您的资源服务器的事件。 1. 您的资源服务器处理该事件并将其发送到您的 C2C 连接器。 1. 您的连接器会将此事件转换为 AWS IoT Device Manag `DEVICE_EVENT` ement 接口的托管集成。 1. 您的 C2C 连接器使用操作设置为 “DEVICE\$1EVENT” `SendConnectorEvent` 的 API 将此设备事件发送到托管集成。 1. 托管集成可识别相关客户，并将此事件转发给客户。 1. 客户收到此事件并通过用户标识符将其显示给用户。 有关 `SendConnectorEvent` API 操作的更多信息，请参阅 `SendConnectorEvent` AWS IoT Device Management 托管集成 API 参考指南。 ## 设备启动的事件要求 以下是设备启动的事件的一些要求。 + 您的 C2C 连接器资源应该能够从您的资源服务器接收异步设备事件 + 您的 C2C 连接器资源应该能够使用用于注册 C2C 连接器的 AWS 凭证通过 Sigv4 调用 AWS IoT 设备管理服务 API 的 AWS 账户 托管集成。 以下示例演示了连接器通过 API 发送源于设备的事件： SendConnectorEvent ``` AWS-API: /SendConnectorEvent URI: POST /connector-event/{Your-Connector-Id} { "UserId": "Your-End-User-ID", "Operation": "DEVICE_EVENT", "OperationVersion": "1.0", "StatusCode": 200, "Message": None, "ConnectorDeviceId": "Your_Device_Id", "MatterEndpoint": { "id": "1", "clusters": [{ "id": "0x0202", "attributes": [ { "0x0000": "3" } ] }] }] } ``` 从以下示例中，我们可以看到以下内容： + 这来自 ID 等于 1 的设备端点。 + 与该事件相关的设备功能的集群 ID 为 **0x0202**，与风扇控制问题集群有关。 + 已更改的属性的 ID 为 **0x000**，与集群中的风扇模式枚举有关。它已更新为值 **3**，与 **High** 的值有关。 + 由于`connectorId`是云服务在创建时返回的参数，因此 Connectors 必须使用查询 GetCloudConnector 和筛选依据`lambdaARN`。使用 `Lambda.get_function_url_config` API 查询 lambda 自己的`ARN`值。这`CloudConnectorId`允许在 lambda 中动态访问，而不是像之前那样进行静态配置。 # 实施 AWS。 DeactivateUser 操作 ## 用户停用概述 当客户删除其客户账户，或者最终用户想要取消其在系统中的账户与 AWS 客户系统的关联时，需要停用提供的用户访问令牌。 AWS 在这两种用例中，托管集成都需要使用 C2C 连接器来简化此工作流程。 下图说明了如何取消最终用户帐户与系统的关联 ![\[用户停用工作流程\]](http://docs.aws.amazon.com/zh_cn/iot-mi/latest/devguide/images/user-deactivate-workflow.png) **用户停用工作流程** 1. 用户启动 AWS 客户账户与与 C2C 连接器关联的第三方授权服务器之间的解除关联过程。 1. 客户通过 AWS IoT Device Management 的托管集成启动删除用户关联。 1. 托管集成通过使用操作界面向连接器发出请求来启动停用过程。`AWS.DeactivateUser` 1. /user 的访问令牌包含在请求的标头中。 1. 您的 C2C 连接器接受请求并调用您的授权服务器来撤消令牌及其提供的任何访问权限。 1. 例如，来自未关联用户账户的事件在执行后不应再发送到托管集成。`AWS.DeactivateUser` 1. 您的授权服务器撤消访问权限并将响应发送回您的 C2C 连接器。 1. 您的 C2C 连接器会向 AWS IoT Device Management 的托管集成发送用户访问令牌已被撤销的 ACK。 1. 托管集成会删除最终用户拥有的与您的资源服务器关联的所有资源。 1. 托管集成会向客户发送 ACK，说明与您的系统相关的所有关联都已删除。 1. 客户通知最终用户其账户已与您的平台取消关联。 ## AWS。 DeactivateUser 要求 + C2C 连接器 Lambda 函数接收来自托管集成的请求消息以处理操作。`AWS.DeactivateUser` + C2C 连接器必须撤销授权服务器中用户提供的 **OAuth2.0** 令牌和相应的刷新令牌。 以下是您的连接器将收到的示例`AWS.DeactivateUser`请求： ``` { "header": { "auth": { "token": "ashriu32yr97feqy7afsaf", "type": "OAuth2.0" } }, "payload":{ "operationName": "AWS.DeactivateUser" "operationVersion": "1.0" "connectorId": "Your-connector-Id" } } ``` # 调用你的 C2C 连接器 AWS Lambda 允许基于资源的策略授权谁可以调用 Lambda。由于 AWS IoT Device Management 的托管集成是 AWS 服务，因此您必须允许托管集成通过资源策略调用 C2C 连接器 Lambda。 将至少具有以下最低权限的资源策略附加到您的 C2C 连接器 Lambda。这提供了与 Lambda 函数调用权限的托管集成。本政策包含一个`Condition`密钥，可帮助您将您的可用性限制`connectorId`为仅限目标用户。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id": "default", "Statement": [ { "Sid": "Your-Desired-Policy-ID", "Effect": "Allow", "Principal": { "Service": "iotmanagedintegrations.amazonaws.com" }, "Action": "lambda:InvokeFunction", "Resource": "arn:aws:lambda:ca-central-1:444455556666:function:connector-lambda-name", "Condition": { "StringEquals": { "aws:SourceArn": "arn:aws:iotmanagedintegrations:ca-central-1:444455556666:account-association/account-association-id" } } } ] } ``` ------ # 为您的 IAM 角色添加权限 所有托管集成都 APIs 需要 AWS Sigv4 身份验证才能调用。Sigv4 正在签署协议，以使用您的 AWS 账户 凭据对 AWS API 请求进行身份验证。您用于调用托管集成的 IAM 角色 APIs 必须具有以下权限才能成功调用： APIs ``` "Version": "2012-10-17", "Statement": [ { "Sid": "Statement1", "Effect": "Allow", "Action": [ "iotmanagedintegrations:Your-Required-Actions" ], "Resource": [ "Your-Resource" ] }] } ``` 有关添加这些权限的更多信息，请联系 支持。 **其他资源** 要注册您的 C2C 连接器，您需要满足以下条件： + 表示您要注册的连接器的 Lambda ARN。 # 手动测试您的 C2C 连接器 要手动测试 C2C 连接器 end-to-end，必须同时模拟客户和最终用户。 **您将需要以下资源：** + 表示您要 AWS Lambda 测试的连接器的 ARN。 + 来自您的云平台的测试 OAuth 2.0 用户帐户。 + 在 AWS IoT Device Management 托管集成中注册的连接器。有关更多信息，请参阅 [使用 C2C（云到云）连接器](use-c2c-create-cloud-connector.md)。 # 使用 C2C（云到云）连接器 C2C 连接器管理请求和响应消息的翻译，并支持托管集成与第三方供应商云之间的通信。它促进了对不同设备类型、平台和协议的统一控制，从而可以加载和管理第三方设备。 以下过程列出了使用 C2C 连接器的步骤。 **使用 C2C 连接器的步骤：** 1. **CreateCloudConnector** 配置连接器以启用托管集成与第三方供应商云之间的双向通信。 设置连接器时，请提供以下详细信息： + **名称**：为连接器选择一个描述性名称。 + **描述**：简要概述连接器的用途和功能。 + **AWS Lambda ARN**：指定为连接器供电的 AWS Lambda 函数的亚马逊资源名称 (ARN)。 构建和部署与第三方供应商通信的 AWS Lambda 函数 APIs 以创建连接器。接下来，在托管集成中调用 [CreateCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateCloudConnector.html)API，并提供 AWS Lambda 函数 ARN 进行注册。确保该 AWS Lambda 函数部署在托管集成中创建连接器的 AWS 账户中。系统将为您分配一个唯一的**连接器 ID** 来识别集成。 ** CreateCloudConnector API 请求和响应示例：** ``` Request: { "Name": "CreateCloudConnector", "Description": "Testing for C2C", "EndpointType": "LAMBDA", "EndpointConfig": { "lambda": { "arn": "arn:aws:lambda:us-east-1:xxxxxx:function:TestingConnector" } }, "ClientToken": "abc" } Response: { "Id": "string" } ``` **创作流程：** ![\[云连接器创建阶段\]](http://docs.aws.amazon.com/zh_cn/iot-mi/latest/devguide/images/iot-managedintegrations-createcloudconnector.png) **注意** 根据需要使用[GetCloudConnector[UpdateCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_UpdateCloudConnector.html)](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetCloudConnector.html)、[DeleteCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_DeleteCloudConnector.html)、和 [ListCloudConnectors](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListCloudConnectors.html) APIs ，执行此过程。 1. **CreateConnectorDestination** 配置目标以提供连接器与第三方供应商云建立安全连接所需的设置和身份验证凭据。使用 Destinations 将您的第三方身份验证凭据注册到托管集成，例如 OAuth 2.0 授权详细信息，包括授权 URL、身份验证方案以及其中凭据的位置 AWS Secrets Manager。 **先决条件** 在创建之前 **ConnectorDestination**，您必须： + 调用 [CreateCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateCloudConnector.html)API 创建连接器。在 [CreateConnectorDestination](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateConnectorDestination.html)API API 调用中使用该函数返回的 ID。 + 检索连接`tokenUrl`器的 3P 平台的。（你可以用 **authCod** e 兑换 AccessT **oken**）。 + 检索连接器的 3P 平台的 **authURL**。（最终用户可以使用其用户名和密码进行身份验证）。 + 在账户的密钥管理器中使用`clientId`和`clientSecret`（来自 3P 平台）。 ** CreateConnectorDestination API 请求和响应示例：** ``` Request: { "Name": "CreateConnectorDestination", "Description": "CreateConnectorDestination", "AuthType": "OAUTH", "AuthConfig": { "oAuth": { "authUrl": "https://xxxx.com/oauth2/authorize", "tokenUrl": "https://xxxx/oauth2/token", "scope": "testScope", "tokenEndpointAuthenticationScheme": "HTTP_BASIC", "oAuthCompleteRedirectUrl": "about:blank", "proactiveRefreshTokenRenewal": { "enabled": false, "DaysBeforeRenewal": 30 } } }, "CloudConnectorId": "", // The connectorID instance from response of Step 1. "SecretsManager": { "arn": "arn:aws:secretsmanager:*****:secret:*******", "versionId": "********" }, "ClientToken": "***" } Response: { "Id":"string" } ``` **云目标创建流程：** ![\[CreateConnectorDestination API 调用阶段\]](http://docs.aws.amazon.com/zh_cn/iot-mi/latest/devguide/images/iot-managedintegrations-createconnectordestination.png) **注意** 根据需要使用[GetCloudConnector[UpdateCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_UpdateCloudConnector.html)](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetCloudConnector.html)、[DeleteCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_DeleteCloudConnector.html)、和 [ListCloudConnectors](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListCloudConnectors.html) APIs ，执行此过程。 1. **CreateAccountAssociation** 关联表示最终用户的第三方云账户与连接器目标之间的关系。在创建关联并将最终用户与托管集成关联后，他们的设备可通过唯一的**关联 ID** 进行访问。这种集成支持三个关键功能：发现设备、发送命令和接收事件。 **先决条件** 在创建之前，**AccountAssociation**您必须完成以下操作： + 调用 [CreateConnectorDestination](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateConnectorDestination.html)API 创建目的地。该函数返回的 ID 将用于 [CreateAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateAccountAssociation.html)API 调用。 + 调用 [CreateAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateAccountAssociation.html) API。 ** CreateAccountAssociation API 请求和响应示例：** ``` Request: { "Name": "CreateAccountAssociation", "Description": "CreateAccountAssociation", "ConnectorDestinationId": "", //The destinationID from destination creation. "ClientToken": "***" } Response: { "Id":"string" } ``` **注意** 根据需要使用[GetCloudConnector[UpdateCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_UpdateCloudConnector.html)](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetCloudConnector.html)、[DeleteCloudConnector](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_DeleteCloudConnector.html)、和 [ListCloudConnectors](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListCloudConnectors.html) APIs ，执行此过程。 **AccountAssociation**的状态是从[GetAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetAccountAssociation.html)和[ListAccountAssociations](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListAccountAssociations.html) APIs中查询的。这些 APIs 显示了**协会**的状况。[StartAccountAssociationRefresh](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_StartAccountAssociationRefresh.html)API 允许在刷新令牌到期时刷新**AccountAssociation**状态。 1. **设备发现** 每个托管事物都与设备特定的详细信息相关联，例如其序列号和数据模型。数据模型描述了设备的功能，表明它是灯泡、开关、恒温器还是其他类型的设备。要发现 3P 设备并为该 3P 设备创建 ManagedThing，必须按顺序执行以下步骤。 1. 调用 [StartDeviceDiscovery](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_StartDeviceDiscovery.html)API 开始设备发现过程。 ** StartDeviceDiscovery API 请求和响应示例：** ``` Request: { "DiscoveryType": "CLOUD", "AccountAssociationId": "*****", "ClientToken": "abc" } Response: { "Id": "string", "StartedAt": number } ``` 1. 调用 [GetDeviceDiscovery](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetDeviceDiscovery.html)API 来检查发现过程的状态。 1. 调用 [ListDiscoveredDevices](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListDiscoveredDevices.html)API 列出发现的设备。 ** ListDiscoveredDevices API 请求和响应示例：** ``` Request: //Empty body Response: { "Items": [ { "Brand": "string", "ConnectorDeviceId": "string", "ConnectorDeviceName": "string", "DeviceTypes": [ "string" ], "DiscoveredAt": number, "ManagedThingId": "string", "Model": "string", "Modification": "string" } ], "NextToken": "string" } ``` 1. 调用 [CreateManagedThing](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateManagedThing.html)API 从发现列表中选择要导入托管集成的设备。 ** CreateManagedThing API 请求和响应示例：** ``` Request: { "Role": "DEVICE", "AuthenticationMaterial": "CLOUD:XXXX:", "AuthenticationMaterialType": "DISCOVERED_DEVICE", "Name": "sample-device-name" "ClientToken": "xxx" } Response: { "Arn": "string", // This is the ARN of the managedThing "CreatedAt": number, "Id": "string" } ``` 1. 调用 [GetManagedThing](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_GetManagedThing.html)API 来查看这个新创建的`managedThing`。状态将是`UNASSOCIATED`。 1. 调用 [RegisterAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_RegisterAccountAssociation.html)API `managedThing` 将其与特定关联`accountAssociation`。成功的 [RegisterAccountAssociation](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_RegisterAccountAssociation.html)API 结束后，`ASSOCIATED`状态会`managedThing`发生变化。 ** RegisterAccountAssociation API 请求和响应示例：** ``` Request: { "AccountAssociationId": "string", "DeviceDiscoveryId": "string", "ManagedThingId": "string" } Response: { "AccountAssociationId": "string", "DeviceDiscoveryId": "string", "ManagedThingId": "string" } ``` 1. **向 3P 设备发送命令** 要控制新上线的设备，请使用 [SendManagedThingCommand](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html)API，使用先前创建的**关联 ID** 和基于设备支持的功能的控制操作。连接器使用账户关联过程中存储的凭据向第三方云进行身份验证并调用操作的相关 API 调用。 ** SendManagedThingCommand API 请求和响应示例：** ``` Request: { "AccountAssociationId": "string", "ConnectorAssociationId": "string", "Endpoints": [ { "capabilities": [ { "actions": [ { "actionTraceId": "string", "name": "string", "parameters": JSON value, "ref": "string" } ], "id": "string", "name": "string", "version": "string" } ], "endpointId": "string" } ] } Response: { "TraceId": "string" } ``` **向 3P 设备流程发送命令：** ![\[向 3P 设备发送命令\]](http://docs.aws.amazon.com/zh_cn/iot-mi/latest/devguide/images/iot-managedintegrations-send-to-device.png) 1. **连接器向托管集成发送事件** [SendConnectorEvent](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendConnectorEvent.html)API 捕获从连接器到托管集成的四种类型的事件，由 O **peration Type 参数的以下枚举值表示**： + D@@ **EVICE\$1COMMAND\$1RESPONSE：连接器为响应命令**而发送的异步响应。 + DEV@@ **ICE\$1DISCO** VERY：为了响应设备发现过程，连接器使用 API 将发现的设备列表发送给托管集成。[SendConnectorEvent](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendConnectorEvent.html) + **DEVICE\$1EVENT：发送收到的设备事件**。 + D@@ **EVICE\$1COMMAND\$1REQUEST：从设备**发起的命令请求。例如，WebRTC工作流程。 连接器还可以使用带有可选`userId`参数的 [SendConnectorEvent](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendConnectorEvent.html)API 转发设备事件。 + 对于带有以下内容的设备事件`userId`： ** SendConnectorEvent API 请求和响应示例：** ``` Request: { "UserId": "*****", "Operation": "DEVICE_EVENT", "OperationVersion": "1.0", "StatusCode": 200, "ConnectorId": "****", "ConnectorDeviceId": "***", "TraceId": "***", "MatterEndpoint": { "id": "**", "clusters": [{ ..... } }] } } Response: { "ConnectorId": "string" } ``` + 对于没有`userId`：的设备事件 ** SendConnectorEvent API 请求和响应示例：** ``` Request: { "Operation": "DEVICE_EVENT", "OperationVersion": "1.0", "StatusCode": 200, "ConnectorId": "*****", "ConnectorDeviceId": "****", "TraceId": "****", "MatterEndpoint": { "id": "**", "clusters": [{ .... }] } } Response: { "ConnectorId": "string" } ``` 要删除特定账户关联`managedThing`和账户关联之间的关联，请使用注销机制： ** DeregisterAccountAssociation API 请求和响应示例：** ``` Request: { "AccountAssociationId": "****", "ManagedThingId": "****" } Response: HTTP/1.1 200 // Empty body ``` **发送事件流：** ![\[发送事件流程\]](http://docs.aws.amazon.com/zh_cn/iot-mi/latest/devguide/images/iot-managedintegrations-send-events.png) 1. **将连接器状态更新为 “已上市”，使其对其他托管集成客户可见** 默认情况下，连接器是私有的，只有创建连接器的 AWS 账户才能看见。您可以选择将连接器设置为对其他托管集成客户可见。 要与其他用户共享您的连接器，请使用连接器详细信息页面 AWS 管理控制台 上的 “**设为可见**” 选项，将您的连接器 ID 提交给以 AWS 供审核。一旦获得批准，该连接器便可供所有托管集成用户使用。 AWS 区域此外，您可以 IDs 通过修改连接器关联 AWS Lambda 功能的访问策略来限制对特定 AWS 账户的访问权限。为确保您的连接器可供其他客户使用，请管理您的 Lambda 函数从其他 AWS 账户到可见连接器的 IAM 访问权限。 在将连接器设置为其他托管集成客户可见之前，请查看管理连接器共享和访问权限的 AWS 服务 条款和组织政策。