사물 인덱싱 관리 - AWS IoT Core
사물 인덱싱 활성화사물 인덱스 설명사물 인덱스에 대한 쿼리규제 및 제한권한 부여

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

사물 인덱싱 관리

모든 사물에 대해 생성된 인덱스는 AWS_Things입니다. AWS IoT 레지스트리 데이터, AWS IoT 디바이스 섀도우 데이터, AWS IoT 연결 데이터 및 AWS IoT Device Defender 위반 데이터와 같은 데이터 원본에서 인덱싱할 대상을 제어할 수 있습니다.

사물 인덱싱 활성화

update-indexing-configuration CLI 명령 또는 구성 API 작업을 사용하여 인덱스를 생성하고 UpdateIndexingAWS_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으로 설정하고 filter에서 명명된 섀도우 이름을 지정합니다.

아래 표에는 각 인덱싱 모드의 유효한 값과 각 값에 대해 인덱싱된 데이터 원본이 나와 있습니다.

속성 유효값 레지스트리 섀도우 연결 DD 위반 명명된 섀도우
thingIndexingMode OFF
REGISTRY ✓
REGISTRY_AND_SHADOW ✓ ✓
thingConnectivityIndexingMode 지정되지 않음.
OFF
STATUS ✓
deviceDefenderIndexingMode 지정되지 않음.
OFF
VIOLATIONS ✓
namedShadowIndexingMode 지정되지 않음.
OFF
ON ✓

관리형 필드 및 사용자 정의 필드

관리형 필드

관리되는 필드에는 사물, 사물 그룹, 디바이스 섀도우, 디바이스 연결 및 Device Defender 위반과 관련된 데이터가 포함됩니다. AWS IoT 관리 필드의 데이터 유형을 정의합니다. AWS IoT 사물을 생성할 때 각 관리형 필드의 값을 지정합니다. 예를 들어, 사물 이름, 사물 그룹 및 사물 설명은 모두 관리형 필드입니다. 플릿 인덱싱은 지정한 인덱싱 모드를 기반으로 관리형 필드를 인덱싱합니다. 관리형 필드는 customFields에서 변경하거나 표시할 수 없습니다.

사용자 지정 필드

속성, 디바이스 섀도우 데이터 및 Device Defender 위반 데이터를 인덱싱할 사용자 지정 필드를 만들어 집계할 수 있습니다. customFields 속성은 필드 이름과 데이터 형식 페어의 목록입니다. 데이터 유형에 따라 집계 쿼리를 수행할 수 있습니다. 선택한 인덱싱 모드는 customFields에서 지정할 수 있는 필드에 영향을 줍니다. 예를 들어, REGISTRY 인덱싱 모드를 지정하면 사물 섀도우에서 사용자 지정 필드를 지정할 수 없습니다. update-indexing-configuration CLI 명령을 사용하여 사용자 정의 필드를 생성하거나 업데이트할 수 있습니다(인덱싱 구성 예 업데이트의 예제 명령 참조). 자세한 내용은 사용자 정의 필드를 참조하세요.

인덱싱 필터

인덱싱 필터는 명명된 섀도우 및 지오로케이션 데이터에 대한 추가 선택 항목을 제공합니다.

namedShadowNames

플릿 인덱싱 구성에 네임드 섀도우를 추가하려면 namedShadowIndexingMode 로 설정하고 필터에 명명된 섀도우 이름을 지정하십시오. ON namedShadowNames

예

"filter": {
     "namedShadowNames": [ "namedShadow1", "namedShadow2" ]
}

geoLocations

플릿 인덱싱 구성에 지오로케이션 데이터를 추가하려면:

  • 지오로케이션 데이터가 이름 없는 클래식 섀도우에 저장되는 경우 thingIndexingMode REGISTRY_AND_SHADOW로 설정하고 필터에 지오로케이션 데이터를 지정하세요. geoLocations

    아래 예제 필터는 이름이 지정되지 않은 클래식 섀도우의 GeoLocation 객체를 지정합니다.

    "filter": {
     "geoLocations": [
        {
            "name": "shadow.reported.location",
            "order": "LonLat"
        }
     ]
  }

  • 지오로케이션 데이터가 명명된 섀도우에 저장되어 있는 경우 namedShadowIndexingMode ON으로 설정하고 필터에 섀도우 이름을 추가하고 namedShadowNames 필터에 지오로케이션 데이터를 지정하십시오. geoLocations

    아래 예제 필터는 이름이 지정된 shadow () 에 GeoLocation 객체를 지정합니다. nameShadow1 

    "filter": {
     "namedShadowNames": [ "namedShadow1" ],
     "geoLocations": [
        {
            "name": "shadow.name.namedShadow1.reported.location",
            "order": "LonLat"
        }
     ]
  }

자세한 내용은 AWS IoTAPI IndexingFilter참조를 참조하십시오.

인덱싱 구성 예 업데이트

인덱싱 구성을 업데이트하려면 AWS IoT update-indexing-configuration CLI 명령을 사용합니다. 다음 예제에서는 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로 표시될 때까지 기다렸다가 사용하는 것이 좋습니다. 구성한 데이터 원본에 따라 스키마 필드에 다른 값이 있을 수 있습니다. 자세한 내용은 사물 인덱스 설명을 참조하세요.

사물 인덱싱 구성 세부 정보를 보려면 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_AND_SHADOW 레지스트리 데이터와 명명되지 않은(클래식) 섀도우 데이터가 인덱싱됩니다.
REGISTRY_AND_CONNECTIVITY 레지스트리 데이터와 연결 데이터가 인덱싱됩니다.
REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS 레지스트리 데이터, 명명되지 않은 (클래식) 섀도우 데이터 및 연결 데이터가 인덱싱됩니다.
MULTI_INDEXING_MODE

레지스트리, 명명되지 않은 (클래식) 섀도우 또는 연결 데이터 외에 명명된 섀도우 또는 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"입니다. 연결 해제 이유에 대한 자세한 내용은 수명 주기 이벤트를 참조하세요.

"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" 필드도 인덱싱되지 않습니다.)

등록되지 않은 디바이스

플릿 인덱싱은 레지스트리에 등록된 사물의 thingName과 연결 clientId가 동일한 디바이스의 연결 상태를 인덱싱합니다.

미등록 섀도우

AWS IoT 계정에 등록되지 않은 사물 이름을 사용하여 섀도우를 사용하여 섀도우를 생성하는 경우 이 섀도우의 필드는 인덱싱되지 않습니다. UpdateThing 이는 명명되지 않은 클래식 섀도우와 명명된 섀도우 모두에 적용됩니다.

숫자 값

레지스트리 혹은 섀도우 데이터가 서비스에서 숫자 값으로 인식되는 경우, 숫자 값으로 인덱스 처리합니다. 범위와 비교 연산자를 포함한 쿼리를 숫자 값에 형성할 수 있습니다(예: "attribute.foo<5" 또는 "shadow.reported.foo:[75 TO 80]"). 숫자로 인식되려면 데이터 값이 유효한 리터럴 유형 JSON 숫자여야 합니다. 값은 -2^53~2^53-1 범위의 정수, 선택적 지수 표기법이 있는 배정밀도 부동 소수점 또는 이러한 값만 포함하는 배열의 일부일 수 있습니다.

Null 값

Null 값은 인덱싱되지 않습니다.

최대값

집계 쿼리의 최대 사용자 정의 필드 수는 5개입니다.

집계 쿼리에 대해 요청된 최대 백분위수는 100입니다.

권한 부여

다음과 같이 AWS IoT 정책 작업에서 things 인덱스를 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)
참고

플릿 인덱스를 쿼리할 권한이 있는 경우 전체 플릿에서 사물 데이터에 액세스할 수 있습니다.