モノのインデックス作成の有効化モノのインデックスの説明モノのインデックスのクエリ制約と制限 Authorization

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

AWS_Things はモノに対して作成されたインデックスです。インデックスを作成する対象 - レジストリデータ、シャドウデータおよびデバイスの接続状態データ (デバイスライフサイクルイベントによる) を制御できます。

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

update-indexing-configuration CLI コマンドまたは UpdateIndexingConfiguration API を使用して、AWS_Things インデックスを作成し、その設定を管理します。--thing-indexing-configuration (thingIndexingConfiguration) パラメータを使用すると、インデックスを作成するデータの種類（レジストリ、シャドウ、デバイス接続データなど）を制御できます。

--thing-indexing-configuration パラメータは、次の構造を持つ文字列を取ります。


{
  "thingIndexingMode": "OFF"|"REGISTRY"|"REGISTRY_AND_SHADOW",
  "thingConnectivityIndexingMode": "OFF"|"STATUS",
  "customFields": [
    { name: field-name, type: String | Number | Boolean },
    ...
  ]
}

thingIndexingMode 属性は、インデックスが作成されるデータの種類を制御します。有効な値は次のとおりです。

VOFF: インデックス作成なし。
REGISTRY: インデックスレジストリデータ。
REGISTRY_AND_SHADOW: インデックスレジストリと Thing Shadow データ。

thingConnectivityIndexingMode 属性は、モノの接続性データにインデックスを付けるかどうかを指定します。有効な値は次のとおりです。

VOFF: モノ接続性データはインデックス化されません。
STATUS: モノ接続性データがインデックス化されます。

customFields 属性は、フィールドとデータ型のペアのリストです。集計クエリは、データ型に基づいて、これらのフィールドに対して実行できます。選択するインデックス作成モード（REGISTRY または REGISTRY_AND_SHADOW）は、customFields で指定できるフィールドに影響します。たとえば、REGISTRY インデックス作成モードを指定した場合、Thing Shadow からフィールドを指定することはできません。インデックスを作成するには、customFields でカスタムフィールドを指定する必要があります。

設定内のカスタムフィールドとインデックスが作成される値の間に型の不整合がある場合、フリートインデックス作成サービスは集計クエリの不整合値を無視します。CloudWatch ログは、集約クエリの問題のトラブルシューティングに役立ちます。詳細については、「」を参照してくださいフリートインデックス作成サービスの集約クエリのトラブルシューティング

管理対象フィールドには、IoT のモノ、モノのグループ、デバイスシャドウに関連するデータが含まれます。管理対象フィールドのデータ型は、AWS IoT で定義されます。IoT モノを作成するときに、各管理対象フィールドの値を指定します。たとえば、モノの名前、モノのグループ、モノの説明はすべて管理対象フィールドです。フリートインデックス作成サービスは、指定したインデックス作成モードに基づいて、管理対象フィールドのインデックスを作成します。

レジストリの管理対象フィールド


"managedFields" : [
  {name:thingId, type:String},
  {name:thingName, type:String},
  {name:registry.version, type:Number},
  {name:registry.thingTypeName, type:String},
  {name:registry.thingGroupNames, type:String},
]

Thing Shadow の管理対象フィールド


"managedFields" : [
  {name:shadow.version, type:Number},
  {name:shadow.hasDelta, type:Boolean}
]

モノの接続性の管理対象フィールド


"managedFields" : [
  {name:connectivity.timestamp, type:Number},
  {name:connectivity.version, type:Number},
  {name:connectivity.connected, type:Boolean}
]

モノのグループの管理対象フィールド


"managedFields" : [
  {name:description, type:String},
  {name:parentGroupNames, type:String},
  {name:thingGroupId, type:String},
  {name:thingGroupName, type:String},
  {name:version, type:Number},
]

customFields では、管理対象フィールドを変更したり表示することはできません。

次に、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}}]

このコマンドは、レジストリおよびシャドウデータのインデックス作成を有効にします。集計クエリは、管理対象フィールドと、データ型に基づいて提供される customFields で動作します。

get-indexing-configuration CLI コマンドまたは GetIndexingConfiguration API を使用して、現在のインデックス作成設定を取得できます。

以下のコマンドは、get-indexing-configuration CLI コマンドを使用して、5 つのカスタムフィールド（3 つのレジストリカスタムフィールドと 2 つのシャドウカスタムフィールド）が定義されている現在のモノインデックス作成設定を取得する方法を示しています。

aws iot get-indexing-configuration


{
    "thingGroupIndexingConfiguration": {
        "thingGroupIndexingMode": "OFF"
    },
    "thingIndexingConfiguration": {
        "thingConnectivityIndexingMode": "STATUS",
        "customFields": [
            {
                "name": "attributes.customField_NUM",
                "type": "Number"
            },
            {
                "name": "shadow.desired.customField_STR",
                "type": "String"
            },
            {
                "name": "shadow.desired.customField_NUM",
                "type": "Number"
            },
            {
                "name": "attributes.customField_STR",
                "type": "String"
            },
            {
                "name": "attributes.customField_BOOL",
                "type": "Boolean"
            }
        ],
        "thingIndexingMode": "REGISTRY_AND_SHADOW",
        "managedFields": [
            {
                "name": "shadow.hasDelta",
                "type": "Boolean"
            },
            {
                "name": "registry.thingGroupNames",
                "type": "String"
            },
            {
                "name": "connectivity.version",
                "type": "Number"
            },
            {
                "name": "registry.thingTypeName",
                "type": "String"
            },
            {
                "name": "connectivity.connected",
                "type": "Boolean"
            },
            {
                "name": "registry.version",
                "type": "Number"
            },
            {
                "name": "thingId",
                "type": "String"
            },
            {
                "name": "connectivity.timestamp",
                "type": "Number"
            },
            {
                "name": "thingName",
                "type": "String"
            },
            {
                "name": "shadow.version",
                "type": "Number"
            }
        ]
    }
}

次の表は、thingIndexingMode、thingConnectivityIndexingMode および関連する効果の使用可能な組み合わせを示しています。必須の thingIndexingMode パラメータは、レジストリデータだけ、またはレジストリおよびシャドウデータが、AWS_Things インデックスに含まれるかどうかを指定します。オプションの thingConnectivityIndexingMode パラメータは、インデックスに接続ステータスデータ (つまり、AWS IoT にデバイスが接続され、切断された時点) も含まれるかどうかを指定します。

`thingIndexingMode`	`thingConnectivityIndexingMode`	結果
VOFF	未指定。	インデックスを作成しない、またはインデックスを削除します。
VOFF	VOFF	前のエントリに相当します。
REGISTRY	未指定。	`AWS_Things` インデックスを作成または設定して､ Registry データのみのインデックスを作成します｡
REGISTRY	VOFF	前のエントリに相当します。(レジストリデータのインデックスのみ作成されます。)
REGISTRY_AND_SHADOW	未指定。	`AWS_Things` インデックスを作成または設定して､レジストリデータとシャドウデータのインデックスを作成します｡
REGISTRY_AND_SHADOW	VOFF	前のエントリに相当します。(レジストリデータとシャドウデータのインデックスが作成されます。)
REGISTRY	STATUS	`AWS_Things` インデックスを作成または設定して､レジストリデータとモノの接続ステータスデータのインデックスを作成します (REGISTRY_AND_CONNECTIVITY_STATUS)。
REGISTRY_AND_SHADOW	STATUS	`AWS_Things` インデックスを作成または設定して､レジストリデータ、シャドウデータとモノの接続ステータスデータのインデックスを作成します (REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS)。

AWS IoT update-indexing-configuration CLI コマンドを使用すると、インデックス作成の設定を更新できます。次に、update-indexing-configuration CLI コマンドの使用例を示します。

短い構文:

aws iot update-indexing-configuration --thing-indexing-configuration "thingIndexingMode=REGISTRY_AND_SHADOW,thingConnectivityIndexingMode=STATUS,customFields=[{name=attributes.version,type=Number},{name=attributes.color,type=String},{name=shadow.desired.power,type=Boolean}]"

JSON 構文:

aws iot update-indexing-configuration --cli-input-json \ '{ "thingIndexingConfiguration": { "thingIndexingMode": "REGISTRY_AND_SHADOW", "thingConnectivityIndexingMode": "STATUS", "customFields": [ { "name": "shadow.desired.power", "type": "Boolean" }, { "name": "attributes.color", "type": "String" }, { "name": "attributes.version", "type": "Number" } ] } }'

これらのコマンドの出力は次のとおりです。


{
    "thingIndexingConfiguration": {
        "thingConnectivityIndexingMode": "STATUS",
        "customFields": [
            {
                "type": "String",
                "name": "attributes.color"
            },
            {
                "type": "Number",
                "name": "attributes.version"
            },
            {
                "type": "Boolean",
                "name": "shadow.desired.power"
            }
        ],
        "thingIndexingMode": "REGISTRY_AND_SHADOW",
        "managedFields": [
            {
                "type": "Boolean",
                "name": "connectivity.connected"
            },
            {
                "type": "String",
                "name": "registry.thingTypeName"
            },
            {
                "type": "String",
                "name": "thingName"
            },
            {
                "type": "Number",
                "name": "shadow.version"
            },
            {
                "type": "String",
                "name": "thingId"
            },
            {
                "type": "Boolean",
                "name": "shadow.hasDelta"
            },
            {
                "type": "Number",
                "name": "connectivity.timestamp"
            },
            {
                "type": "String",
                "name": "registry.thingGroupNames"
            },
            {
                "type": "Number",
                "name": "connectivity.version"
            },
            {
                "type": "Number",
                "name": "registry.version"
            }
        ]
    },
    "thingGroupIndexingConfiguration": {
        "thingGroupIndexingMode": "OFF"
    }
}

次の例では、新しいカスタムフィールドが設定に追加されます。

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 を呼び出すときは、必ずすべてのカスタムフィールドを指定してください。

インデックスを再構築したら、新しく追加したフィールドに対して集計クエリを使用し、レジストリデータ、シャドウデータ、およびモノの接続状態データを検索できます。

インデックス作成モードを変更するときは、新しいインデックス作成モードを使用して、すべてのカスタムフィールドが有効であることを確認してください。たとえば、REGISTRY_AND_SHADOW というカスタムフィールドを使用して shadow.desired.temperature モードを開始する場合、インデックス作成モードを shadow.desired.temperature に変更する前に REGISTRY カスタムフィールドを削除する必要があります。インデックス作成設定にインデックス作成モードによってインデックス化されていないカスタムフィールドが含まれている場合、更新は失敗します。

モノのインデックスの説明

次のコマンドは、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 データのクエリを行うことはできません。インデックスの作成または再構築に要する時間は、データの量によって異なります。

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

インデックスのデータにクエリを実行するには、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
         }         
    },
    {  
        "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 に接続されているかどうかを示すブール値およびタイムスタンプが得られます。デバイス "mything1" は、POSIX 時間 false に切断されました (1556649874716)。


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

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


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

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

重要

デバイスが約 1 時間切断されていた場合、接続ステータスの "timestamp" 値が含まれていない場合があります。

制約と制限

以下は、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 値はインデックス化されません。

集計クエリのカスタムフィールドの最大数

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

100

Authorization

次のように、AWS IoT ポリシーアクションでリソース 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`）。

注記

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

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

フリートインデックス作成サービス

モノのグループのインデックス作成の管理