기본 요청 헤더 요청 페이로드 기본 응답 헤더 C2C 커넥터 작업 요청에 응답

C2C 커넥터 인터페이스 작업 구현

용 관리형 통합은 커넥터로 검증하기 위해 처리 AWS Lambda 해야 하는 4가지 작업을 AWS IoT Device Management 정의합니다. C2C 커넥터는 다음 각 작업을 구현해야 합니다.

AWS.ActivateUser - AWS IoT Device Management 서비스용 관리형 통합은이 API를 호출하여 제공된 OAuth2.0 토큰과 연결된 전역적으로 고유한 사용자 식별자를 검색합니다. 이 작업은 선택적으로 계정 연결 프로세스에 대한 추가 요구 사항을 수행하는 데 사용할 수 있습니다.
AWS.DiscoverDevices - AWS IoT Device Management 서비스의 관리형 통합은 사용자의 디바이스를 검색하기 위해이 API를 커넥터에 호출합니다.
AWS.SendCommand - AWS IoT Device Management 서비스의 관리형 통합은 사용자 디바이스에 대한 명령을 보내기 위해이 API를 커넥터에 호출합니다.
AWS.DeactivateUser - AWS IoT Device Management 서비스의 관리형 통합은이 API를 커넥터로 호출하여 권한 부여 서버에서 연결을 해제할 사용자의 액세스 토큰을 비활성화합니다.

용 관리형 통합은 AWS IoT Device Management 작업을 통해 항상 JSON 문자열 페이로드를 사용하여 Lambda 함수를 호출합니다 AWS Lambda invokeFunction. 요청 작업은 모든 요청 페이로드에 operationName 필드를 포함해야 합니다. 자세한 내용은 AWS Lambda API 참조의 간접 호출을 참조하세요.

각 호출 제한 시간은 2초로 설정되며, 호출이 실패하면 5회 재시도됩니다.

커넥터에 대해 구현하는 Lambda는 요청 페이로드operationName에서를 구문 분석하고 해당 기능을 구현하여 타사 클라우드에 매핑합니다.


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

참고

커넥터 개발자는 이전 예제에 나열된 activateUserManager.activateUser(request), deviceDiscoveryManager.listDevices(request)sendCommandManager.sendCommand(request), 및 deactivateUser.deactivateUser 작업을 구현해야 합니다.

다음 예제에서는 모든 필수 인터페이스에 대한 공통 필드가 있는 관리형 통합의 일반 커넥터 요청을 자세히 설명합니다. 예제에서 요청 헤더와 요청 페이로드가 모두 있는 것을 볼 수 있습니다. 요청 헤더는 모든 작업 인터페이스에서 공통적입니다.


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

기본 요청 헤더

기본 헤더 필드는 다음과 같습니다.


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

커넥터에서 호스팅하는 모든 API는 다음 헤더 파라미터를 처리해야 합니다.

기본 헤더 및 필드
필드	필수/선택 사항	설명
`header:auth`	예	커넥터 등록 중에 C2C 커넥터 빌더가 제공하는 권한 부여 정보입니다.
`header:auth:token`	예	타사 클라우드 공급자가 생성하고에 연결된 사용자의 권한 부여 토큰입니다`connectorAssociationID`.
`header:auth:type`	예	필요한 권한 부여 유형입니다.

참고

커넥터에 대한 모든 요청에는 최종 사용자의 액세스 토큰이 연결됩니다. 최종 사용자와 관리형 통합 고객 간의 계정 연결이 이미 발생했다고 가정할 수 있습니다.

요청 페이로드

일반 헤더 외에도 모든 요청에는 페이로드가 있습니다. 이 페이로드에는 모든 작업 유형에 대한 고유한 필드가 있지만 각 페이로드에는 항상 표시되는 기본 필드 세트가 있습니다.

요청 페이로드 필드:

operationName: 지정된 요청의 작업으로, , AWS.ActivateUser, AWS.SendCommand, 값 중 하나와 같습니다AWS.DiscoverDevicesAWS.DeactivateUser.
operationVersion: 모든 작업은 시간이 지남에 따라 진화하고 타사 커넥터에 대한 안정적인 인터페이스 정의를 제공하도록 버전이 지정됩니다. 관리형 통합은 모든 요청의 페이로드에 버전 필드를 전달합니다.
connectorId: 요청이 전송된 커넥터의 ID입니다.

기본 응답 헤더

모든 작업은 C2C 커넥터가 요청을 수신하고 처리를 시작했음을 확인하는 AWS IoT Device Management의 ACK 관리형 통합에 로 응답합니다. 다음은 해당 응답의 일반적인 예입니다.


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

모든 작업 응답에는 다음과 같은 공통 헤더가 있어야 합니다.


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

다음 표에는 기본 응답 헤더가 나열되어 있습니다.

기본 응답 헤더 및 필드
필드	필수/선택 사항	Comment
`header:responseCode`	예	요청의 실행 상태를 나타내는 값의 ENUM입니다.

이 문서에 설명된 다양한 커넥터 인터페이스 및 API 스키마 전체에 responseMessage 또는 Message 필드가 있습니다. 이 필드는 C2C 커넥터 Lambda가 요청 및 실행과 관련된 컨텍스트로 응답하는 데 사용되는 선택적 필드입니다. 가급적이면 이외의 상태 코드를 초래하는 모든 오류에는 오류를 설명하는 메시지 값이 포함되어야 200 합니다.

SendConnectorEvent API를 사용하여 C2C 커넥터 작업 요청에 응답

용 관리형 통합은 모든 AWS.SendCommand 및 AWS.DiscoverDevices 작업에 대해 커넥터가 비동기적으로 작동할 것으로 AWS IoT Device Management 예상합니다. 즉, 이러한 작업에 대한 초기 응답은 단순히 C2C 커넥터가 요청을 수신했음을 “확인”한다는 의미입니다.

SendConnectorEvent API를 사용하면 커넥터가 아래 목록에서 AWS.DiscoverDevices 및 AWS.SendCommand 작업에 대한 이벤트 유형과 사전 예방적 디바이스 이벤트(예: 수동으로 켜고 끄는 등)를 로 전송해야 합니다. 이러한 이벤트 유형 및 사용 사례에 대한 자세한 설명은 AWS.DiscoverDevices 작업 구현, AWS.SendCommand 작업 구현및 단원을 참조하십시오SendConnectorEvent API를 사용하여 디바이스 이벤트 전송.

예를 들어 C2C 커넥터가 DiscoverDevices 요청을 수신하면 AWS IoT Device Management의 관리형 통합은 위에서 정의한 응답 형식과 동기적으로 응답할 것으로 예상합니다. 그런 다음 DEVICE_DISCOVERY 이벤트에 AWS.DiscoverDevices 작업 구현대해에 정의된 요청 구조로 SendConnectorEventAPI를 호출해야 합니다. SendConnectorEvent 온 API 호출은 C2C 커넥터 Lambda AWS 계정 자격 증명에 액세스할 수 있는 모든 곳에서 발생할 수 있습니다. AWS IoT Device Management 검색 흐름이 성공하지 못합니다.

참고

또는 필요한 경우 C2C 커넥터 Lambda 호출 응답 전에 SendConnectorEvent API 호출이 발생할 수 있습니다. 그러나이 흐름은 소프트웨어 개발을 위한 비동기 모델과 모순됩니다.

SendConnectorEvent - 커넥터가 AWS IoT Device Management API에 대한이 관리형 통합을 호출하여 AWS IoT Device Management에 대한 관리형 통합으로 디바이스 이벤트를 전송합니다. 관리형 통합에서 허용되는 이벤트 유형은 3가지뿐입니다.
- "DEVICE_DISCOVERY" -이 이벤트 작업은 특정 액세스 토큰에 대해 타사 클라우드 내에서 검색된 디바이스 목록을 전송하는 데 사용해야 합니다.
- "DEVICE_COMMAND_RESPONSE" -이 이벤트 작업은 명령 실행의 결과로 특정 디바이스 이벤트를 전송하는 데 사용해야 합니다.
- "DEVICE_EVENT" -이 이벤트 작업은 사용자 기반 명령의 직접적인 결과가 아닌 디바이스에서 시작된 모든 이벤트에 사용해야 합니다. 이는 디바이스 상태 변경 또는 알림을 사전에 보고하는 일반적인 이벤트 유형 역할을 할 수 있습니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

계정 연결 워크플로

AWS.ActivateUser 작업 구현