As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# 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 AWS IoT Device Management serviços chamam essa API para recuperar um identificador de usuário globalmente exclusivo. Para o OAuth 2.0, isso está associado ao token OAuth 2.0 fornecido. Opcionalmente, essa operação pode ser usada para executar quaisquer requisitos adicionais para o processo de vinculação de contas.
1. `AWS.DiscoverDevices`- Integrações gerenciadas para AWS IoT Device Management serviços chamam essa API ao seu conector para descobrir os dispositivos do usuário
1. `AWS.SendCommand`- Integrações gerenciadas para AWS IoT Device Management serviços chamam essa API ao seu conector para enviar comandos para os dispositivos do usuário
1. `AWS.DeactivateUser`- As integrações gerenciadas para AWS IoT Device Management serviços chamam essa API ao seu conector para desativar o token de acesso do usuário para desvincular seu servidor de autorização.
## 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:**
+ **Tempo limite:** 2 segundos por invocação
+ **Repetições:** 5 tentativas em caso de falha
## 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);
};
}
```
**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.
## 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"
}
}
}
```
**parâmetros de cabeçalho**
| | | |
| --- |--- |--- |
| Campo | Required/Optional | Descrição |
| `header:auth` | Sim | Informações de autorização fornecidas pelo construtor do conector C2C durante o registro do conector. |
| `header:auth:token` | Condicional | Token de autorização do usuário gerado pelo provedor de nuvem terceirizado e vinculado `connectorAssociationID` a. Obrigatório para o OAuth 2.0, não presente para a Autorização Geral. |
| `header:auth:secretsManager` | Condicional | AWS Secrets Manager ARN e ID da versão contendo credenciais de autorização. Exigido para autorização geral, não presente para o OAuth 2.0. |
| `header:auth:type` | Sim | O tipo de autorização: `OAuth2.0` ou`GeneralAuthorization`. |
**nota**
Todas as solicitações ao seu conector incluirão informações de autorização. Para o OAuth 2.0, isso inclui o token de acesso do usuário final. Para autorização geral, isso inclui o AWS Secrets Manager ARN e o ID da versão. Você pode presumir que a autorização apropriada já foi estabelecida.
## 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.
**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 transmitem 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.
**Example Exemplo de resposta genérica**
```
{
"header":{
"responseCode": 200
},
"payload":{
"responseMessage": “Example response!”
}
}
```
**Example formato do cabeçalho de resposta**
```
{
"header": {
"responseCode": Integer
}
}
```
**Cabeçalho e campo de resposta padrão**
| | | |
| --- |--- |--- |
| Campo | Required/Optional | 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 `AWS.SendCommand` operações `AWS.DiscoverDevices` e, bem como eventos proativos do dispositivo (como uma luz sendo ligada e desligada manualmente).
Se seu conector C2C receber uma `DiscoverDevices` solicitação, a Managed Integrations for AWS IoT Device Management espera que ela:
+ Responda de forma síncrona com o formato de resposta definido acima
+ Invoque a `SendConnectorEvent` API com um evento DEVICE\_DISCOVERY
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.
**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.
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:
+ **“DEVICE\_DISCOVERY”** - Usado para enviar uma lista de dispositivos descobertos na nuvem de terceiros para um token de acesso específico
+ **“DEVICE\_COMMAND\_RESPONSE”** - Usado para enviar um evento de dispositivo específico como resultado da execução do comando
+ **“DEVICE\_EVENT”** - Usado para qualquer evento originado do 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.