Implementazione delle operazioni di interfaccia del connettore C2C

Managed Integrations for AWS IoT Device Management definisce quattro operazioni da gestire per qualificarsi come connettore. AWS Lambda Il connettore C2C deve implementare ognuna delle seguenti operazioni:

Dettagli di chiamata

Managed Integrations for AWS IoT Device Management always richiama la funzione Lambda con un payload di stringa JSON tramite l'azione. AWS Lambda invokeFunction Le operazioni di richiesta devono includere un operationName campo in ogni payload della richiesta.

Impostazioni di chiamata:

Esempio di implementazione

La Lambda implementata per il connettore analizzerà an operationName dal payload della richiesta e implementerà la funzionalità corrispondente da mappare al cloud di terze parti:

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);
    };
}

Esempi di formati di richiesta

Gli esempi seguenti descrivono in dettaglio le richieste di connettori generiche provenienti da Managed Integrations, in cui sono presenti campi comuni a ogni interfaccia richiesta. Dagli esempi, puoi vedere che esistono sia un'intestazione di richiesta che un payload della richiesta. Le intestazioni di richiesta sono comuni a tutte le interfacce operative.

Esempio OAuth 2.0:

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

Esempio di autorizzazione generale:

{
        "header": {
                "auth": { 
                        "secretsManager": {
                                "arn": "string",
                                "versionId": "string"
                        },
                        "type": "GeneralAuthorization"
                }
        },
        "payload":{
                "operationName": "AWS.SendCommand",
                "operationVersion": "1.0",
                "connectorId": "exampleId",
        …
        }
}

Intestazioni di richiesta predefinite

I campi di intestazione predefiniti variano a seconda del tipo di autorizzazione. Il connettore deve gestire sia le intestazioni di richiesta OAuth 2.0 che quelle di autorizzazione generale.

Intestazione predefinita OAuth 2.0:

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

Intestazione predefinita di autorizzazione generale:

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

Richiedi Payload

Oltre alle intestazioni comuni, ogni richiesta avrà un payload. Sebbene questo payload abbia campi unici per ogni tipo di operazione, ogni payload ha una serie di campi predefiniti che saranno sempre presenti.

Intestazioni di risposta predefinite

Ogni operazione risponderà con una risposta ACK alle integrazioni gestite per AWS IoT Device Management che confermerà che il connettore C2C ha ricevuto la richiesta e ha iniziato a elaborarla.

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

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

Campo di intestazione della risposta

Nelle varie interfacce di connettore e schemi API descritti in questo documento è presente un responseMessage campo or. Message Questo è un campo opzionale utilizzato dal connettore C2C Lambda per rispondere con qualsiasi contesto relativo alla richiesta e alla sua esecuzione. Preferibilmente, qualsiasi errore che dia origine a un codice di stato diverso da 200 dovrebbe includere un valore di messaggio che descriva l'errore.

Rispondi alle richieste di funzionamento del connettore C2C con l'API SendConnectorEvent

Managed Integrations for AWS IoT Device Management prevede che il connettore si comporti in modo asincrono per ogni operazione. AWS.SendCommand AWS.DiscoverDevices Ciò significa che la risposta iniziale a queste operazioni «riconosce» semplicemente che il connettore C2C ha ricevuto la richiesta.

Utilizzando l'SendConnectorEventAPI, ci si aspetta che il connettore invii i tipi di eventi indicati nell'elenco seguente relativi AWS.SendCommand alle operazioni AWS.DiscoverDevices e alle operazioni, nonché gli eventi proattivi del dispositivo (come l'accensione e lo spegnimento manuale di una luce).

Esempio di workflow

Se il connettore C2C riceve una DiscoverDevices richiesta, Managed Integrations for AWS IoT Device Management prevede che:

La chiamata SendConnectorEvent API può avvenire ovunque sia possibile accedere alle credenziali Lambda del connettore C2C. Account AWS Il flusso di rilevamento dei dispositivi non ha esito positivo finché le integrazioni gestite per AWS IoT Device Management non ricevono questo evento.

SendConnectorEvent API

Il connettore chiama queste integrazioni gestite per l'API AWS IoT Device Management per inviare eventi ai dispositivi. Sono accettati solo 3 tipi di eventi: