Implementa le 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:

1. AWS.ActivateUser- Le integrazioni gestite per il AWS IoT Device Management servizio richiamano questa API per recuperare un identificatore utente univoco a livello globale associato al token .0 fornito. OAuth2 Questa operazione può essere utilizzata opzionalmente per eseguire eventuali requisiti aggiuntivi per il processo di collegamento dell'account.

2. AWS.DiscoverDevices- le integrazioni gestite per il servizio AWS IoT Device Management richiamano questa API al connettore per scoprire i dispositivi dell'utente

3. AWS.SendCommand- le integrazioni gestite per il servizio AWS IoT Device Management richiamano questa API al connettore per l'invio di comandi per i dispositivi dell'utente

4. AWS.DeactivateUser- le integrazioni gestite per il servizio AWS IoT Device Management richiamano questa API al connettore per disattivare il token di accesso dell'utente da decollegare nel server di autorizzazione.

Le integrazioni gestite per AWS IoT Device Management sempre richiamano 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. Per ulteriori informazioni, consulta Invoke in AWS Lambda API Reference.

Ogni timeout di chiamata è impostato su due secondi e, se la chiamata fallisce, verrà ritentata cinque volte.

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

Nota

Lo sviluppatore del connettore deve implementare le deactivateUser.deactivateUser operazioniactivateUserManager.activateUser(request), deviceDiscoveryManager.listDevices(request)sendCommandManager.sendCommand(request), e elencate nell'esempio precedente.

L'esempio seguente descrive in dettaglio una richiesta di connettore generica proveniente da integrazioni gestite, in cui sono presenti campi comuni a tutte le interfacce richieste. Dall'esempio, puoi vedere che sono presenti sia un'intestazione di richiesta che un payload della richiesta. Le intestazioni di richiesta sono comuni a tutte le interfacce operative.

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

Intestazioni di richiesta predefinite

I campi di intestazione predefiniti sono i seguenti.

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

Qualsiasi API ospitata da un connettore deve elaborare i seguenti parametri di intestazione:

Intestazioni e campi predefiniti

Campo	Obbligatorio/facoltativo	Descrizione
header:auth	Sì	Informazioni di autorizzazione fornite dal costruttore di connettori C2C durante la registrazione dei connettori.
header:auth:token	Sì	Token di autorizzazione dell'utente generato dal provider di servizi cloud di terze parti e collegato a. connectorAssociationID
header:auth:type	Sì	Il tipo di autorizzazione necessaria.

Nota

A tutte le richieste al connettore verrà allegato il token di accesso dell'utente finale. Si può presumere che il collegamento dell'account tra l'utente finale e il cliente delle integrazioni gestite sia già avvenuto.

Payload della richiesta

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.

Richiedi i campi del payload:

• operationName: L'operazione di una determinata richiesta, pari a uno dei seguenti valori:AWS.ActivateUser,, AWS.SendCommandAWS.DiscoverDevices,AWS.DeactivateUser.

• operationVersion: Ogni operazione è suddivisa in versioni per consentirne l'evoluzione nel tempo e fornire una definizione stabile dell'interfaccia per i connettori di terze parti. Le integrazioni gestite inseriscono un campo di versione nel payload di tutte le richieste.

• connectorId: L'ID del connettore a cui è stata inviata la richiesta.

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. Di seguito è riportato un esempio generico di tale risposta:

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

Ogni risposta operativa deve avere la seguente intestazione comune:

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

La tabella seguente elenca l'intestazione di risposta predefinita:

Intestazione e campo di risposta predefiniti

Campo	Obbligatorio/facoltativo	Commento
header:responseCode	Sì	ENUM di valori che indicano lo stato di esecuzione della richiesta.

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

Le integrazioni gestite AWS IoT Device Management prevedono 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, il connettore dovrebbe inviare i tipi di eventi dall'elenco seguente a for AWS.DiscoverDevices and AWS.SendCommand operations, oltre a eventi proattivi del dispositivo (come l'accensione e lo spegnimento manuale di una luce). Per una spiegazione dettagliata di questi tipi di eventi e dei relativi casi d'uso, consulta Implementa AWS. DiscoverDevices operazioneImplementa AWS. SendCommand operazione, eInvia gli eventi del dispositivo con l'API SendConnectorEvent.

Ad esempio, se il connettore C2C riceve una DiscoverDevices richiesta, le integrazioni gestite per AWS IoT Device Management si aspettano che risponda in modo sincrono con il formato di risposta definito sopra. Quindi, devi richiamare l'SendConnectorEventAPI con la struttura della richiesta definita in, per un evento DEVICE_DISCOVERY. Implementa AWS. DiscoverDevices operazione La chiamata SendConnectorEvent on 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.

Nota

In alternativa, la chiamata SendConnectorEvent API può avvenire prima della risposta alla chiamata Lambda del connettore C2C, se necessario. Tuttavia, questo flusso contraddice il modello asincrono per lo sviluppo del software.

• SendConnectorEvent- Il connettore chiama questa API managed integrations for AWS IoT Device Management per inviare eventi del dispositivo a integrazioni gestite per AWS IoT Device Management. Solo 3 tipi di eventi accettati dalle integrazioni gestite:

  • "DEVICE_DISCOVERY" — Questa operazione relativa all'evento deve essere utilizzata per inviare un elenco di dispositivi rilevati all'interno del cloud di terze parti per un token di accesso specifico.

  • «DEVICE_COMMAND_RESPONSE" — Questa operazione evento deve essere utilizzata per inviare un evento specifico del dispositivo come risultato dell'esecuzione del comando.

  • «DEVICE_EVENT" — Questa operazione evento deve essere utilizzata per qualsiasi evento originato dal dispositivo che non sia il risultato diretto di un comando basato sull'utente. Questo può servire come tipo di evento generale per segnalare in modo proattivo le modifiche o le notifiche dello stato del dispositivo.