C2C (Cloud-to-Cloud) コネクタを使用する

C2C コネクタを使用する手順:

1. CreateCloudConnector

   マネージド統合とサードパーティーベンダークラウド間の双方向通信を有効にするようにコネクタを設定します。

   コネクタを設定するときは、次の詳細を指定します。

   • 名前: コネクタのわかりやすい名前を選択します。

   • 説明: コネクタの目的と機能の概要を提供します。

   • AWS Lambda ARN: コネクタに電力を供給する AWS Lambda 関数の Amazon リソースネーム (ARN) を指定します。

   サードパーティーベンダー APIsしてコネクタを作成する AWS Lambda 関数を構築およびデプロイします。次に、マネージド統合内で 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

   送信先を設定して、コネクタがサードパーティーベンダークラウドとの安全な接続を確立するために必要な設定と認可認証情報を提供します。Destinations を使用して、サードパーティーの認可認証情報を マネージド統合に登録します。

   2 つの認可タイプがサポートされるようになりました。

   • OAuth 2.0 - OAuth 認可を使用するプラットフォームの場合 (認可 URL、トークン URL、クライアント認証情報)

   • GeneralAuthorization - API キー、ベアラートークン、または非 OAuth 認可メカニズムを使用するプラットフォームの場合

   前提条件

   ConnectorDestination を作成する前に、以下を行う必要があります。

   • CreateCloudConnector API を呼び出してコネクタを作成します。関数が返す ID は、CreateConnectorDestination API コールで使用されます。

   • 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 は ConnectorDestination で OAuth と GeneralAuthorization も一緒にサポートしています。

   クラウド送信先の作成フロー:

   

   注記

   この手順では、必要に応じて GetConnectorDestination、UpdateConnectorDestination、DeleteConnectorDestination、および ListConnectorDestinations APIs を使用します。

3. CreateAccountAssociation

   関連付けは、エンドユーザーのサードパーティーのクラウドアカウントとコネクタの送信先との関係を表します。関連付けを作成し、エンドユーザーをマネージド統合にリンクすると、そのデバイスは一意の関連付け ID を介してアクセスできるようになります。この統合により、デバイスの検出、コマンドの送信、イベントの受信の 3 つの主要な機能が有効になります。

   前提条件

   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 で定義されている認証マテリアルの 1 つを参照します

   • レスポンスに OAuth 認可 URL がない

   注記

   この手順では、必要に応じて GetAccountAssociation、UpdateAccountAssociation、DeleteAccountAssociation、および ListAccountAssociations APIs を使用します。

   AccountAssociation には、GetAccountAssociation API と ListAccountAssociations APIs。これらの APIs、関連付けの状態を示します。StartAccountAssociationRefresh API を使用すると、更新トークンの有効期限が切れたときに AccountAssociation 状態を更新できます。

4. デバイス検出

   各マネージドモノは、シリアル番号やデータモデルなど、デバイス固有の詳細にリンクされます。データモデルは、デバイスの機能を記述し、電球、スイッチ、サーモスタット、または別のタイプのデバイスであるかどうかを示します。サードパーティーのデバイスを検出し、managedThings を作成するためのワークフローは 2 つあります。従来の検出フローとオンボーディング済みの検出フローです。

   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 が正常に終了すると、 は ACTIVATED状態managedThingに変更されます。

         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 を呼び出します。これにより、複数のアカウント関連付けを持つ managedThing in PRE_ASSOCIATED状態が作成されます。

         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形式は、1 つ以上のアカウント関連付け ID を指定できる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 に一致するデバイスのみを返します。コネクタは、検出されたデバイス情報を含むDEVICE_DISCOVERYイベントを SendConnectorEvent 経由で送信します。

      4. 検出が正常に完了すると、マネージド統合は、事前にオンボーディングされた managedThings を関連するアカウントの関連付けに自動的に登録します。managedThing が 状態から ACTIVATED状態に移行PRE_ASSOCIATEDします。

         注記

         自動登録が失敗し、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 は、コネクタからマネージド統合への 4 種類のイベントをキャプチャします。これは、Operation Type パラメータの次の列挙値で表されます。

   • DEVICE_COMMAND_RESPONSE: コマンドに応答してコネクタが送信する非同期レスポンス。

   • DEVICE_DISCOVERY: デバイス検出プロセスに応答して、コネクタは検出されたデバイスのリストをマネージド統合に送信し、SendConnectorEvent API を使用します。

   • DEVICE_EVENT: 受信したデバイスイベントを送信します。

   • DEVICE_COMMAND_REQUEST: デバイスから開始されたコマンドリクエスト。例えば、WebRTC ワークフローなどです。

   コネクタは、オプションの userIdパラメータを指定して、SendConnectorEvent API を使用してデバイスイベントを転送することもできます。

   注記

   GeneralAuthorization の場合: GeneralAuthorization を使用する場合、シークレット 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. コネクタのステータスを「Listed」に更新して、他のマネージド統合のお客様に表示されるようにします。

   デフォルトでは、コネクタはプライベートであり、それらを作成した AWS アカウントにのみ表示されます。コネクタを他のマネージド統合のお客様に表示することを選択できます。

   コネクタを他のユーザーと共有するには、コネクタの詳細ページの の表示オプションを使用して、レビュー AWS のためにコネクタ ID AWS マネジメントコンソール を に送信します。承認されると、コネクタは同じ 内のすべてのマネージド統合ユーザーが使用できます AWS リージョン。さらに、コネクタの関連 AWS Lambda 関数のアクセスポリシーを変更することで、特定の AWS アカウント IDs へのアクセスを制限できます。コネクタを他のお客様が使用できるようにするには、Lambda 関数の IAM アクセス許可を他の AWS アカウントから可視コネクタに管理します。

   コネクタを他のマネージド統合の顧客に表示する前に、コネクタの共有とアクセス許可を管理する AWS のサービス 用語と組織のポリシーを確認してください。