モノのインデックス作成の管理

注記 インデックス作成の名前付きシャドウおよび AWS IoT Device Defender 違反のデータをサポートするフリートインデックス作成の機能は、AWS IoT Device Management のプレビューで、変更される可能性があります。

すべてのモノに対して作成されるインデックスは AWS_Things です。次のデータソースからインデックス化する対象を制御できます: AWS IoT レジストリデータ、AWS IoT Device Shadow データ、AWS IoT 接続性データ、および AWS IoT Device Defender 違反データ

モノのインデックス作成の有効化

update-indexing-configuration CLI コマンドまたは UpdateIndexingConfiguration 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" 
    },
    ...
  ]
}

モノのインデックス作成モード

thingIndexingMode 属性は、インデックスが作成されるデータの種類を制御します。

重要

モノのインデックス作成を有効にするには、thingIndexingMode 属性を OFF に設定してはいけません。

属性	有効な値	説明
thingIndexingMode	VOFF	インデックス作成なし。
	REGISTRY	インデックスレジストリデータ。
	REGISTRY_AND_SHADOW	インデックスレジストリと Thing Shadow データ。

thingConnectivityIndexingMode 属性は、モノの接続性データにインデックスを付けるかどうかを指定します。

属性	有効な値	説明
thingConnectivityIndexingMode	未指定。	モノの接続性データにインデックスは付けられません。
	VOFF	モノの接続性データにインデックスは付けられません。
	STATUS	モノの接続性データにインデックスが付けられます。

deviceDefenderIndexingMode 属性は、Device Defender 違反のデータにインデックスを付けるかどうかを指定します。

属性	有効な値	説明
deviceDefenderIndexingMode	未指定。	Device Defender 違反のデータにインデックスは付けられません。
	VOFF	Device Defender 違反のデータにインデックスは付けられません。
	VIOLATIONS	Device Defender 違反のデータにインデックスが付けられます。

namedShadowIndexingMode 属性は、名前付きシャドウデータにインデックスを付けるかどうかを指定します。

属性	有効な値	説明
namedShadowIndexingMode	未指定。	名前付きシャドウデータにインデックスは付けられません。
	VOFF	名前付きシャドウデータにインデックスは付けられません。
	ON	名前付きシャドウデータにインデックスが付けられます。

管理対象フィールドとカスタムフィールド

管理対象フィールド

管理対象フィールドには、モノ、モノのグループ、デバイスシャドウ、デバイスの接続性、および Device Defender 違反に関連するデータが含まれます。管理対象フィールドのデータ型は、AWS IoT により定義されます。IoT モノを作成するときに、各管理対象フィールドの値を指定します。例えば、モノの名前、モノのグループ、モノの説明はすべて管理対象フィールドです。フリートインデックス作成では、指定したインデックス作成モードに基づいて、管理対象フィールドがインデックス化されます。customFields では、管理対象フィールドを変更したり表示することはできません。

カスタムフィールド

カスタムフィールドを作成してインデックスを作成し、属性、Device Shadow データ、および Device Defender 違反のデータを集計できます。customFields 属性は、フィールド名とデータ型のペアのリストです。データ型に基づいて、集計クエリを実行できます。選ぶインデックス作成モードは、customFields で指定できるフィールドに影響します。例えば、REGISTRY インデックス作成モードを指定した場合、Thing Shadow からカスタムフィールドを指定することはできません。update-indexing-configuration CLI コマンドを使用して、カスタムフィールドを作成または更新できます (Updating indexing configuration examples のコマンド例を参照してください)。詳細については、「Custom fields」を参照してください。

インデックス作成の設定例を更新する

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,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",
          "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"
            }
        ]
    },
    "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 に変更した場合、最新の更新を含むレジストリデータのクエリを行うことができます。ただし、再構築が完了するまで Shadow データのクエリを行うことはできません。インデックスの作成または再構築に要する時間は、データの量によって異なります。

スキーマフィールドには、設定したデータソースに応じて、さまざまな値を表示できます。次の表に、さまざまなスキーマの値と対応する説明を示します。

スキーマ	説明
VOFF	データソースが設定またはインデックス化されていません。
REGISTRY	レジストリデータがインデックス化されます。
REGISTRY_AND_SHADOW	レジストリデータおよび名前のない (クラシック) シャドウデータがインデックス化されます。
REGISTRY_AND_CONNECTIVITY	レジストリデータおよび接続性データがインデックス化されます。
REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS	レジストリデータ、名前のない (クラシック) シャドウデータ、および接続性データがインデックス化されます。
MULTI_INDEXING_MODE	レジストリ、名前のない (クラシック) シャドウ、または接続性データに加えて、名前付きシャドウまたは Device Defender 違反のデータがインデックス化されます。

モノのインデックスのクエリ

インデックスのデータにクエリを実行するには、CLI の search-index コマンドを使用します。

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 をを提供します。デバイス "mything1" は、POSIX 時間 1556649874716 にCONNECTION_LOSTのために切断されました (false)。切断理由の詳細については、「ライフサイクルイベント」を参照してください。

"connectivity": { 
    "connected":false,
    "timestamp":1556649874716, 
    "disconnectReason": "CONNECTION_LOST"
}

デバイス"mything2" は、POSIX 時間 1556649855046に接続されました (true)。

"connectivity": { 
    "connected":true,
    "timestamp":1556649855046
}

タイムスタンプは、エポックからの経過をミリ秒単位で提供されるため、1556649855046 は、2019 年 4 月 30 日火曜日の午後 6 時 44 分 15. 046秒 (UTC) を表します。

重要

デバイスが約 1 時間切断されていた場合、"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" フィールドもインデックス化されません。)

未登録シャドウ

UpdateThingShadow を使用して、AWS IoT アカウントで登録されていないモノの名前でシャドウを作成する場合、このシャドウのフィールドはインデックス化されません。これは、名前のないクラシックシャドウと名前付きシャドウの両方に適用されます。

数値

レジストリまたはシャドウデータがサービスによって数値として認識される場合、そのようにインデックス化されます。数値の範囲および比較演算子を含むクエリを作成できます (例: "attribute.foo<5" または "shadow.reported.foo:[75 TO 80]")。数値として認識されるには、データの値が有効なリテラルタイプの JSON 番号である必要があります。値は、範囲 -2^53...2^53-1 の整数、オプションの指数関数表記を使用した倍精度浮動小数点、またはそのような値のみを含む配列の一部である必要があります。

Null 値

Null 値はインデックス化されません。

最大値

集計クエリのカスタムフィールドの最大数は 5 です。

集計クエリで要求されるパーセンタイルの最大数は 100 です。

フリートインデックス作成によって処理されるモノの合計の最大のデータサイズは 32 KB に制限されています。このデータには、レジストリ、クラシックおよび名前付きシャドウ、接続性のライフサイクルイベント、Device Defender 違反のデータからのインデックス化されたデータが含まれます。

モノあたりの名前付きシャドウの最大数は 5 です。

フリートインデックス作成がサポートする最大帯域幅は 32 MBps です。

承認

次のように、AWS IoT ポリシーアクションで Amazon Resource Name (ARN) としてのモノのインデックスを指定できます｡

アクション	リソース
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）。

注記

フリートインデックスに対してクエリを実行するアクセス許可があるユーザーは、フリート全体でモノのデータにアクセスできます。