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 effectuer pour être considéré comme un connecteur. Votre connecteur C2C doit implémenter chacune des opérations suivantes :

Détails de l'invocation

Managed Integrations for AWS IoT Device Management Always invoque la fonction Lambda avec une charge utile de chaîne JSON par le biais de l'action. AWS Lambda invokeFunction Les opérations de demande doivent inclure un operationName champ dans chaque charge utile de demande.

Paramètres d'invocation :

Exemple de mise en œuvre

Le Lambda que vous implémentez pour votre connecteur analysera un extrait 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);
    };
}

Exemples de formats de demande

Les exemples suivants détaillent les demandes de connecteur génériques émanant de Managed Integrations, dans lesquelles des champs communs à chaque interface requise sont présents. À partir des exemples, 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.

Exemple OAuth 2.0 :

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

Exemple d'autorisation générale :

{
        "header": {
                "auth": { 
                        "secretsManager": {
                                "arn": "string",
                                "versionId": "string"
                        },
                        "type": "GeneralAuthorization"
                }
        },
        "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 varient en fonction du type d'autorisation. Votre connecteur doit gérer à la fois les en-têtes de demande OAuth 2.0 et d'autorisation générale.

En-tête par défaut OAuth 2.0 :

{
    "header": {
        "auth": {
            "token": string,    // End user's Access Token
            "type": "OAuth2.0"
        }
    }
}

En-tête par défaut de l'autorisation générale :

{
    "header": {
        "auth": {
            "secretsManager": {
                "arn": "string",
                "versionId": "string"
            },
            "type": "GeneralAuthorization"
        }
    }
}

Charge utile de la demande

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.

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.

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

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

Champ d'en-tête de réponse

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 figurant dans la liste ci-dessous pour les AWS.SendCommand opérations AWS.DiscoverDevices et les opérations, ainsi que les événements proactifs relatifs aux appareils (tels que l'allumage et l'extinction manuels d'un voyant).

Exemple de flux de travail

Si votre connecteur C2C reçoit une DiscoverDevices demande, Managed Integrations for AWS IoT Device Management s'attend à ce qu'il :

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.

SendConnectorEvent API

Votre connecteur appelle cette API d'intégrations gérées pour AWS IoT Device Management afin d'envoyer des événements liés aux appareils. Seuls 3 types d'événements sont acceptés :