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:

1. AWS.ActivateUser- Integrações gerenciadas para o AWS IoT Device Management serviço chamam essa API para recuperar um identificador de usuário globalmente exclusivo associado ao token OAuth2 .0 fornecido. Opcionalmente, essa operação pode ser usada para executar quaisquer requisitos adicionais para o processo de vinculação de contas.

2. AWS.DiscoverDevices- integrações gerenciadas para o serviço AWS IoT Device Management chamam essa API ao seu conector para descobrir os dispositivos do usuário

3. AWS.SendCommand- integrações gerenciadas para o serviço AWS IoT Device Management chamam essa API ao seu conector para enviar comandos para os dispositivos do usuário

4. AWS.DeactivateUser- integrações gerenciadas para o serviço AWS IoT Device Management chamam essa API para seu conector para desativar o token de acesso do usuário para desvincular seu servidor de autorizaçã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. Para saber mais, consulte Invoke in AWS Lambda API Reference.

Cada tempo limite de invocação é definido para dois segundos e, se a invocação falhar, ela será repetida cinco vezes.

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

nota

O desenvolvedor do conector deve implementar as deactivateUser.deactivateUser operações activateUserManager.activateUser(request) deviceDiscoveryManager.listDevices(request)sendCommandManager.sendCommand(request),, e listadas no exemplo anterior.

O exemplo a seguir detalha uma solicitação genérica de conector de integrações gerenciadas, na qual campos comuns para cada interface necessária estão presentes. No exemplo, 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.

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

Cabeçalhos de solicitação padrão

Os campos de cabeçalho padrão são os seguintes.

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

Qualquer API hospedada por um conector deve processar os seguintes parâmetros de cabeçalho:

Cabeçalhos e campos padrão

Campo	Obrigatório/opcional	Descrição
header:auth	Sim	Informações de autorização fornecidas pelo construtor do conector C2C durante o registro do conector.
header:auth:token	Sim	Token de autorização do usuário gerado pelo provedor de nuvem terceirizado e vinculado connectorAssociationID a.
header:auth:type	Sim	O tipo de autorização necessária.

nota

Todas as solicitações ao seu conector terão o token de acesso do usuário final anexado. Você pode supor que a vinculação de contas entre o usuário final e o cliente de integrações gerenciadas já tenha ocorrido.

Carga da solicitação

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.

Campos de carga útil da solicitação:

• operationName: a operação de uma determinada solicitação, igual a um dos seguintes valores:AWS.ActivateUser,AWS.SendCommand,AWS.DiscoverDevices,AWS.DeactivateUser.

• operationVersion: Cada operação é versionada para permitir sua evolução ao longo do tempo e fornecer uma definição de interface estável para conectores de terceiros. As integrações gerenciadas passam um campo de versão na carga útil de todas as solicitações.

• connectorId: o ID do conector para o qual a solicitação foi enviada.

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. A seguir está um exemplo genérico dessa resposta:

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

Cada resposta de operação deve ter o seguinte cabeçalho comum:

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

A tabela a seguir lista o cabeçalho de resposta padrão:

Cabeçalho e campo de resposta padrão

Campo	Obrigatório/opcional	Comentário
header:responseCode	Sim	ENUM de valores que indicam o status de execução da solicitação.

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 for AWS.DiscoverDevices and AWS.SendCommand operations, bem como eventos proativos do dispositivo (como uma luz sendo ligada e desligada manualmente). Para ler uma explicação detalhada desses tipos de eventos e seus casos de usoImplemente a AWS. DiscoverDevices operação, consulteImplemente a AWS. SendCommand operação, Envie eventos do dispositivo com a SendConnectorEvent API e.

Por exemplo, se seu conector C2C receber uma DiscoverDevices solicitação, as integrações gerenciadas do AWS IoT Device Management esperam que ele responda de forma síncrona com o formato de resposta definido acima. Em seguida, você deve invocar a SendConnectorEvent API com a estrutura de solicitação definida emImplemente a AWS. DiscoverDevices operação, para um evento DEVICE_DISCOVERY. A chamada SendConnectorEvent na API pode ocorrer em qualquer lugar em que 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.

nota

Como alternativa, a chamada da SendConnectorEvent API pode ocorrer antes da resposta de invocação Lambda do conector C2C, se necessário. No entanto, esse fluxo contradiz o modelo assíncrono para desenvolvimento de software.

• SendConnectorEvent- Seu conector chama essas integrações gerenciadas para a API AWS IoT Device Management para enviar eventos de dispositivos para integrações gerenciadas para o AWS IoT Device Management. Somente 3 tipos de eventos aceitos pelas integrações gerenciadas:

  • “DEVICE_DISCOVERY" — Essa operação de evento deve ser usada para enviar uma lista de dispositivos descobertos na nuvem de terceiros para um token de acesso específico.

  • “DEVICE_COMMAND_RESPONSE" — Essa operação de evento deve ser usada para enviar um evento de dispositivo específico como resultado da execução do comando.

  • “DEVICE_EVENT" — Esta operação de evento deve ser usada para qualquer evento originado no dispositivo que não seja o resultado direto de um comando baseado no usuário. Isso pode servir como um tipo de evento geral para relatar proativamente as alterações ou notificações do estado do dispositivo.