기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 디바이스 연결 상태 쿼리
AWS IoT 플릿 인덱싱은 개별 디바이스 연결 쿼리를 지원하므로 특정 디바이스의 연결 상태 및 관련 메타데이터를 효율적으로 검색할 수 있습니다. 이 기능은 기존 플릿 전체 인덱싱 및 쿼리 기능을 보완합니다.
## 작동 방식
디바이스 연결 쿼리 지원은 최적화된 단일 디바이스 연결 상태 검색에 사용할 수 있습니다. 이 API는 최신 디바이스별 연결 정보에 대해 지연 시간이 짧고 처리량이 많은 액세스를 제공합니다. 연결 인덱싱을 활성화하면 표준 쿼리로 요금이 청구되는 이 쿼리 API에 액세스할 수 있습니다. 자세한 내용은 [AWS IoT Device Management 요금](https://aws.amazon.com/iot-device-management/pricing/#:~:text=Search%20queries%20(per%2010%2C000%20queries))을 참조하세요.
## 특성
디바이스 연결 쿼리 지원을 통해 다음을 수행할 수 있습니다.
1. `thingName`을 사용하여 지정된 디바이스에 대한 현재 연결 상태(연결 또는 연결 해제됨)를 쿼리합니다.
1. 다음을 포함한 추가 연결 메타데이터를 검색합니다.
1. 연결 해제 이유
1. 가장 최근 연결 또는 연결 해제 이벤트의 타임 스탬프입니다.
1. 연결 유지 기간을 포함한 세션 정보
1. IP 주소, 포트 및 VPC 엔드포인트 ID를 포함한 소켓 수준 세션 정보입니다. 이 정보는 다음 조건이 충족되는 경우에만 사용할 수 있습니다.
1. 플릿 인덱싱 구성 설정에서이 옵션을 활성화합니다.
1. API를 호출할 때 IAM 정책에 해당 권한이 있습니다.
**참고**
플릿 인덱싱은 [레지스트리](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html)에 등록된 사물의 `thingName`과 연결 `clientId`가 동일한 디바이스의 연결 상태를 인덱싱합니다.
## 이점
1. **짧은 지연 시간:** 최신 디바이스 연결 상태를 반영하고 짧은 지연 시간을 제공하여 IoT Core의 연결 상태 변경을 반영합니다. IoT Core는 디바이스로부터 연결 해제 요청을 받는 즉시 또는 연결 해제 요청을 보내지 않고 디바이스가 연결 해제되는 경우, 디바이스가 연결 해제된 것으로 판단합니다. IoT 코어는 클라이언트가 연결 해제되었다고 확인되기 전에 구성된 연결 유지 시간의 1.5배를 기다립니다. 연결 상태 API는 일반적으로 IoT Core가 디바이스의 연결 상태를 확인한 후 1초 이내에 이러한 변경 사항을 반영합니다.
1. **높은 처리량:** 기본적으로 350개의 초당 트랜잭션(TPS)을 지원하며 요청 시 더 높게 조정할 수 있습니다.
1. **데이터 보존: **플릿 인덱싱(FI) ConnectivityIndexing 모드가 활성화되어 있고 사물이 삭제되지 않은 경우, 이벤트 데이터를 무기한 저장합니다. 연결 인덱싱을 비활성화하면 레코드가 보존되지 않습니다.
**참고**
이 API를 시작하기 전에 연결 상태 인덱싱이 활성화된 경우, 플릿 인덱싱은 API 시작 후에 발생한 연결 상태 변경을 추적하기 시작하고 이러한 변경 사항에 따라 업데이트된 상태를 반영합니다.
## 사전 조건
디바이스 연결 쿼리 지원을 사용하려면 다음을 수행하세요.
1. [AWS 계정 설정](https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html)
1. 원하는 리전 AWS IoT Core 의에 디바이스 온보딩 및 등록
1. 연결 [인덱싱을 사용하여 플릿 인덱싱을 활성화합니다](https://docs.aws.amazon.com/iot/latest/developerguide/managing-index.html). 선택 사항: `includeSocketInformation` 옵션을 활성화하여 소켓 수준 정보를 수신하도록 옵트인합니다.
**참고**
연결 인덱싱이 이미 활성화된 경우 추가 설정이 필요하지 않습니다.
자세한 설정 지침은 [AWS IoT 개발자 안내서](https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html)를 참조하세요.
## 예제
**CLI 명령:**
```
aws iot get-thing-connectivity-data --include-socket-information --thing-name myThingName
```
**응답**:
```
{
"thingName": "myThingName",
"connected": true,
"timestamp": "2024-12-19T10:00:00.000000-08:00",
"disconnectReason": "NONE",
"sourceIp": "192.0.2.1",
"sourcePort": 52123,
"targetIp": "198.51.100.1",
"targetPort": 8883,
"vpcEndpointId": "vpce-1234567890abcdef0",
"keepAliveDuration": 60,
"cleanSession": true,
"clientId": "myThingName"
}
```
**API 파라미터**
+ `thingName`: AWS IoT 레지스트리에 등록된 디바이스의 이름입니다. 이는 AWS IoT Core에 연결하는 데 `clientId` 사용되는와 일치해야 합니다.
+ `includeSocketInformation`: `includeSocketInformation` 파라미터는 소켓 수준 네트워크 정보가 API 응답에 포함되는지 여부를 제어합니다. true로 설정하면 응답에 필드가 포함됩니다`sourceIp, sourcePort, targetIp, targetPort, vpcEndpointId`. `includeSocketInformation`를 지정하지 않거나 false로 설정하면 이러한 소켓 필드가 응답에서 제외됩니다. 특정 IAM 사용자가 소켓 정보에 액세스하지 못하도록 제한하려면 `includeSocketInformation` 조건 키를 false로 설정하여 IAM 정책에서 이를 지정해야 합니다.
**응답 필드**
+ `thingName`: AWS IoT 레지스트리에 등록된 디바이스의 이름입니다. 이는 AWS IoT Core에 연결하는 데 `clientId` 사용되는와 일치해야 합니다.
+ `connected`: 이 디바이스가 현재 연결되어 있음을 나타내는 부울 값 true입니다.
+ `disconnectReason`: 연결 해제 이유입니다. `NONE` 연결된 디바이스와 연결되지 않은 디바이스`UNKNOWN`에 사용됩니다. 연결이 끊긴 디바이스의 경우 인증/권한 부여 문제 또는 네트워크 문제로 인해 연결이 끊긴 클라이언트가 시작되었는지, 서버가 시작되었는지를 나타냅니다. 연결 해제 사유 코드는 [LifeCycleEvents](https://docs.aws.amazon.com//iot/latest/developerguide/life-cycle-events.html)를 참조하세요.
+ `timestamp`: 디바이스의 가장 최근 연결 또는 연결 해제 이벤트를 나타내는 타임스탬프입니다.
+ `clientId`: MQTT 클라이언트의 clientId입니다.
+ `keepAliveDuration`: 클라이언트가 연결을 설정할 때 지정한 초 단위 연결 유지 간격입니다. 이는 클라이언트가 연결을 유지하기 위해 연결 유지 메시지를 보내는 빈도를 결정합니다.
+ `cleanSession`: 클라이언트가 클린 세션을 사용하고 있는지 여부를 나타냅니다.
+ `sessionExpiry`: 클라이언트가 연결을 설정할 때 지정한 영구 세션 만료 구성입니다. 이는 클라이언트 연결 해제 후 세션이 활성 상태로 유지되는 기간을 결정합니다.
+ `sourceIp`: 연결을 시작한 클라이언트의 IP 주소입니다. `includeSocketInformation`이 true로 설정되어 있고 사용자에게이 정보를 검색할 권한이 있는 경우에만 반환됩니다.
+ `sourcePort`: 클라이언트가 연결에 사용하는 포트 번호입니다. `includeSocketInformation`이 true로 설정되어 있고 사용자에게이 정보를 검색할 권한이 있는 경우에만 반환됩니다.
+ `targetIp`: 연결 요청이 이루어진 IP 주소입니다. `includeSocketInformation`이 true로 설정되어 있고 사용자에게이 정보를 검색할 권한이 있는 경우에만 반환됩니다.
+ `targetPort`: 클라이언트가 연결된 AWS IoT Core 엔드포인트의 포트 번호입니다. `includeSocketInformation`이 true로 설정되어 있고 사용자에게이 정보를 검색할 권한이 있는 경우에만 반환됩니다.
+ `vpcEndpointId`: 해당하는 경우 클라이언트가 연결한 VPC 엔드포인트의 ID입니다. `includeSocketInformation`이 true로 설정되어 있고 사용자에게이 정보를 검색할 권한이 있는 경우에만 반환됩니다.
**필수 권한**
GetThingConnectivityData API를 사용하려면 다음 IAM 권한이 필요합니다.
`iot:GetThingConnectivityData`
리소스 기반 정책을 사용하여이 권한의 범위를 특정 사물로 지정할 수 있습니다. `iot:IncludeSocketInformation` 조건을 사용하여 소켓 정보에 대한 세분화된 액세스 제어를 구현합니다. 아래 정책 예제는 소켓 정보에 대한 사용자 액세스를 거부하는 시나리오를 보여줍니다. 이 예제는 GetThingConnectivityData 작업에 대한 액세스 권한을 부여하는 유일한 정책인 경우에 작동합니다.
**권한 부여 정책 예제**
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [ "iot:GetThingConnectivityData" ],
"Resource": [ "arn:aws:iot:us-east-1:123456789012:thing/*"],
"Condition": {
"Bool": {
"iot:IncludeSocketInformation": "false"
}
}
}]
}
```