使用 C2C (Cloud-to-Cloud) 连接器

使用 C2C 连接器的步骤：

1. CreateCloudConnector

   配置连接器以启用托管集成与第三方供应商云之间的双向通信。

   设置连接器时，请提供以下详细信息：

   • 名称：为连接器选择一个描述性名称。

   • 描述：简要概述连接器的用途和功能。

   • AWS Lambda ARN：指定为连接器供电的 AWS Lambda 函数的亚马逊资源名称 (ARN)。

   构建和部署与第三方供应商 API 通信的 AWS Lambda 函数，以创建连接器。接下来，在托管集成中调用 CreateCloudConnectorAPI，并提供 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"
   }

   创作流程：

   

   注意

   根据需要使用本过程的GetCloudConnectorUpdateCloudConnectorDeleteCloudConnector、、和 ListCloudConnectorsAPI。

2. CreateConnectorDestination

   配置目标以提供连接器与第三方供应商云建立安全连接所需的设置和授权凭据。使用目标向托管集成注册您的第三方授权凭证。

   现在支持两种授权类型：

   • OAuth 2.0-适用于使用 OAuth 授权的平台（授权网址、令牌网址、客户端凭证）

   • GeneralAuthorization-适用于使用 API 密钥、不记名令牌或任何非 OAuth 授权机制的平台

   先决条件

   在创建之前 ConnectorDestination，您必须：

   • 调用 CreateCloudConnectorAPI 创建连接器。在 CreateConnectorDestinationAPI API 调用中使用该函数返回的 ID。

   • 如需获得 OAuth 授权：

     • 检索第三方平台tokenUrl的（用 authCode 兑换 AccessToken）

     • 检索第三方平台的（用于最终用户授权）authUrl

     • 把clientId和存放clientSecret进去 AWS Secrets Manager

   • 对于 GeneralAuthorization：

     • 将您的授权材料（API 密钥、不记名令牌等）存储在 AWS Secrets Manager

     • 每份授权材料都需要一个名称和 Secrets Manager 参考文献

   CreateConnectorDestination API 请求示例 (OAuth)：

   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": "<connectorId>",
       "SecretsManager": {
           "arn": "arn:aws:secretsmanager:*****:secret:*******",
           "versionId": "********"
       },
       "ClientToken": "***"
   }
   
   Response:
   
   {
       "Id":"string"
   }

   CreateConnectorDestination API 请求示例 (GeneralAuthorization)：

   Request:
   
   {
       "Name": "CreateConnectorDestination",
       "Description": "GeneralAuthorization test destination",
       "AuthConfig": {
           "GeneralAuthorization": {
               "AuthMaterials": [
                   {
                       "AuthMaterialName": "AuthKey1",
                       "SecretsManager": {
                           "arn": "arn:aws:secretsmanager:*****:secret:*******",
                           "versionId": "********"
                       }
                   }
               ]
           }
       },
       "CloudConnectorId": "<connectorId>",
       "ClientToken": "***"
   }
   
   Response:
   
   {
       "Id": "string"
   }

   以下方面的主要区别 GeneralAuthorization：

   • 无需填AuthType写字段

   • 无需顶级SecretsManager字段

   • 使用AuthConfig.GeneralAuthorization.AuthMaterials数组

   • 每个身份验证材料都有自己的名称和自己的 Secrets Manager 参考文献

   • 支持多种身份验证材料，以备将来的用例使用

   目前， ConnectorDestination 还支持OAuth GeneralAuthorization 以及我们的。 ConnectorDestination

   云目标创建流程：

   

   注意

   根据需要使用本过程的GetConnectorDestinationUpdateConnectorDestinationDeleteConnectorDestination、、和 ListConnectorDestinationsAPI。

3. CreateAccountAssociation

   关联表示最终用户的第三方云账户与连接器目标之间的关系。在创建关联并将最终用户与托管集成关联后，他们的设备可通过唯一的关联 ID 进行访问。这种集成支持三个关键功能：发现设备、发送命令和接收事件。

   先决条件

   在创建之前，AccountAssociation您必须完成以下操作：

   • 调用 CreateConnectorDestinationAPI 创建目的地。该函数返回的 ID 将用于 CreateAccountAssociationAPI 调用。

   • 调用 CreateAccountAssociation API。

   CreateAccountAssociation API 请求示例 (OAuth)：

   Request:
   
   {
       "Name": "CreateAccountAssociation",
       "Description": "CreateAccountAssociation",
       "ConnectorDestinationId": "<destinationId>",
       "ClientToken": "***"
   }
           
   Response:
   
   {
       "Id":"string"
   }

   CreateAccountAssociation API 请求示例 (GeneralAuthorization)：

   Request:
   
   {
       "Name": "CreateAccountAssociation",
       "Description": "GeneralAuthorization test account association",
       "GeneralAuthorization": {
           "AuthMaterialName": "AuthKey1"
       },
       "ConnectorDestinationId": "<destinationId>",
       "ClientToken": "***"
   }
           
   Response:
   
   {
       "AccountAssociationId": "string",
       "Arn": "string",
       "AssociationState": "ASSOCIATION_SUCCEEDED"
   }

   以下方面的主要区别 GeneralAuthorization：

   • 包括GeneralAuthorization.AuthMaterialName字段

   • 引用中定义的身份验证材料之一 ConnectorDestination

   • 响应中没有 OAuth 授权网址

   注意

   根据需要使用本过程的GetAccountAssociationUpdateAccountAssociationDeleteAccountAssociation、、和 ListAccountAssociationsAPI。

   AccountAssociation具有从GetAccountAssociation和 ListAccountAssociationsAPI 查询的状态。这些 API 显示了协会的状态。StartAccountAssociationRefreshAPI 允许在刷新令牌到期时刷新AccountAssociation状态。

4. 设备发现

   每个托管事物都与设备特定的详细信息相关联，例如其序列号和数据模型。数据模型描述了设备的功能，表明它是灯泡、开关、恒温器还是其他类型的设备。有两种工作流程可用于发现第三方设备和创建 ManagedThings：传统的发现流程和预加载的发现流程。

   1. 选项 1：传统设备发现流程

      如果您事先不知道连接器设备 ID，请使用此工作流程。此流程会发现与账户关联的所有设备，并允许您选择要加入的设备。

      1. 调用 StartDeviceDiscoveryAPI 开始设备发现过程。

         StartDeviceDiscovery API 请求和响应示例：

         Request:
         
         {
             "DiscoveryType": "CLOUD",
             "AccountAssociationId": "*****",
             "ClientToken": "abc"
         }
         
         Response:
         
         {
             "Id": "string",
             "StartedAt": number
         }

      2. 调用 GetDeviceDiscoveryAPI 来检查发现过程的状态。

      3. 调用 ListDiscoveredDevicesAPI 列出发现的设备。

         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"
         }

      4. 调用 CreateManagedThingAPI 从发现列表中选择要导入到托管集成的设备。

         CreateManagedThing API 请求和响应示例：

         Request:
                       
         {
             "Role": "DEVICE",
             "AuthenticationMaterial": "CLOUD:<deviceDiscoveryId>:<connectorDeviceId>",
             "AuthenticationMaterialType": "DISCOVERED_DEVICE",
             "Name": "sample-device-name",
             "ClientToken": "xxx"
         }
         
         Response:
         
         {
            "Arn": "string", // This is the ARN of the managedThing
            "CreatedAt": number,
            "Id": "string" 
         }

      5. 调用 GetManagedThingAPI 来查看这个新创建的managedThing。状态将是UNASSOCIATED。

      6. 调用 RegisterAccountAssociationAPI managedThing 将其与特定关联accountAssociation。成功的 RegisterAccountAssociationAPI 结束后，ACTIVATED状态会managedThing发生变化。

         RegisterAccountAssociation API 请求和响应示例：

         Request:
         
         {
             "AccountAssociationId": "string",
             "DeviceDiscoveryId": "string",
             "ManagedThingId": "string"
         }
         
         Response:
         
         {
             "AccountAssociationId": "string",
             "DeviceDiscoveryId": "string",
             "ManagedThingId": "string"
         }

   2. 选项 2： Pre-onboarded 设备发现流程

      如果您在入门之前已经知道连接器设备 ID，请使用此工作流程。此流程对于预先配置的设备或想要有选择地从更大的设备集中加载特定设备时非常有用。这种方法减少了完全注册和激活设备所需的 API 调用次数。

      重要

      要使用预加载的云发现流程，您必须在启动设备加载流程之前知道connectorDeviceId（连接器设备标识符）。此标识符是从第三方供应商的平台或在设备配置期间获得的。

      1. 使用PRE_ONBOARDED_CLOUD身份验证材料类型调用 CreateManagedThingAPI。这会创建一个处于多个账户关联PRE_ASSOCIATED状态的 ManagedThing。

         CreateManagedThing API 请求和响应示例 (Pre-onboarded)：

         Request:
                       
         {
             "Role": "DEVICE",
             "AuthenticationMaterial": "CLOUD:<connectorDeviceId>:<accountAssociationId1>:<accountAssociationId2>",
             "AuthenticationMaterialType": "PRE_ONBOARDED_CLOUD",
             "Name": "pre-onboarded-device-name",
             "ClientToken": "xxx"
         }
         
         Response:
         
         {
            "Arn": "string", // This is the ARN of the managedThing
            "CreatedAt": number,
            "Id": "string" 
         }

         注意

         预登录设备的AuthenticationMaterial格式是CLOUD:<connectorDeviceId>:<accountAssociationId1>:<accountAssociationId2>:...您可以指定一个或多个账户关联 ID 的格式。

      2. （可选）调用 GetManagedThingAPI 以验证 ManagedThing 是否处于状态。PRE_ASSOCIATED

      3. 使用connectorDeviceIdList参数调用 StartDeviceDiscoveryAPI 以仅发现预装载的设备。

         带连接器 StartDeviceDiscovery 的 API 请求示例DeviceIdList：

         Request:
         
         {
             "DiscoveryType": "CLOUD",
             "AccountAssociationId": "*****",
             "ConnectorDeviceIdList": [
                 "connector-device-id-1",
                 "connector-device-id-2",
                 "connector-device-id-3"
             ],
             "ClientToken": "abc"
         }
         
         Response:
         
         {
             "Id": "string",
             "StartedAt": number
         }

         使用时connectorDeviceIdList，发现过程仅返回与指定连接器设备 ID 匹配的设备。连接器将通过发送SendConnectorEvent包含已发现设备信息DEVICE_DISCOVERY的事件。

      4. 成功完成发现后，托管集成会自动将预先加入的 ManagedThings 注册到其关联的账户关联中。ManagedThing 会从状态过渡PRE_ASSOCIATED到ACTIVATED状态。

         注意

         如果自动注册失败且 ManagedThing 保持DISCOVERED状态，则可以手动调用 RegisterAccountAssociationAPI 作为备用以完成注册过程。

      5. （可选）调用 GetManagedThingAPI 以验证 ManagedThing 现在处于状态。ACTIVATED

5. 向第三方设备发送命令

   要控制新上线的设备，请使用 SendManagedThingCommandAPI，使用之前创建的关联 ID 和基于设备支持的功能的控制操作。连接器使用账户关联过程中存储的凭据向第三方云进行身份验证，并为操作调用相关 API 调用。

   注意

   对于 GeneralAuthorization，连接器使用中指定的授权材料名称从 Secrets Manager 检索授权材料（API 密钥、持有者令牌等）。 AccountAssociation

   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"
   }

   向第三方设备流程发送命令：

   

6. 连接器向托管集成发送事件

   SendConnectorEventAPI 捕获从连接器到托管集成的四种类型的事件，由 O peration Type 参数的以下枚举值表示：

   • D@@ EVICE_COMMAND_RESPONSE：连接器为响应命令而发送的异步响应。

   • DEV@@ ICE_DISCO VERY：为了响应设备发现过程，连接器使用 API 将发现的设备列表发送给托管集成。SendConnectorEvent

   • DEVICE_EVENT：发送收到的设备事件。

   • D@@ EVICE_COMMAND_REQUEST：从设备发起的命令请求。例如，WebRTC工作流程。

   连接器还可以使用带有可选userId参数的 SendConnectorEventAPI 转发设备事件。

   注意

   对于 GeneralAuthorization：使用时 GeneralAuthorization，对于每个密钥 ARN 和版本，用户 ID 必须是唯一的。

   • 对于带有以下内容的设备事件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
   
   

   发送事件流：

   

7. 将连接器状态更新为 “已上市”，使其对其他托管集成客户可见

   默认情况下，连接器是私有的，只有创建连接器的 AWS 账户才能看见。您可以选择让其他托管集成客户看到连接器。

   要与其他用户共享您的连接器，请使用连接器详细信息页面 AWS 管理控制台 上的 “设为可见” 选项，将您的连接器 ID 提交给以 AWS 供审核。一旦获得批准，该连接器便可供所有托管集成用户使用。 AWS 区域此外，您可以通过修改连接器关联 AWS Lambda 功能的访问策略来限制对特定 AWS 账户 ID 的访问。为确保您的连接器可供其他客户使用，请管理您的 Lambda 函数从其他 AWS 账户到可见连接器的 IAM 访问权限。

   在将连接器设置为其他托管集成客户可见之前，请查看管理连接器共享和访问权限的 AWS 服务 条款和组织政策。