Mettre en œuvre les opérations d'interface du connecteur C2C

Managed Integrations for AWS IoT Device Management définit quatre opérations que vous AWS Lambda devez gérer pour être considéré comme un connecteur. Votre connecteur C2C doit implémenter chacune des opérations suivantes :

1. AWS.ActivateUser- Les intégrations gérées pour le AWS IoT Device Management service appellent cette API pour récupérer un identifiant utilisateur unique au monde associé au jeton OAuth2 .0 fourni. Cette opération peut éventuellement être utilisée pour effectuer toute exigence supplémentaire relative au processus de liaison de comptes.

2. AWS.DiscoverDevices- les intégrations gérées pour le service AWS IoT Device Management appelle cette API à votre connecteur pour découvrir les appareils des utilisateurs

3. AWS.SendCommand- intégrations gérées pour le service AWS IoT Device Management appelle cette API à votre connecteur pour envoyer des commandes aux appareils des utilisateurs

4. AWS.DeactivateUser- les intégrations gérées pour le service AWS IoT Device Management appelle cette API à votre connecteur pour désactiver le jeton d'accès de l'utilisateur afin de dissocier votre serveur d'autorisation.

Les intégrations gérées pour AWS IoT Device Management toujours invoquer la fonction Lambda avec une charge utile de chaîne JSON via l'action. AWS Lambda invokeFunction Les opérations de demande doivent inclure un operationName champ dans chaque charge utile de demande. Pour en savoir plus, consultez Invoke dans le guide de référence des AWS Lambda API.

Chaque délai d'invocation est fixé à deux secondes, et si l'appel échoue, il sera réessayé cinq fois.

Le Lambda que vous implémentez pour votre connecteur analysera un élément de la charge utile operationName de la demande et implémentera les fonctionnalités correspondantes pour le mapper vers le cloud tiers :

public ConnectorResponse handleRequest(final ConnectorRequest request) 
        throws OperationFailedException {
    Operation operation;
    try {
        operation = Operation.valueOf(request.payload().operationName());
    } catch (IllegalArgumentException ex) {
        throw new ValidationException(
           "Unknown operation '%s'".formatted(request.payload().operationName()), 
           ex
        );
    }

    return switch (operation) {
        case ActivateUser -> activateUserManager.activateUser(request);
        case DiscoverDevices -> deviceDiscoveryManager.listDevices(request);
        case SendCommand -> sendCommandManager.sendCommand(request);
        case DeactivateUser -> deactivateUser.deactivateUser(request);
    };
}

Note

Le développeur du connecteur doit implémenter les deactivateUser.deactivateUser opérations activateUserManager.activateUser(request)deviceDiscoveryManager.listDevices(request),sendCommandManager.sendCommand(request), et répertoriées dans l'exemple précédent.

L'exemple suivant détaille une demande de connecteur générique provenant d'intégrations gérées, dans laquelle des champs communs à chaque interface requise sont présents. Dans l'exemple, vous pouvez voir qu'il existe à la fois un en-tête de demande et une charge utile de demande. Les en-têtes de requête sont communs à toutes les interfaces d'exploitation.

{
 	"header": {
 		"auth": { 
 			"token": “ashriu32yr97feqy7afsaf”, 
 			"type": “OAuth2.0"
 		}
 	},
 	"payload":{
 		"operationName": "AWS.SendCommand",
 		"operationVersion": "1.0",
 		"connectorId": “exampleId”,
 	…
 	}
}

En-têtes de demande par défaut

Les champs d'en-tête par défaut sont les suivants.

{
    "header": {
        "auth": {                 
            "token": string,    // end user's Access Token
            "type": ENUM ["OAuth2.0"], 
        }
    }
}

Toute API hébergée par un connecteur doit traiter les paramètres d'en-tête suivants :

En-têtes et champs par défaut

Champ	Obligatoire/Facultatif	Description
header:auth	Oui	Informations d'autorisation fournies par le constructeur du connecteur C2C lors de son enregistrement du connecteur.
header:auth:token	Oui	Jeton d'autorisation de l'utilisateur généré par le fournisseur de cloud tiers et lié àconnectorAssociationID.
header:auth:type	Oui	Le type d'autorisation requis.

Note

Le jeton d'accès de l'utilisateur final sera joint à toutes les demandes adressées à votre connecteur. Vous pouvez supposer que la liaison de compte entre l'utilisateur final et le client des intégrations gérées a déjà eu lieu.

Charge utile de la requête

Outre les en-têtes communs, chaque demande aura une charge utile. Bien que cette charge utile contienne des champs uniques pour chaque type d'opération, chaque charge utile possède un ensemble de champs par défaut qui seront toujours présents.

Champs de charge utile de la demande :

• operationName: opération d'une demande donnée, égale à l'une des valeurs suivantes :AWS.ActivateUser,AWS.SendCommand,AWS.DiscoverDevices,AWS.DeactivateUser.

• operationVersion: Chaque opération est versionnée afin de permettre son évolution dans le temps et de fournir une définition d'interface stable pour les connecteurs tiers. Les intégrations gérées transfèrent un champ de version dans la charge utile de toutes les demandes.

• connectorId: ID du connecteur auquel la demande a été envoyée.

En-têtes de réponse par défaut

Chaque opération répondra par une intégration gérée ACK pour AWS IoT Device Management qui confirmera que votre connecteur C2C a reçu la demande et a commencé à la traiter. Voici un exemple générique de cette réponse :

{
 	"header":{
 		"responseCode": 200 
 	},
 	"payload":{
 		"responseMessage": “Example response!”
 	}
}

Chaque réponse d'opération doit avoir l'en-tête commun suivant :

{
    "header": {
        "responseCode": Integer
    }
}

Le tableau suivant répertorie l'en-tête de réponse par défaut :

En-tête et champ de réponse par défaut

Champ	Obligatoire/Facultatif	Commentaire
header:responseCode	Oui	ENUM de valeurs indiquant le statut d'exécution de la demande.

Dans les différentes interfaces de connecteur et schémas d'API décrits dans ce document, il existe un Message champ responseMessage or. Il s'agit d'un champ facultatif utilisé par le connecteur C2C Lambda pour répondre à n'importe quel contexte concernant la demande et son exécution. De préférence, toute erreur entraînant un code d'état autre que 200 doit inclure une valeur de message décrivant l'erreur.

Répondre aux demandes de fonctionnement du connecteur C2C avec l'API SendConnectorEvent

Managed Integrations for AWS IoT Device Management s'attend à ce que votre connecteur se comporte de manière asynchrone pour chaque AWS.SendCommand opération. AWS.DiscoverDevices Cela signifie que la réponse initiale à ces opérations « reconnaît » simplement que votre connecteur C2C a reçu la demande.

À l'aide de l'SendConnectorEventAPI, votre connecteur est censé envoyer les types d'événements de la liste ci-dessous à for AWS.DiscoverDevices and AWS.SendCommand operations, ainsi que des événements proactifs sur les appareils (tels que l'allumage et l'extinction manuels d'un voyant). Pour lire une explication détaillée de ces types d'événements et de leurs cas d'utilisation Implémentez l'AWS. DiscoverDevices opérationImplémentez l'AWS. SendCommand opération, reportez-vous aux sections etEnvoyer des événements liés à un appareil avec l' SendConnectorEventAPI.

Par exemple, si votre connecteur C2C reçoit une DiscoverDevices demande, les intégrations gérées pour AWS IoT Device Management s'attendent à ce qu'il réponde de manière synchrone avec le format de réponse défini ci-dessus. Vous devez ensuite appeler l'SendConnectorEventAPI avec la structure de demande définie dansImplémentez l'AWS. DiscoverDevices opération, pour un événement DEVICE_DISCOVERY. L'appel SendConnectorEvent d'API peut avoir lieu partout où vous avez accès aux informations d'identification Compte AWS Lambda de votre connecteur C2C. Le flux de découverte des appareils échoue tant que Managed Integrations for AWS IoT Device Management n'a pas reçu cet événement.

Note

L'appel d'SendConnectorEventAPI peut également avoir lieu avant la réponse d'appel Lambda du connecteur C2C si nécessaire. Cependant, ce flux contredit le modèle asynchrone du développement logiciel.

• SendConnectorEvent- Votre connecteur appelle cette API Managed Integrations for AWS IoT Device Management pour envoyer les événements liés aux appareils aux intégrations gérées pour AWS IoT Device Management. Seuls 3 types d'événements sont acceptés par les intégrations gérées :

  • « DEVICE_DISCOVERY » — Cette opération événementielle doit être utilisée pour envoyer la liste des appareils découverts dans un cloud tiers pour un jeton d'accès spécifique.

  • « DEVICE_COMMAND_RESPONSE » — Cette opération d'événement doit être utilisée pour envoyer un événement de périphérique spécifique à la suite de l'exécution d'une commande.

  • « DEVICE_EVENT » — Cette opération événementielle doit être utilisée pour tout événement provenant de l'appareil qui n'est pas le résultat direct d'une commande basée sur l'utilisateur. Cela peut servir de type d'événement général pour signaler de manière proactive les modifications de l'état de l'appareil ou les notifications.