使用 C2C Cloud-to-Cloud) 連接器

使用 C2C 連接器的步驟：

1. CreateCloudConnector

   設定連接器以啟用受管整合和第三方供應商雲端之間的雙向通訊。

   設定連接器時，請提供下列詳細資訊：

   • 名稱：選擇連接器的描述性名稱。

   • 描述：提供連接器目的和功能的簡短摘要。

   • AWS Lambda ARN：指定將為連接器供電之 AWS Lambda 函數的 Amazon Resource Name (ARN)。

   建置和部署 AWS Lambda 函數，以與第三方廠商 APIs通訊來建立連接器。接著，在受管整合中呼叫 CreateCloudConnector 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"
   }

   建立流程：

   

   注意

   視需要使用 GetCloudConnector、UpdateCloudConnector、DeleteCloudConnector 和 ListCloudConnectors APIs。

2. CreateConnectorDestination

   設定目的地以提供連接器與第三方廠商雲端建立安全連線所需的設定和授權登入資料。使用目的地向受管整合註冊您的第三方授權憑證。

   現在支援兩種授權類型：

   • OAuth 2.0 - 適用於使用 OAuth 授權的平台 （授權 URL、字符 URL、用戶端憑證）

   • GeneralAuthorization - 適用於使用 API 金鑰、承載字符或任何非 OAuth 授權機制的平台

   先決條件

   建立 ConnectorDestination 之前，您必須：

   • 呼叫 CreateCloudConnector API 來建立連接器。函數傳回的 ID 用於 CreateConnectorDestination API 呼叫。

   • 對於 OAuth 授權：

     • 擷取第三方平台tokenUrl的 （以交換 accessToken 的 authCode)

     • 擷取第三方平台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 目前也在我們的 ConnectorDestination 中同時支援 OAuth 和 GeneralAuthorization。

   雲端目的地建立流程：

   

   注意

   視需要使用 GetConnectorDestination、UpdateConnectorDestination、DeleteConnectorDestination 和 ListConnectorDestinations APIs。

3. CreateAccountAssociation

   關聯代表最終使用者的第三方雲端帳戶與連接器目的地之間的關係。建立關聯並將最終使用者連結至受管整合之後，即可透過唯一的關聯 ID 存取其裝置。此整合可啟用三個關鍵函數：探索裝置、傳送命令和接收事件。

   先決條件

   在建立 AccountAssociation 之前，您必須完成下列操作：

   • 呼叫 CreateConnectorDestination API 來建立目的地。函數傳回的 ID 用於 CreateAccountAssociation API 呼叫。

   • 叫用 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 授權 URL

   注意

   視需要使用 GetAccountAssociation、UpdateAccountAssociation、DeleteAccountAssociation 和 ListAccountAssociations APIs。

   AccountAssociation 具有從 GetAccountAssociation 和 ListAccountAssociations APIs 查詢的狀態。這些 APIs會顯示關聯的狀態。StartAccountAssociationRefresh API 允許在其重新整理權杖過期時重新整理 AccountAssociation 狀態。

4. 裝置探索

   每個受管物件都會連結到裝置特定的詳細資訊，例如其序號和資料模型。資料模型說明裝置的功能，指出裝置是燈泡、開關、調溫器或其他類型的裝置。探索第三方裝置和建立 managedThings 有兩種工作流程：傳統探索流程和預先加入的探索流程。

   1. 選項 1：傳統裝置探索流程

      當您事先不知道連接器裝置 IDs時，請使用此工作流程。此流程會探索與 帳戶相關聯的所有裝置，並可讓您選擇要加入的裝置。

      1. 呼叫 StartDeviceDiscovery API 以啟動裝置探索程序。

         StartDeviceDiscovery API 請求和回應範例：

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

      2. 叫用 GetDeviceDiscovery API 來檢查探索程序的狀態。

      3. 叫用 ListDiscoveredDevices 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"
         }

      4. 叫用 CreateManagedThing API，從探索清單中選擇要匯入受管整合的裝置。

         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. 叫用 GetManagedThing API 來檢視這個新建立的 managedThing。狀態為 UNASSOCIATED。

      6. 叫用 RegisterAccountAssociation API 將此managedThing與特定 建立關聯accountAssociation。在成功的 RegisterAccountAssociation API 結束時，狀態會managedThing變更為 ACTIVATED 狀態。

         RegisterAccountAssociation API 請求和回應範例：

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

   2. 選項 2：預先加入的裝置探索流程

      當您在加入之前已經知道連接器裝置 IDs 時，請使用此工作流程。此流程適用於預先佈建的裝置，或您想要從較大的集合選擇性地加入特定裝置時。此方法可減少完全註冊和啟用裝置所需的 API 呼叫次數。

      重要

      若要使用預先加入的雲端探索流程，您必須先知道 connectorDeviceId（連接器裝置識別符），才能啟動裝置加入程序。此識別符是從第三方供應商的平台或在裝置佈建期間取得。

      1. 使用PRE_ONBOARDED_CLOUD身分驗證材料類型叫用 CreateManagedThing API。這會建立具有多個帳戶關聯的PRE_ASSOCIATED狀態 managedThing。

         CreateManagedThing API 請求和回應範例 （預先加入）：

         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>:...指定一或多個帳戶關聯 IDs。

      2. （選用） 叫用 GetManagedThing API 以驗證 managedThing 處於 PRE_ASSOCIATED 狀態。

      3. 使用 connectorDeviceIdList 參數呼叫 StartDeviceDiscovery API，以僅探索預先加入的裝置。

         具有 connectorDeviceIdList 的 StartDeviceDiscovery API 請求範例：

         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，探索程序只會傳回符合指定連接器裝置 IDs的裝置。連接器會透過 SendConnectorEvent 傳送DEVICE_DISCOVERY事件，其中包含探索到的裝置資訊。

      4. 探索成功完成後，受管整合會自動將預先加入的 managedThings 註冊至其相關聯的帳戶關聯。managedThing 從 轉換為 PRE_ASSOCIATED ACTIVATED 狀態。

         注意

         如果自動註冊失敗且 managedThing 保持 DISCOVERED 狀態，您可以手動調用 RegisterAccountAssociation API 作為備用以完成註冊程序。

      5. （選用） 叫用 GetManagedThing API 來驗證 managedThing 現在處於 ACTIVATED 狀態。

5. 將命令傳送至第三方裝置

   若要控制新加入的裝置，請使用 SendManagedThingCommand API，搭配先前建立的關聯 ID 和以裝置支援的功能為基礎的控制動作。連接器使用帳戶連結程序中儲存的登入資料來驗證第三方雲端，並叫用 操作的相關 API 呼叫。

   注意

   對於 GeneralAuthorization，連接器會使用 AccountAssociation 中指定的授權資料名稱，從 Secrets Manager 擷取授權資料 (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"
   }

   將命令傳送至第三方裝置流程：

   

6. 連接器將事件傳送至受管整合

   SendConnectorEvent API 會擷取從連接器到受管整合的四種事件類型，以操作類型參數的下列列舉值表示：

   • DEVICE_COMMAND_RESPONSE：連接器為了回應命令而傳送的非同步回應。

   • DEVICE_DISCOVERY：為了回應裝置探索程序，連接器會將探索到的裝置清單傳送至受管整合，並使用 SendConnectorEvent API。

   • DEVICE_EVENT：傳送收到的裝置事件。

   • DEVICE_COMMAND_REQUEST：從裝置啟動的命令請求。例如，WebRTC 工作流程。

   連接器也可以使用 SendConnectorEvent API 搭配選用userId參數轉送裝置事件。

   注意

   對於 GeneralAuthorization：使用 GeneralAuthorization 時，對於每個 Secrets ARN 和版本，userId 必須是唯一的。

   • 對於具有 的裝置事件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 可見選項，將連接器 ID 提交至 AWS 以供檢閱。核准後，連接器可供相同 中的所有受管整合使用者使用 AWS 區域。此外，您可以透過修改連接器相關聯 AWS Lambda 函數上的存取政策，限制對特定 AWS 帳戶 IDs 的存取。為了確保您的連接器可供其他客戶使用，請管理 Lambda 函數上從其他 AWS 帳戶到可見連接器的 IAM 存取許可。

   在讓其他受管整合客戶看見連接器之前，請檢閱管理連接器共用和存取許可 AWS 服務 的條款和組織的政策。