기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 사물 인덱싱 관리 모든 사물에 대해 생성된 인덱스는 `AWS_Things`입니다. [AWS IoT 레지스트리](thing-registry.md) 데이터, [AWS IoT 디바이스 섀도우 ](iot-device-shadows.md)데이터, [AWS IoT 연결](life-cycle-events.md) 데이터 및 [AWS IoT Device Defender](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/what-is-device-defender.html) 위반 데이터와 같은 데이터 소스에서 인덱싱할 대상을 제어할 수 있습니다. **Topics** + [사물 인덱싱 활성화](#enable-index) + [사물 인덱스 설명](#describe-index) + [사물 인덱스에 대한 쿼리](#search-index) + [규제 및 제한](#index-limitations) + [권한 부여](#query-auth) ## 사물 인덱싱 활성화 [update-indexing-configuration](https://docs.aws.amazon.com/cli/latest/reference/iot/update-indexing-configuration.html) CLI 명령 또는 [UpdateIndexingConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateIndexingConfiguration.html) API 작업을 사용하여 `AWS_Things` 인덱스를 생성하고 해당 구성을 제어합니다. `--thing-indexing-configuration`(`thingIndexingConfiguration`) 파라미터를 사용하여 인덱싱할 데이터 종류(예: 레지스트리, 섀도우, 디바이스 연결 데이터 및 Device Defender 위반 데이터)를 제어합니다. `--thing-indexing-configuration` 파라미터는 다음 구조의 문자열을 사용합니다. ``` { "thingIndexingMode": "OFF"|"REGISTRY"|"REGISTRY_AND_SHADOW", "thingConnectivityIndexingMode": "OFF"|"STATUS", "deviceDefenderIndexingMode": "OFF"|"VIOLATIONS", "namedShadowIndexingMode": "OFF"|"ON", "managedFields": [ { "name": "string", "type": "Number"|"String"|"Boolean" }, ... ], "customFields": [ { "name": "string", "type": "Number"|"String"|"Boolean" }, ... ], "filter": { "namedShadowNames": [ "string" ], "geoLocations": [ { "name": "String", "order": "LonLat|LatLon" } ] } } ``` ### 사물 인덱싱 모드 인덱싱 구성에서 디바이스를 인덱싱하고 검색하려는 데이터 소스에 따라 다양한 사물 인덱싱 모드를 지정할 수 있습니다. + `thingIndexingMode`: 레지스트리 또는 섀도가 인덱싱되는지 여부를 제어합니다. `thingIndexingMode` 이 `OFF`로 설정되면 사물 인덱싱이 비활성화됩니다. + `thingConnectivityIndexingMode`: 사물 연결 데이터가 인덱싱되는지를 지정합니다. + `deviceDefenderIndexingMode`: Device Defender 위반 데이터가 인덱싱되는지 여부를 지정합니다. + `namedShadowIndexingMode`: 명명된 섀도 데이터가 인덱싱되는지 여부를 지정합니다. 플릿 인덱싱 구성에 추가할 명명된 섀도우를 선택하려면 `namedShadowIndexingMode`를 `ON`으로 설정하고 [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html)에서 명명된 섀도우 이름을 지정합니다. 아래 표에는 각 인덱싱 모드의 유효한 값과 각 값에 대해 인덱싱된 데이터 소스가 나와 있습니다. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/iot/latest/developerguide/managing-index.html) ### 관리형 필드 및 사용자 정의 필드 **관리형 필드** 관리형 필드에는 사물, 사물 그룹, 디바이스 섀도우, 디바이스 연결 및 Device Defender 위반과 관련된 데이터가 포함됩니다.는 관리형 필드의 데이터 유형을 AWS IoT 정의합니다. AWS IoT 사물을 생성할 때 각 관리형 필드의 값을 지정합니다. 예를 들어, 사물 이름, 사물 그룹 및 사물 설명은 모두 관리형 필드입니다. 플릿 인덱싱은 지정한 인덱싱 모드를 기반으로 관리형 필드를 인덱싱합니다. 관리형 필드는 `customFields`에서 변경하거나 표시할 수 없습니다. **사용자 지정 필드** 속성, 디바이스 섀도우 데이터 및 Device Defender 위반 데이터를 인덱싱할 사용자 지정 필드를 만들어 집계할 수 있습니다. `customFields` 속성은 필드 이름과 데이터 형식 페어의 목록입니다. 데이터 유형에 따라 집계 쿼리를 수행할 수 있습니다. 선택한 인덱싱 모드는 `customFields`에서 지정할 수 있는 필드에 영향을 줍니다. 예를 들어, `REGISTRY` 인덱싱 모드를 지정하면 사물 섀도우에서 사용자 지정 필드를 지정할 수 없습니다. [update-indexing-configuration](https://docs.aws.amazon.com/cli/latest/reference/iot/update-indexing-configuration.html) CLI 명령을 사용하여 사용자 정의 필드를 생성하거나 업데이트할 수 있습니다([인덱싱 구성 예 업데이트](#update-index-examples)의 예제 명령 참조). 자세한 내용은 [사용자 정의 필드](managing-fleet-index.md#custom-field)를 참조하세요. ### 인덱싱 필터 인덱싱 필터는 명명된 섀도 및 지리적 위치 데이터에 대한 추가 선택을 제공합니다. **`namedShadowNames`** 플릿 인덱싱 구성에 추가할 명명된 섀도를 선택하려면 `namedShadowIndexingMode`를 `ON`으로 설정하고 `namedShadowNames`에서 명명된 섀도 이름을 지정합니다. **예제** ``` "filter": { "namedShadowNames": [ "namedShadow1", "namedShadow2" ] } ``` `geoLocations` 플릿 인덱싱 구성에 지리적 위치 데이터를 추가하려면: + 지리적 위치 데이터가 클래식(이름 없음) 섀도에 저장되는 경우 `thingIndexingMode`를 REGISTRY\$1AND\$1SHADOW로 설정하고 `geoLocations` 필터에서 지리적 위치 데이터를 지정합니다. 아래 예제 필터는 클래식(이름 없음) 섀도에서 geoLocation 객체를 지정합니다. ``` "filter": { "geoLocations": [ { "name": "shadow.reported.location", "order": "LonLat" } ] } ``` + 지리적 위치 데이터가 명명된 섀도우에 저장되어 있는 경우 `namedShadowIndexingMode`를 ON으로 설정하고 `namedShadowNames` 필터에 섀도 이름을 추가한 다음 `geoLocations` 필터에 지리 위치 데이터를 지정합니다. 아래 예제 필터는 명명된 섀도(`nameShadow1`)에서 geoLocation 객체를 지정합니다. ``` "filter": { "namedShadowNames": [ "namedShadow1" ], "geoLocations": [ { "name": "shadow.name.namedShadow1.reported.location", "order": "LonLat" } ] } ``` 자세한 내용은 *AWS IoT* *API 참조*의 [IndexingFilter](https://docs.aws.amazon.com/iot/latest/apireference/API_IndexingFilter.html)를 참조하세요. ### 인덱싱 구성 예 업데이트 인덱싱 구성을 업데이트하려면 **update-indexing-configuration** CLI 명령를 AWS IoT 사용합니다. 다음 예제에서는 **update-indexing-configuration**을 사용하는 방법을 보여줍니다. 짧은 구문: ``` aws iot update-indexing-configuration --thing-indexing-configuration \ 'thingIndexingMode=REGISTRY_AND_SHADOW, deviceDefenderIndexingMode=VIOLATIONS, namedShadowIndexingMode=ON,filter={namedShadowNames=[thing1shadow]}, thingConnectivityIndexingMode=STATUS, customFields=[{name=attributes.version,type=Number}, {name=shadow.name.thing1shadow.desired.DefaultDesired, type=String}, {name=shadow.desired.power, type=Boolean}, {name=deviceDefender.securityProfile1.NUMBER_VALUE_BEHAVIOR.lastViolationValue.number, type=Number}]' ``` JSON 구문: ``` aws iot update-indexing-configuration --cli-input-json \ '{ "thingIndexingConfiguration": { "thingIndexingMode": "REGISTRY_AND_SHADOW", "thingConnectivityIndexingMode": "STATUS", "deviceDefenderIndexingMode": "VIOLATIONS", "namedShadowIndexingMode": "ON", "filter": { "namedShadowNames": ["thing1shadow"]}, "customFields": [ { "name": "shadow.desired.power", "type": "Boolean" }, {"name": "attributes.version", "type": "Number"}, {"name": "shadow.name.thing1shadow.desired.DefaultDesired", "type": "String"}, {"name": "deviceDefender.securityProfile1.NUMBER_VALUE_BEHAVIOR.lastViolationValue.number", "type": Number} ] } }' ``` 이 명령은 출력을 생성하지 않습니다. 사물 인덱스 상태를 확인하려면 `describe-index` CLI 명령을 실행합니다. ``` aws iot describe-index --index-name "AWS_Things" ``` `describe-index` 명령의 출력은 다음과 같습니다. ``` { "indexName": "AWS_Things", "indexStatus": "ACTIVE", "schema": "MULTI_INDEXING_MODE" } ``` **참고** 플릿 인덱싱이 플릿 인덱스를 업데이트하는 데 잠시 시간이 걸릴 수 있습니다. `indexStatus`가 ACTIVE로 표시될 때까지 기다렸다가 사용하는 것이 좋습니다. 구성한 데이터 원본에 따라 스키마 필드에 다른 값이 있을 수 있습니다. 자세한 내용은 [사물 인덱스 설명](#describe-index)을 참조하세요. 사물 인덱싱 구성 세부 정보를 보려면 `get-indexing-configuration` CLI 명령을 실행합니다. ``` aws iot get-indexing-configuration ``` `get-indexing-configuration` 명령의 출력은 다음과 같습니다. ``` { "thingIndexingConfiguration": { "thingIndexingMode": "REGISTRY_AND_SHADOW", "thingConnectivityIndexingMode": "STATUS", "deviceDefenderIndexingMode": "VIOLATIONS", "namedShadowIndexingMode": "ON", "managedFields": [ { "name": "connectivity.disconnectReason", "type": "String" }, { "name": "registry.version", "type": "Number" }, { "name": "thingName", "type": "String" }, { "name": "deviceDefender.violationCount", "type": "Number" }, { "name": "shadow.hasDelta", "type": "Boolean" }, { "name": "shadow.name.*.version", "type": "Number" }, { "name": "shadow.version", "type": "Number" }, { "name": "connectivity.version", "type": "Number" }, { "name": "connectivity.timestamp", "type": "Number" }, { "name": "shadow.name.*.hasDelta", "type": "Boolean" }, { "name": "registry.thingTypeName", "type": "String" }, { "name": "thingId", "type": "String" }, { "name": "connectivity.connected", "type": "Boolean" }, { "name": "registry.thingGroupNames", "type": "String" } ], "customFields": [ { "name": "shadow.name.thing1shadow.desired.DefaultDesired", "type": "String" }, { "name": "deviceDefender.securityProfile1.NUMBER_VALUE_BEHAVIOR.lastViolationValue.number", "type": "Number" }, { "name": "shadow.desired.power", "type": "Boolean" }, { "name": "attributes.version", "type": "Number" } ], "filter": { "namedShadowNames": [ "thing1shadow" ] } }, "thingGroupIndexingConfiguration": { "thingGroupIndexingMode": "OFF" } } ``` 사용자 지정 필드를 업데이트하려면 `update-indexing-configuration` 명령을 실행하면 됩니다. 예제는 다음과 같습니다. ``` aws iot update-indexing-configuration --thing-indexing-configuration 'thingIndexingMode=REGISTRY_AND_SHADOW,customFields=[{name=attributes.version,type=Number},{name=attributes.color,type=String},{name=shadow.desired.power,type=Boolean},{name=shadow.desired.intensity,type=Number}]' ``` 이 명령은 인덱싱 구성에 `shadow.desired.intensity`를 추가했습니다. **참고** 인덱싱 구성에서 사용자 정의 필드를 업데이트하면 모든 기존 사용자 정의 필드를 덮어씁니다. **update-indexing-configuration**을 호출할 때 모든 사용자 지정 필드를 지정해야 합니다. 인덱스가 다시 작성되면 새로 추가된 필드, 검색 레지스트리 데이터, 섀도우 데이터 및 사물 연결 상태 데이터에 대해 집계 쿼리를 사용할 수 있습니다. 인덱싱 모드를 변경할 때 새 인덱싱 모드를 사용하여 모든 사용자 정의 필드가 유효한지 확인합니다. 예를 들어, `shadow.desired.temperature`라는 사용자 정의 필드에서 `REGISTRY_AND_SHADOW` 모드를 사용하여 시작하는 경우 인덱싱 모드를 `REGISTRY`로 변경하기 전에 `shadow.desired.temperature` 사용자 정의 필드를 삭제해야 합니다. 인덱싱 구성에 해당 인덱싱 모드로 인덱싱되지 않은 사용자 정의 필드가 포함되어 있으면 업데이트가 실패합니다. ## 사물 인덱스 설명 다음은 **describe-index** CLI 명령을 사용하여 현재 사물 인덱스 상태를 가져오는 방법을 나타낸 명령입니다. ``` aws iot describe-index --index-name "AWS_Things" ``` 명령의 응답은 다음과 같을 수 있습니다. ``` { "indexName": "AWS_Things", "indexStatus": "BUILDING", "schema": "REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS" } ``` 인덱싱을 처음 플릿하면가 인덱스를 AWS IoT 빌드합니다. `indexStatus`가 `BUILDING` 상태일 경우 인덱스를 쿼리할 수 없습니다. 사물 인덱스에 대한 `schema`는 인덱싱할 데이터 형식(`REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS`)을 가리킵니다. 인덱스 구성을 변경하면 인덱스를 다시 작성해야 합니다. 이 프로세스 중의 `indexStatus`는 `REBUILDING`입니다. 다시 작성되는 도중에 사물 인덱스의 데이터에 대한 쿼리는 실행할 수 있습니다. 예를 들어, 인덱스가 다시 작성되는 동안 인덱스 구성을 `REGISTRY`에서 `REGISTRY_AND_SHADOW`로 변경하는 경우 최신 업데이트를 포함하여 레지스트리 데이터를 쿼리할 수 있습니다. 하지만 리빌드가 완료될 때까지 섀도우 데이터에 대해서는 쿼리를 실행할 수 없습니다. 인덱스를 빌드 또는 리빌드하는 데 걸리는 시간은 데이터 크기에 따라 달라집니다. 구성한 데이터 원본에 따라 스키마 필드에 다른 값이 표시될 수 있습니다. 아래 테이블에는 다양한 스키마 값과 해당 설명이 나와 있습니다. | 스키마 | 설명 | | --- | --- | | OFF | 데이터 원본이 구성되거나 인덱싱되지 않습니다. | | REGISTRY | 레지스트리 데이터는 인덱싱됩니다. | | REGISTRY\$1AND\$1SHADOW | 레지스트리 데이터와 명명되지 않은(클래식) 섀도우 데이터가 인덱싱됩니다. | | REGISTRY\$1AND\$1CONNECTIVITY | 레지스트리 데이터와 연결 데이터가 인덱싱됩니다. | | REGISTRY\$1AND\$1SHADOW\$1AND\$1CONNECTIVITY\$1STATUS | 레지스트리 데이터, 명명되지 않은 (클래식) 섀도우 데이터 및 연결 데이터가 인덱싱됩니다. | | MULTI\$1INDEXING\$1MODE | 레지스트리, 명명되지 않은 (클래식) 섀도우 또는 연결 데이터 외에 명명된 섀도우 또는 Device Defender 위반 데이터가 인덱싱됩니다. | ## 사물 인덱스에 대한 쿼리 **search-index** CLI 명령을 사용하여 인덱스의 데이터에 대한 쿼리를 실행합니다. ``` aws iot search-index --index-name "AWS_Things" --query-string "thingName:mything*" ``` ``` { "things":[{ "thingName":"mything1", "thingGroupNames":[ "mygroup1" ], "thingId":"a4b9f759-b0f2-4857-8a4b-967745ed9f4e", "attributes":{ "attribute1":"abc" }, "connectivity": { "connected":false, "timestamp":1556649874716, "disconnectReason": "CONNECTION_LOST" } }, { "thingName":"mything2", "thingTypeName":"MyThingType", "thingGroupNames":[ "mygroup1", "mygroup2" ], "thingId":"01014ef9-e97e-44c6-985a-d0b06924f2af", "attributes":{ "model":"1.2", "country":"usa" }, "shadow":{ "desired":{ "location":"new york", "myvalues":[3, 4, 5] }, "reported":{ "location":"new york", "myvalues":[1, 2, 3], "stats":{ "battery":78 } }, "metadata":{ "desired":{ "location":{ "timestamp":123456789 }, "myvalues":{ "timestamp":123456789 } }, "reported":{ "location":{ "timestamp":34535454 }, "myvalues":{ "timestamp":34535454 }, "stats":{ "battery":{ "timestamp":34535454 } } } }, "version":10, "timestamp":34535454 }, "connectivity": { "connected":true, "timestamp":1556649855046 } }], "nextToken":"AQFCuvk7zZ3D9pOYMbFCeHbdZ+h=G" } ``` JSON 응답에서 `"connectivity"`(`thingConnectivityIndexingMode=STATUS` 설정으로 사용 설정됨)는 부울 값, 타임스탬프 및 디바이스가 AWS IoT Core에 연결되었는지를 나타내는 disconnectReason을 제공합니다. `CONNECTION_LOST`로 인해 POSIX 시간 `1556649874716`에 연결 해제된(`false`) 디바이스 `"mything1"`입니다. 연결 해제 이유에 대한 자세한 내용은 [수명 주기 이벤트](life-cycle-events.md)를 참조하세요. ``` "connectivity": { "connected":false, "timestamp":1556649874716, "disconnectReason": "CONNECTION_LOST" } ``` POSIX 시간 `1556649855046`에 연결된(`true`) 디바이스 `"mything2"`: ``` "connectivity": { "connected":true, "timestamp":1556649855046 } ``` 타임스탬프는 Epoch 이후 밀리초 단위로 제공되므로 `1556649855046`은 2019년 4월 30일 화요일 오후 6:44:15.046(UTC)을 나타냅니다. **중요** 디바이스가 약 한 시간 동안 연결이 끊어져 있으면 연결 상태 값 `"timestamp"` 및 `"disconnectReason"`이 누락되었을 수 있습니다. ## 규제 및 제한 `AWS_Things`에 대한 규제 및 제한입니다. **복잡한 유형의 섀도우 필드** 섀도우 필드는 필드 값이 배열을 포함하지 않는 JSON 객체 또는 단순 유형으로만 구성된 배열과 같은 단순 유형인 경우에만 인덱싱됩니다. 단순한 유형이란 문자열, 숫자 또는 문자의 한 부분이 `true` 또는 `false`라는 의미입니다. 예를 들어, 다음의 섀도우 상태에서 `"palette"` 필드의 값은 유형이 복잡한 항목이 포함된 어레이이므로 인덱싱되지 않습니다. `"colors"` 필드의 값은 어레이의 각 값이 문자열이므로 인덱스 처리됩니다. ``` { "state": { "reported": { "switched": "ON", "colors": [ "RED", "GREEN", "BLUE" ], "palette": [ { "name": "RED", "intensity": 124 }, { "name": "GREEN", "intensity": 68 }, { "name": "BLUE", "intensity": 201 } ] } } } ``` **중첩 섀도우 필드 이름** 중첩 섀도우 필드의 이름은 마침표(.)로 구분된 문자열로 저장됩니다. 예를 들어, 섀도우 문서가 다음과 같을 경우 ``` { "state": { "desired": { "one": { "two": { "three": "v2" } } } } } ``` 필드 `three`의 이름은 `desired.one.two.three`로 저장됩니다. 섀도우 문서가 다음과 같이 저장된 경우에도 ``` { "state": { "desired": { "one.two.three": "v2" } } } ``` 둘 다 `shadow.desired.one.two.three:v2`에 대한 쿼리와 일치합니다. 섀도우 필드 이름에 마침표를 사용하지 마세요. **섀도우 메타데이터** 섀도우 메타데이터 섹션의 필드는 인덱스 처리가 되지만, 섀도우의 `"state"` 섹션에서 해당 필드가 인덱스 처리된 경우에만 처리됩니다. (앞의 예에서 섀도우의 메타데이터 섹션의 `"palette"` 필드도 인덱싱되지 않습니다.) **등록되지 않은 디바이스** 플릿 인덱싱은 [레지스트리](https://docs.aws.amazon.com//iot/latest/developerguide/thing-registry.html)에 등록된 사물의 `thingName`과 연결 `clientId`가 동일한 디바이스의 연결 상태를 인덱싱합니다. **미등록 섀도우** [UpdateThingShadow](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html)를 사용하여 AWS IoT 계정에 등록되지 않은 사물 이름을 사용하여 섀도우를 생성하는 경우이 섀도우의 필드는 인덱싱되지 않습니다. 이는 명명되지 않은 클래식 섀도우와 명명된 섀도우 모두에 적용됩니다. **숫자 값** 레지스트리 혹은 섀도우 데이터가 서비스에서 숫자 값으로 인식되는 경우, 숫자 값으로 인덱스 처리합니다. 범위와 비교 연산자를 포함한 쿼리를 숫자 값에 형성할 수 있습니다(예: `"attribute.foo<5"` 또는 `"shadow.reported.foo:[75 TO 80]"`). 숫자로 인식되려면 데이터 값이 유효한 리터럴 유형 JSON 숫자여야 합니다. 값은 -2^53\$12^53-1 범위의 정수, 선택적 지수 표기법이 있는 배정밀도 부동 소수점 또는 이러한 값만 포함하는 배열의 일부일 수 있습니다. **Null 값** Null 값은 인덱싱되지 않습니다. **최대값** 집계 쿼리의 최대 사용자 정의 필드 수는 5개입니다. 집계 쿼리에 대해 요청된 최대 백분위수는 100입니다. ## 권한 부여 다음과 같이 AWS IoT 정책 작업에서 사물 인덱스를 Amazon 리소스 이름(ARN)으로 지정할 수 있습니다. **** | 작업 | Resource | | --- | --- | | `iot:SearchIndex` | 인덱스 ARN(예: `arn:aws:iot:your-aws-regionyour-aws-account:index/AWS_Things`) | | `iot:DescribeIndex` | 인덱스 ARN(예: `arn:aws:iot:your-aws-region:index/AWS_Things`) | **참고** 플릿 인덱스를 쿼리할 권한이 있는 경우 전체 플릿에서 사물 데이터에 액세스할 수 있습니다.