기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# C2C 커넥터 인터페이스 작업 구현
용 관리형 통합은 커넥터로 검증하기 위해 처리 AWS Lambda 해야 하는 4가지 작업을 AWS IoT Device Management 정의합니다. C2C 커넥터는 다음 각 작업을 구현해야 합니다.
1. `AWS.ActivateUser` - Managed Integrations for AWS IoT Device Management service는이 API를 호출하여 전역적으로 고유한 사용자 식별자를 검색합니다. OAuth 2.0의 경우 제공된 OAuth 2.0 토큰과 연결됩니다. 이 작업은 선택적으로 계정 연결 프로세스에 대한 추가 요구 사항을 수행하는 데 사용할 수 있습니다.
1. `AWS.DiscoverDevices` - Managed Integrations for AWS IoT Device Management service는 사용자의 디바이스를 검색하기 위해이 API를 커넥터로 호출합니다.
1. `AWS.SendCommand` - AWS IoT Device Management 서비스용 관리형 통합은 사용자 디바이스에 대한 명령을 보내기 위해이 API를 커넥터로 호출합니다.
1. `AWS.DeactivateUser` - Managed Integrations for AWS IoT Device Management service는 인증 서버에서 연결을 해제하기 위해 사용자의 액세스 토큰을 비활성화하기 위해이 API를 커넥터로 호출합니다.
## 호출 세부 정보
용 관리형 통합은 AWS IoT Device Management 작업을 통해 항상 JSON 문자열 페이로드를 사용하여 Lambda 함수를 호출합니다 AWS Lambda `invokeFunction`. 요청 작업은 모든 요청 페이로드에 `operationName` 필드를 포함해야 합니다.
**호출 설정:**
+ **제한 시간:** 호출당 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` 작업을 구현해야 합니다.
## 요청 형식 예제
다음 예제에서는 모든 필수 인터페이스에 대한 공통 필드가 있는 Managed Integrations의 일반 커넥터 요청을 자세히 설명합니다. 예제에서 요청 헤더와 요청 페이로드가 모두 있는 것을 볼 수 있습니다. 요청 헤더는 모든 작업 인터페이스에서 일반적입니다.
**OAuth 2.0 예제:**
```
{
"header": {
"auth": {
"token": "ashriu32yr97feqy7afsaf",
"type": "OAuth2.0"
}
},
"payload":{
"operationName": "AWS.SendCommand",
"operationVersion": "1.0",
"connectorId": "exampleId",
…
}
}
```
**일반 권한 부여 예제:**
```
{
"header": {
"auth": {
"secretsManager": {
"arn": "string",
"versionId": "string"
},
"type": "GeneralAuthorization"
}
},
"payload":{
"operationName": "AWS.SendCommand",
"operationVersion": "1.0",
"connectorId": "exampleId",
…
}
}
```
## 기본 요청 헤더
기본 헤더 필드는 권한 부여 유형에 따라 다릅니다. 커넥터는 OAuth 2.0 및 일반 승인 요청 헤더를 모두 처리해야 합니다.
**OAuth 2.0 기본 헤더:**
```
{
"header": {
"auth": {
"token": string, // End user's Access Token
"type": "OAuth2.0"
}
}
}
```
**일반 권한 부여 기본 헤더:**
```
{
"header": {
"auth": {
"secretsManager": {
"arn": "string",
"versionId": "string"
},
"type": "GeneralAuthorization"
}
}
}
```
**헤더 파라미터**
| | | |
| --- |--- |--- |
| 필드 | 필수/선택 사항 | 설명 |
| `header:auth` | 예 | 커넥터 등록 중에 C2C 커넥터 빌더가 제공하는 권한 부여 정보입니다. |
| `header:auth:token` | 조건부 | 타사 클라우드 공급자가 생성하고에 연결된 사용자의 권한 부여 토큰입니다`connectorAssociationID`. OAuth 2.0에는 필수이며 일반 권한 부여에는 없습니다. |
| `header:auth:secretsManager` | 조건부 | AWS Secrets Manager 권한 부여 자격 증명이 포함된 ARN 및 버전 ID입니다. 일반 승인에 필요하며 OAuth 2.0에는 없습니다. |
| `header:auth:type` | 예 | 권한 부여 유형: `OAuth2.0` 또는 `GeneralAuthorization`. |
**참고**
커넥터에 대한 모든 요청에는 권한 부여 정보가 포함됩니다. OAuth 2.0의 경우 여기에는 최종 사용자의 액세스 토큰이 포함됩니다. 일반 권한 부여의 경우 여기에는 AWS Secrets Manager ARN 및 버전 ID가 포함됩니다. 적절한 권한 부여가 이미 설정되었다고 가정할 수 있습니다.
## 페이로드 요청
일반 헤더 외에도 모든 요청에는 페이로드가 있습니다. 이 페이로드에는 모든 작업 유형에 대한 고유한 필드가 있지만 각 페이로드에는 항상 존재하는 기본 필드 세트가 있습니다.
**요청 페이로드 필드:**
+ `operationName`: , , `AWS.ActivateUser`, 값 중 하나와 동일한 지정된 요청의 작업`AWS.SendCommand``AWS.DiscoverDevices`입니다`AWS.DeactivateUser`.
+ `operationVersion`: 모든 작업은 시간이 지남에 따라 진화하고 타사 커넥터에 안정적인 인터페이스 정의를 제공하도록 버전이 지정됩니다. 관리형 통합은 모든 요청의 페이로드에 버전 필드를 전달합니다.
+ `connectorId`: 요청이 전송된 커넥터의 ID입니다.
## 기본 응답 헤더
모든 작업은 C2C 커넥터가 요청을 수신하고 처리를 시작했음을 확인하는 AWS IoT Device Management의 `ACK` 관리형 통합에 로 응답합니다.
**Example 일반 응답 예제**
```
{
"header":{
"responseCode": 200
},
"payload":{
"responseMessage": “Example response!”
}
}
```
**Example 응답 헤더 형식**
```
{
"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` 작업에 대해 아래 목록에서 이벤트 유형과 사전 예방적 디바이스 이벤트(예: 수동으로 켜고 끄는 등)를 전송해야 합니다.
C2C 커넥터가 `DiscoverDevices` 요청을 수신하면 용 관리형 통합은 다음을 AWS IoT Device Management 기대합니다.
+ 위에 정의된 응답 형식과 동기식으로 응답
+ DEVICE\_DISCOVERY 이벤트로 `SendConnectorEvent` API 호출
`SendConnectorEvent` API 호출은 C2C 커넥터 Lambda AWS 계정 자격 증명에 액세스할 수 있는 모든 곳에서 발생할 수 있습니다. AWS IoT Device Management 검색 흐름이 성공하지 못합니다.
**참고**
또는 필요한 경우 C2C 커넥터 Lambda 호출 응답 전에 `SendConnectorEvent` API 호출이 발생할 수 있습니다. 그러나이 흐름은 소프트웨어 개발을 위한 비동기 모델과 모순됩니다.
커넥터는 AWS IoT Device Management API에 대해이 관리형 통합을 호출하여 디바이스 이벤트를 전송합니다. 3가지 유형의 이벤트만 허용됩니다.
+ **"DEVICE\_DISCOVERY"** - 특정 액세스 토큰에 대해 타사 클라우드 내에서 검색된 디바이스 목록을 전송하는 데 사용됩니다.
+ **"DEVICE\_COMMAND\_RESPONSE"** - 명령 실행의 결과로 특정 디바이스 이벤트를 전송하는 데 사용됩니다.
+ **"DEVICE\_EVENT"** - 사용자 기반 명령의 직접적인 결과가 아닌 디바이스에서 시작된 모든 이벤트에 사용됩니다. 이는 디바이스 상태 변경 또는 알림을 사전에 보고하는 일반적인 이벤트 유형으로 사용할 수 있습니다.