Implemente operações de interface do conector C2C

As integrações gerenciadas AWS IoT Device Management definem quatro operações que você AWS Lambda deve realizar para se qualificar como conector. Seu conector C2C deve implementar cada uma das seguintes operações:

Detalhes da invocação

As integrações gerenciadas AWS IoT Device Management sempre invocam a função Lambda com uma carga útil de string JSON por meio da ação. AWS Lambda invokeFunction As operações de solicitação devem incluir um operationName campo em cada carga útil da solicitação.

Configurações de invocação:

Exemplo de implementação

O Lambda que você implementa para seu conector analisará a carga útil operationName da solicitação e implementará a funcionalidade correspondente para mapear para a nuvem de terceiros:

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

Exemplos de formato de solicitação

Os exemplos a seguir detalham solicitações genéricas de conectores de integrações gerenciadas, nas quais campos comuns para cada interface necessária estão presentes. Nos exemplos, você pode ver que há um cabeçalho de solicitação e uma carga útil de solicitação. Os cabeçalhos de solicitação são comuns em todas as interfaces de operação.

Exemplo de OAuth 2.0:

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

Exemplo de autorização geral:

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

Cabeçalhos de solicitação padrão

Os campos de cabeçalho padrão variam de acordo com o tipo de autorização. Seu conector deve lidar com cabeçalhos de solicitação de autorização geral e OAuth 2.0.

Cabeçalho padrão do OAuth 2.0:

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

Cabeçalho padrão de autorização geral:

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

Solicitar carga

Além dos cabeçalhos comuns, cada solicitação terá uma carga útil. Embora essa carga tenha campos exclusivos para cada tipo de operação, cada carga tem um conjunto de campos padrão que sempre estarão presentes.

Cabeçalhos de resposta padrão

Cada operação responderá com uma ACK das integrações gerenciadas do AWS IoT Device Management, confirmando que seu conector C2C recebeu a solicitação e começou a processá-la.

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

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

Campo de cabeçalho de resposta

Nas várias interfaces de conectores e esquemas de API descritos neste documento, há um Message campo responseMessage ou. Esse é um campo opcional usado para que o conector C2C Lambda responda com qualquer contexto relacionado à solicitação e sua execução. De preferência, qualquer erro que resulte em um código de status diferente 200 deve incluir um valor de mensagem descrevendo o erro.

Responda às solicitações de operação do conector C2C com a API SendConnectorEvent

Integrações gerenciadas AWS IoT Device Management esperam que seu conector se comporte de forma assíncrona em todas as operações. AWS.SendCommand AWS.DiscoverDevices Isso significa que a resposta inicial a essas operações simplesmente “reconhece” que seu conector C2C recebeu a solicitação.

Usando a SendConnectorEvent API, espera-se que seu conector envie os tipos de eventos da lista abaixo para AWS.SendCommand operações AWS.DiscoverDevices e, bem como eventos proativos do dispositivo (como uma luz sendo ligada e desligada manualmente).

Exemplo de fluxo de trabalho

Se seu conector C2C receber uma DiscoverDevices solicitação, a Managed Integrations for AWS IoT Device Management espera que ela:

A chamada de SendConnectorEvent API pode ocorrer em qualquer lugar onde você tenha acesso às suas credenciais Lambda do conector C2C. Conta da AWS O fluxo de descoberta de dispositivos não é bem-sucedido até que as integrações gerenciadas do AWS IoT Device Management recebam esse evento.

SendConnectorEvent API

Seu conector chama essas integrações gerenciadas para a API AWS IoT Device Management para enviar eventos do dispositivo. Somente 3 tipos de eventos são aceitos: