Utiliser un connecteur C2C (Cloud-to-Cloud)

Un connecteur C2C gère la traduction des messages de demande et de réponse et permet la communication entre les intégrations gérées et le cloud d'un fournisseur tiers. Il facilite le contrôle unifié entre différents types d'appareils, plateformes et protocoles, permettant d'intégrer et de gérer des appareils tiers.

La procédure suivante répertorie les étapes d'utilisation du connecteur C2C.

Étapes d'utilisation du connecteur C2C :

CreateCloudConnector

Configurez un connecteur pour permettre une communication bidirectionnelle entre vos intégrations gérées et les clouds de fournisseurs tiers.

Lors de la configuration du connecteur, fournissez les informations suivantes :
- Nom : Choisissez un nom descriptif pour le connecteur.
- Description : fournissez un bref résumé de l'objectif et des fonctionnalités du connecteur.
- AWS Lambda ARN : Spécifiez l'Amazon Resource Name (ARN) de la AWS Lambda fonction qui alimentera le connecteur.
Créez et déployez une AWS Lambda fonction qui communique avec les API de fournisseurs tiers pour créer un connecteur. Ensuite, appelez l'CreateCloudConnectorAPI dans les intégrations gérées et fournissez la AWS Lambda fonction ARN pour l'enregistrement. Assurez-vous que la AWS Lambda fonction est déployée dans le AWS compte où vous avez créé le connecteur dans les intégrations gérées. Un identifiant de connecteur unique vous sera attribué pour identifier l'intégration.

Exemple de demande et de réponse à l' 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"
}
```
Flux de création :

Note
Utilisez les ListCloudConnectorsAPI GetCloudConnector UpdateCloudConnector, DeleteCloudConnector, et selon les besoins pour cette procédure.
CreateConnectorDestination

Configurez les destinations pour fournir les paramètres et les informations d'autorisation dont les connecteurs ont besoin pour établir des connexions sécurisées avec les clouds de fournisseurs tiers. Utilisez Destinations pour enregistrer vos informations d'identification d'autorisation tierces auprès d'intégrations gérées.

Deux types d'autorisation sont désormais pris en charge :
- OAuth 2.0 - Pour les plateformes utilisant l'autorisation OAuth (URL d'autorisation, URL du jeton, informations d'identification du client)
- GeneralAuthorization- Pour les plateformes utilisant des clés API, des jetons porteurs ou tout autre mécanisme d'autorisation non OAuth
Conditions préalables

Avant de créer un ConnectorDestination, vous devez :
- Appelez l'CreateCloudConnectorAPI pour créer un connecteur. L'ID renvoyé par la fonction est utilisé dans l'appel d'CreateConnectorDestinationAPI.
- Pour l'autorisation OAuth :
  - Récupérez le tokenUrl pour la plateforme tierce (pour échanger un AuthCode contre un AccessToken)
  - Récupérez le authUrl pour la plate-forme tierce (pour l'autorisation de l'utilisateur final)
  - Rangez clientId le clientSecret sable AWS Secrets Manager
- Pour GeneralAuthorization :
  - Stockez vos documents d'autorisation (clés API, jetons porteurs, etc.) dans AWS Secrets Manager
  - Chaque document d'autorisation doit comporter un nom et une référence à Secrets Manager
Exemple de demande d' 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"
}
```
Exemple de demande d' 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"
}
```
Principales différences pour GeneralAuthorization :
- Aucun AuthType champ requis
- Aucun SecretsManager champ de niveau supérieur n'est requis
- Utilise AuthConfig.GeneralAuthorization.AuthMaterials un tableau
- Chaque matériel d'authentification possède un nom et sa propre référence Secrets Manager.
- Supporte plusieurs supports d'authentification pour les futurs cas d'utilisation
Actuellement, prend ConnectorDestination également en charge OAuth et GeneralAuthorization ensemble dans notre. ConnectorDestination

Flux de création de destinations cloud :

Note
Utilisez les ListConnectorDestinationsAPI GetConnectorDestination UpdateConnectorDestination, DeleteConnectorDestination, et selon les besoins pour cette procédure.
CreateAccountAssociation

Les associations représentent les relations entre les comptes cloud tiers des utilisateurs finaux et une destination de connecteur. Après avoir créé une association et lié les utilisateurs finaux à des intégrations gérées, leurs appareils sont accessibles via un identifiant d'association unique. Cette intégration permet trois fonctions clés : découvrir des appareils, envoyer des commandes et recevoir des événements.

Conditions préalables

Avant de créer un, AccountAssociationvous devez effectuer les opérations suivantes :
- Appelez l'CreateConnectorDestinationAPI pour créer une destination. L'ID renvoyé par la fonction est utilisé dans l'appel CreateAccountAssociationd'API.
- Appelez l'CreateAccountAssociationAPI.
Exemple de demande d' CreateAccountAssociation API (OAuth) :
```
Request:

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

{
    "Id":"string"
}
```
Exemple de demande d' 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"
}
```
Principales différences pour GeneralAuthorization :
- GeneralAuthorization.AuthMaterialNameChamp inclus
- Fait référence à l'un des matériaux d'authentification définis dans le ConnectorDestination
- Aucune URL d'autorisation OAuth dans la réponse
Note
Utilisez les ListAccountAssociationsAPI GetAccountAssociation UpdateAccountAssociation, DeleteAccountAssociation, et selon les besoins pour cette procédure.

An AccountAssociationpossède un état qui est interrogé par GetAccountAssociationet ListAccountAssociationspar des API. Ces API indiquent l'état de l'association. L'StartAccountAssociationRefreshAPI permet d'actualiser un AccountAssociationétat lorsque son jeton d'actualisation expire.
Découverte des appareils

Chaque objet géré est lié à des informations spécifiques à l'appareil, telles que son numéro de série et un modèle de données. Le modèle de données décrit les fonctionnalités de l'appareil, indiquant s'il s'agit d'une ampoule, d'un interrupteur, d'un thermostat ou d'un autre type d'appareil. Il existe deux flux de travail pour découvrir des appareils tiers et créer ManagedThings : le flux de découverte traditionnel et le flux de découverte préintégré.
1. Option 1 : flux de découverte des appareils traditionnel
  
  Utilisez ce flux de travail lorsque vous ne connaissez pas à l'avance les identifiants des connecteurs. Ce flux découvre tous les appareils associés à un compte et vous permet de sélectionner les appareils à intégrer.
  1. Appelez StartDeviceDiscoveryl'API pour démarrer le processus de découverte des appareils.
    
    Exemple de demande et de réponse à l' StartDeviceDiscovery API :
```
Request:

{
    "DiscoveryType": "CLOUD",
    "AccountAssociationId": "*****",
    "ClientToken": "abc"
}

Response:

{
    "Id": "string",
    "StartedAt": number
}
```
  2. Appelez GetDeviceDiscoveryl'API pour vérifier l'état du processus de découverte.
  3. Appelez ListDiscoveredDevicesl'API pour répertorier les appareils découverts.
    
    Exemple de demande et de réponse à l' 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. Appelez CreateManagedThingl'API pour sélectionner les appareils de la liste de découverte à importer dans les intégrations gérées.
    
    Exemple de demande et de réponse à l' 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. Appelez GetManagedThingl'API pour afficher cette nouvelle créationmanagedThing. Le statut seraUNASSOCIATED.
  6. Appelez RegisterAccountAssociationl'API pour l'associer managedThing à un élément spécifiqueaccountAssociation. À la fin d'une RegisterAccountAssociationAPI réussie, l'état managedThing passe à ACTIVATED l'état.
    
    Exemple de demande et de réponse à l' RegisterAccountAssociation API :
```
Request:

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

Response:

{
    "AccountAssociationId": "string",
    "DeviceDiscoveryId": "string",
    "ManagedThingId": "string"
}
```
2. Option 2 : flux de découverte des Pre-onboarded appareils
  
  Utilisez ce flux de travail lorsque vous connaissez déjà les identifiants des appareils du connecteur avant l'intégration. Ce flux est utile pour les appareils préconfigurés ou lorsque vous souhaitez intégrer de manière sélective des appareils spécifiques à partir d'un ensemble plus important. Cette approche réduit le nombre d'appels d'API nécessaires pour enregistrer et activer complètement les appareils.
  
  Important
  Pour utiliser le flux de découverte du cloud préintégré, vous devez connaître le connectorDeviceId (identifiant du périphérique connecteur) avant de lancer le processus d'intégration du terminal. Cet identifiant est obtenu sur la plateforme du fournisseur tiers ou lors du provisionnement de l'appareil.
  1. Appelez CreateManagedThingl'API avec le type de matériel d'PRE_ONBOARDED_CLOUDauthentification. Cela crée un ManagedThing en PRE_ASSOCIATED état avec plusieurs associations de comptes.
    
    Exemple de demande et de réponse d' 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" 
}
```
    Note
    Le AuthenticationMaterial format des appareils préintégrés est celui dans CLOUD:<connectorDeviceId>:<accountAssociationId1>:<accountAssociationId2>:... lequel vous pouvez spécifier un ou plusieurs identifiants d'association de comptes.
  2. (Facultatif) Appelez GetManagedThingl'API pour vérifier que le ManagedThing est en PRE_ASSOCIATED état.
  3. Appelez StartDeviceDiscoveryl'API avec le connectorDeviceIdList paramètre pour découvrir uniquement les appareils pré-intégrés.
    
    Exemple de demande d' StartDeviceDiscovery API avec connecteur 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
}
```
    Lors de l'utilisationconnectorDeviceIdList, le processus de découverte renvoie uniquement les appareils correspondant aux identifiants de périphériques de connecteur spécifiés. Le connecteur enverra un DEVICE_DISCOVERY événement SendConnectorEventavec les informations du périphérique découvert.
  4. Une fois la découverte terminée avec succès, les intégrations gérées enregistrent automatiquement les ManagedThings préintégrés dans leurs associations de comptes associées. Le ManagedThing passe de l'état PRE_ASSOCIATED à l'état. ACTIVATED
    
    Note
    Si l'enregistrement automatique échoue et que le ManagedThing reste en DISCOVERED état, vous pouvez appeler manuellement l'RegisterAccountAssociationAPI comme solution de secours pour terminer le processus d'enregistrement.
  5. (Facultatif) Appelez GetManagedThingl'API pour vérifier que le ManagedThing est maintenant en ACTIVATED état.
Envoyer une commande à l'appareil tiers

Pour contrôler un appareil récemment intégré, utilisez l'SendManagedThingCommandAPI, avec l'ID d'association créé précédemment et une action de contrôle basée sur les fonctionnalités prises en charge par l'appareil. Le connecteur utilise les informations d'identification stockées lors du processus de liaison des comptes pour s'authentifier auprès du cloud tiers et appeler l'appel d'API correspondant à l'opération.

Note
En GeneralAuthorization effet, le connecteur récupère le matériel d'autorisation (clé API, jeton porteur, etc.) auprès de Secrets Manager en utilisant le nom du matériel d'autorisation spécifié dans le. AccountAssociation

Exemple de demande et de réponse à l' 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"
}
```
Envoyer la commande au flux de périphériques tiers :
Le connecteur envoie des événements aux intégrations gérées

L'SendConnectorEventAPI capture quatre types d'événements, du connecteur aux intégrations gérées, représentés par les valeurs d'énumération suivantes pour le paramètre Operation Type :
- DEVICE_COMMAND_RESPONSE : réponse asynchrone envoyée par le connecteur en réponse à une commande.
- DEVICE_DISCOVERY : En réponse à un processus de découverte d'appareils, le connecteur envoie la liste des appareils découverts aux intégrations gérées, il utilise l'API. SendConnectorEvent
- DEVICE_EVENT : envoie les événements de l'appareil reçus.
- DEVICE_COMMAND_REQUEST : demandes de commande lancées depuis le périphérique. Par exemple, les flux de travail WebRTC.
Le connecteur peut également transmettre les événements de l'appareil à l'aide de l'SendConnectorEventAPI, avec un userId paramètre facultatif.

Note
Pour GeneralAuthorization : lors de l'utilisation GeneralAuthorization, pour chaque ARN et version de Secrets, l'userID doit être unique.
- Pour les événements liés à un appareil avec userId :
  
  Exemple de demande et de réponse à l' SendConnectorEvent API :
```
Request:

{
    "UserId": "*****",
    "Operation": "DEVICE_EVENT",
    "OperationVersion": "1.0",
    "StatusCode": 200,
    "ConnectorId": "****",
    "ConnectorDeviceId": "***",
    "TraceId": "***",
    "MatterEndpoint": {
        "id": "**",
        "clusters": [{
            .....
            }
        }]
    }
}

Response:

{
    "ConnectorId": "string"
}
```
- Pour les événements liés à un appareil sans userId :
  
  Exemple de demande et de réponse à l' SendConnectorEvent API :
```
Request:

{
    "Operation": "DEVICE_EVENT",
    "OperationVersion": "1.0",
    "StatusCode": 200,
    "ConnectorId": "*****",
    "ConnectorDeviceId": "****",
    "TraceId": "****",
    "MatterEndpoint": {
        "id": "**",
        "clusters": [{
            ....
        }]
    }
}

Response:

{
    "ConnectorId": "string"
}
```
Pour supprimer le lien entre un compte en particulier managedThing et une association de comptes, utilisez le mécanisme de désenregistrement :

Exemple de demande et de réponse à l' DeregisterAccountAssociation API :
```
Request:

{
    "AccountAssociationId": "****",
    "ManagedThingId": "****"
}

Response:

HTTP/1.1 200 // Empty body
```
Envoyer le flux d'événements :
Mettez à jour le statut du connecteur sur « Listé » pour le rendre visible aux autres clients des intégrations gérées

Par défaut, les connecteurs sont privés et ne sont visibles que par le AWS compte qui les a créés. Vous pouvez choisir de rendre un connecteur visible pour les autres clients des intégrations gérées.

Pour partager votre connecteur avec d'autres utilisateurs, utilisez l'option Rendre visible Console de gestion AWS sur la page de détails du connecteur pour soumettre votre identifiant de connecteur à des AWS fins de révision. Une fois approuvé, le connecteur est accessible à tous les utilisateurs des intégrations gérées de la même manière Région AWS. En outre, vous pouvez restreindre l'accès à des identifiants de AWS compte spécifiques en modifiant la politique d'accès relative à la AWS Lambda fonction associée au connecteur. Pour vous assurer que votre connecteur est utilisable par d'autres clients, gérez les autorisations d'accès IAM sur votre fonction Lambda depuis AWS d'autres comptes vers votre connecteur visible.

Passez en revue les Service AWS conditions et les politiques de votre organisation qui régissent le partage des connecteurs et les autorisations d'accès avant de rendre les connecteurs visibles aux autres clients des intégrations gérées.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.