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 un fournisseur tiers APIs 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 le GetCloudConnector, UpdateCloudConnector DeleteCloudConnector, et selon ListCloudConnectors APIs les besoins pour cette procédure.
CreateConnectorDestination

Configurez les destinations pour fournir les paramètres et les informations d'authentification 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'authentification tierces avec des intégrations gérées, telles que les détails d'autorisation OAuth 2.0, y compris l'URL d'autorisation, le schéma d'authentification et l'emplacement des informations d'identification qu'ils contiennent. AWS Secrets Manager

Prérequis

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.
- Récupérez le tokenUrl pour la plate-forme 3P du connecteur. (Vous pouvez échanger un AuthCode contre un AccessToken).
- Récupérez l'AuthURL de la plate-forme 3P du connecteur. (Les utilisateurs finaux peuvent s'authentifier à l'aide de leur nom d'utilisateur et de leur mot de passe).
- Utilisez le clientId et clientSecret (depuis la plateforme 3P) dans le gestionnaire secret de votre compte.
Exemple de demande et de réponse à l' 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": "<connectorId>", // The connectorID instance from response of Step 1.
    "SecretsManager": {
        "arn": "arn:aws:secretsmanager:*****:secret:*******",
        "versionId": "********"
    },
    "ClientToken": "***"
}

Response:

{
    "Id":"string"
}
```
Flux de création de destinations cloud :

Note
Utilisez le GetCloudConnector, UpdateCloudConnector DeleteCloudConnector, et selon ListCloudConnectors APIs 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 : la découverte d'appareils, l'envoi de commandes et la réception d'événements.

Prérequis

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 et de réponse à l' CreateAccountAssociation API :
```
Request:

{
    "Name": "CreateAccountAssociation",
    "Description": "CreateAccountAssociation",
    "ConnectorDestinationId": "<destinationId>", //The destinationID from destination creation.
    "ClientToken": "***"
}
        
Response:

{
    "Id":"string"
}
```
Note
Utilisez le GetCloudConnector, UpdateCloudConnector DeleteCloudConnector, et selon ListCloudConnectors APIs les besoins pour cette procédure.

An AccountAssociationpossède un état qui est demandé à partir GetAccountAssociationde et. ListAccountAssociations APIs Cela APIs montre 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. Pour découvrir un appareil 3P et créer un ManagedThing pour l'appareil 3P, vous devez suivre les étapes ci-dessous dans l'ordre.
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:XXXX:<connectorDeviceId1>",
    "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 à ASSOCIATED 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"
}
```

Envoyer une commande à l'appareil 3P

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.

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 3P :

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.
- 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 « Répertorié » 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 AWS Management Console 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 à un AWS compte spécifique IDs 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.

Conventions de rédaction

Testez manuellement votre connecteur C2C

SDK du hub

Utiliser un connecteur C2C (Cloud-to-Cloud)

Étapes d'utilisation du connecteur C2C :

Note

Note

Note