Gérer l'indexation d'objet - AWS IoT Core
Activation de l'indexation d'objetDescription d'un index d'objetsInterrogation d'un index d'objetsRestrictions et limitationsAutorisation

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Gérer l'indexation d'objet

AWS_Things est l'index créé pour l'ensemble de vos objets. Vous pouvez contrôler les éléments à indexer à partir des sources de données suivantes : données de AWS IoT registre, données AWS IoT Device Shadow, données de AWS IoT connectivité et données de AWS IoT Device Defenderviolations.

Activation de l'indexation d'objet

Vous utilisez la commande CLI update-indexing-configuration ou UpdateIndexingl'opération de l'API de configuration pour créer AWS_Things l'index et contrôler sa configuration. En utilisant le paramètre --thing-indexing-configuration (thingIndexingConfiguration), vous contrôlez le type de données (par exemple, les données de registre, shadow, de connectivité des appareils et les données de violations de Device Defender) qui sont indexées.

Le paramètre --thing-indexing-configuration prend une chaîne avec la structure suivante :

{
  "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"
        }
    ]
  }
}

Modes d'indexation d’objets

Vous pouvez définir différents modes d'indexation d'objets dans votre configuration d'indexation, en fonction des sources de données que vous souhaitez indexer et à partir desquelles vous souhaitez rechercher des appareils :

  • thingIndexingMode: Contrôle si le registre ou shadow sont indexés. Lorsque thingIndexingMode est défini sur OFF, l'indexation des objets est désactivée.

  • thingConnectivityIndexingMode : Indique si les données de connectivité d'objets sont indexées.

  • deviceDefenderIndexingMode : Indique si les données relatives aux violations de Device Defender sont indexées.

  • namedShadowIndexingMode : Indique si les données fictives nommées sont indexées. Pour sélectionner des shadows nommées à ajouter à la configuration d'indexation de votre flotte, configurez namedShadowIndexingMode comme étant ON et spécifiez les noms de vos shadows nommées dans filter.

Le tableau ci-dessous indique les valeurs valides pour chaque mode d'indexation et la source de données indexée pour chaque valeur.

Attribut Valeurs valides Registre Shadow Connectivité Violations du DD Shadow nommé
thingIndexingMode OFF
REGISTRY ✓
REGISTRY_AND_SHADOW ✓ ✓
thingConnectivityIndexingMode Non spécifié.
OFF
STATUS ✓
deviceDefenderIndexingMode Non spécifié.
OFF
VIOLATIONS ✓
namedShadowIndexingMode Non spécifié.
OFF
ON ✓

Champs gérés et champs personnalisés

Champs gérés

Les champs gérés contiennent des données associées aux objets, aux groupes d'objets, aux ombres des appareils, à la connectivité des appareils et aux violations de Device Defender. AWS IoT définit le type de données dans les champs gérés. Vous spécifiez les valeurs de chaque champ géré lorsque vous créez un objet AWS IoT . Par exemple, les noms d'objets, les groupes d'objets et les descriptions d'objets sont tous des champs gérés. L'indexation de flotte indexe les champs gérés en fonction du mode d'indexation que vous spécifiez. Les champs gérés ne peuvent pas être modifiés ni s'afficher dans customFields.

Champs personnalisés

Vous pouvez agréger les attributs des objets, les données de Device Shadow et les données relatives aux violations de Device Defender en créant des champs personnalisés pour les indexer. L'attribut customFields est une liste de paires de noms de champs et de types de données. Vous pouvez effectuer des requêtes d'agrégation en fonction du type de données. Le mode d'indexation que vous choisissez et qui affecte les champs peut être spécifié dans customFields. Par exemple, si vous spécifiez le mode d'indexation REGISTRY, vous ne pouvez pas spécifier un champ personnalisé à partir d'une shadow d'objet. Vous pouvez utiliser la commande CLI update-indexing-configuration pour créer ou mettre à jour les champs personnalisés (voir un exemple de commande dans la section Mise à jour des exemples de configuration d'indexation). Pour plus d’informations, consultez Champs personnalisés.

Filtre d'indexation

Le filtre d'indexation fournit des sélections supplémentaires pour les shadows nommées et les données de géolocalisation.

namedShadowNames

Pour sélectionner des shadows nommées à ajouter à la configuration d'indexation de votre flotte, configurez namedShadowIndexingMode comme étant ON et spécifiez les noms de vos shadows nommées dans namedShadowNames.

Exemple

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

geoLocations

Pour ajouter des données de géolocalisation à la configuration d'indexation de votre flotte :

  • Si vos données de géolocalisation sont stockées dans une shadow classique (sans nom), définissez thingIndexingMode REGISTRY_AND_SHADOW et spécifiez vos données de géolocalisation dans le filtre geoLocations.

    L'exemple de filtre ci-dessous spécifie un objet GeoLocation dans une shadow classique (sans nom) :

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

  • Si vos données de géolocalisation sont stockées dans une shadow nommée, namedShadowIndexingMode réglez-la sur ON, ajoutez le nom de shadow dans le filtre namedShadowNames et spécifiez vos données de géolocalisation dans le filtre geoLocations.

    L'exemple de filtre ci-dessous spécifie un objet geoLocation dans une shadow nommée (nameShadow1) :

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

Pour plus d'informations, consultez le IndexingFilterGuide de référence des AWS IoTAPI.

Mise à jour des exemples de configuration d'indexation

Pour mettre à jour votre configuration d'indexation, utilisez la commande AWS IoT update-indexing-configuration CLI. Les exemples suivants montrent comment utiliser update-indexing-configuration.

Syntaxe courte :

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}]'

Syntaxe 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} ] } }'

Cette commande ne produit aucune sortie.

Pour vérifier l'état de l'index des objets, exécutez la commande CLI describe-index : 

aws iot describe-index --index-name "AWS_Things"

La sortie de la commande describe-index ressemble à ce qui suit :

{
    "indexName": "AWS_Things",
    "indexStatus": "ACTIVE",
    "schema": "MULTI_INDEXING_MODE"
}
Note

L'indexation de flotte peut prendre un certain temps pour mettre à jour l'indice de flotte. Nous vous recommandons d'attendre que le indexStatus affiche ACTIVE avant de l'utiliser. Le champ de schéma peut contenir différentes valeurs en fonction des sources de données que vous avez configurées. Pour plus d'informations, consultez Description d’un index d'objet.

Pour obtenir les détails de configuration de l'indexation de votre appareil, exécutez la commande CLI get-indexing-configuration : 

aws iot get-indexing-configuration

La sortie de la commande get-indexing-configuration ressemble à ce qui suit :

{
    "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"
    }
}

Pour mettre à jour les champs personnalisés, vous pouvez exécuter la commande update-indexing-configuration. Un exemple se présente comme suit :

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}]'

Cette commande a ajouté shadow.desired.intensity à la configuration d'indexation.

Note

La mise à jour de la configuration d'indexation des champs personnalisés remplace tous les champs personnalisés existants. Assurez-vous de spécifier tous les champs personnalisés lorsque vous appelez update-indexing-configuration.

Une fois l'index régénéré, vous pouvez utiliser une requête d'agrégation sur les champs nouvellement ajoutés et faire des recherches dans les données de registre, les données de shadow et les données de statut de connectivité d'objet.

Lorsque vous modifiez le mode d'indexation, assurez-vous que tous vos champs personnalisés sont valides à l'aide du nouveau mode d'indexation. Par exemple, si vous commencez par le mode REGISTRY_AND_SHADOW avec un champ personnalisé appelé, shadow.desired.temperature, vous devez supprimer le champ personnalisé shadow.desired.temperature avant de remplacer le mode d'indexation par REGISTRY. Si votre configuration d'indexation contient des champs personnalisés qui ne sont pas indexés par le mode d'indexation, la mise à jour échoue.

Description d'un index d'objets

La commande suivante montre comment utiliser la commande d'interface de ligne de commande describe-index pour extraire l'état actuel de l'index d'objets.

aws iot describe-index --index-name "AWS_Things"

La réponse de la commande peut ressembler à ce qui suit :

{
    "indexName": "AWS_Things", 
    "indexStatus": "BUILDING", 
    "schema": "REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS"
}

La première fois que vous indexez une flotte, votre AWS IoT index est créé. Lorsque indexStatus est dans l'état BUILDING, vous ne pouvez pas interroger l'index. Le schema de l'index d'objets indique le type de données (REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS) qui est indexé.

Si vous modifiez la configuration de votre index, ce dernier est recréé. Lors de ce processus, l'indexStatus est REBUILDING. Vous pouvez exécuter des requêtes sur les données de l'index d’objets pendant sa régénération. Par exemple, si vous faites passer la configuration d'index de REGISTRY à REGISTRY_AND_SHADOW, pendant sa régénération, vous pouvez interroger les données de registre, y compris les dernières mises à jour. Toutefois, vous ne pouvez pas interroger les données des shadows tant que la reconstruction n'est pas terminée. Le temps nécessaire pour créer ou recréer l'index dépend de la quantité de données.

Vous pouvez voir différentes valeurs dans le champ de schéma en fonction des sources de données que vous avez configurées. Le tableau suivant affiche les différentes valeurs de schéma et les descriptions correspondantes :

Schema Description
OFF Aucune source de données n'est configurée ou indexée.
REGISTRY Les données du registre sont indexées.
REGISTRY_AND_SHADOW Les données du registre et les données shadow sans nom (classiques) sont indexées.
REGISTRY_ET_CONNECTIVITÉ_ Les données de registre et les données de connectivité sont indexées.
REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS REGISTRY_AND_CONNECTIVITY_STATUS Les données de registre, les données shadow sans nom (classiques) et les données de connectivité sont indexées.
MULTI_INDEXING_MODE

Les données relatives aux violations de Named Shadow ou Device Defender sont indexées, en plus des données de registre, shadow anonyme (classique) ou de connectivité.

Interrogation d'un index d'objets

Utilisez la commande de l'interface de ligne de commande search-index pour interroger les données dans l'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"
}

Dans la réponse JSON "connectivity" (telle qu'activée par le paramètre thingConnectivityIndexingMode=STATUS), fournit une valeur booléenne, un horodatage et un déconnecterReason qui indique si l'appareil est connecté à AWS IoT Core. L’appareil "mything1" déconnecté (false) à l'heure POSIX 1556649874716 à cause de CONNECTION_LOST. Pour plus d’informations sur les motifs de déconnexion, consultez Événements du cycle de vie. 

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

L'appareil "mything2" connecté (true) à l'heure POSIX 1556649855046 :

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

Les horodatages sont indiqués en millisecondes depuis l'époque Unix, donc 1556649855046 représente 6:44:15.046 PM le mardi 30 avril 2019 (UTC).

Important

Si un appareil a été déconnecté pendant environ une heure, la valeur "timestamp" et la valeur "disconnectReason" de l'état de connectivité peuvent être manquantes.

Restrictions et limitations

Les restrictions et limitations pour AWS_Things sont les suivantes.

Champs Shadow de types complexes

Un champ shadow est indexé uniquement si la valeur du champ est un type simple, tel qu’un objet JSON qui ne contient pas de tableau ou un tableau qui se compose entièrement de types simples. (Un type simple représente une chaîne, un nombre ou un des littéraux true ou false.) Par exemple, étant donné l'état du shadow suivant, la valeur du champ "palette" n’est pas indexée, car il s'agit d'un tableau dont les éléments ont des types complexes. La valeur du champ "colors" est indexée, car chaque valeur du tableau est une chaîne. 

{
    "state": {
        "reported": {
            "switched": "ON",
            "colors": [ "RED", "GREEN", "BLUE" ],
            "palette": [
                {
                    "name": "RED", 
                    "intensity": 124
                },
                {
                    "name": "GREEN", 
                    "intensity": 68
                },
                {
                    "name": "BLUE", 
                    "intensity": 201
                }
            ]
        }
    }
}
Noms de champs shadow imbriqués

Les noms des champs shadow imbriqués sont stockés sous la forme d'une chaîne délimitée par un point (.). Par exemple, soit un document shadow :

{
  "state": {
    "desired": {
      "one": {
        "two": {
          "three": "v2"
        }
      }
    }    
  }
}

Le nom du champ three est stocké sous la forme desired.one.two.three. Si vous disposez également d'un document shadow, il est stocké comme ceci :

{
  "state": {
    "desired": {
      "one.two.three": "v2"
    }    
  }
}

Ils correspondent tous deux à une requête pour shadow.desired.one.two.three:v2. Conformément aux bonnes pratiques, n'utilisez pas de points dans les noms de champs shadow.

Métadonnées de shadow

Un champ d'une section de métadonnées de shadow est indexé, à l'unique condition que le champ correspondant dans la section "state" du shadow soit indexé. (Dans l'exemple précédent, le champ "palette" de la section des métadonnées du shadow n’est pas indexé non plus.)

Appareils non enregistrés

L'indexation de flotte indexe l'état de connectivité d'un appareil dont la connexion clientId est identique à celle thingName d'un objet enregistré dans le registre .

Shadows non enregistrés

Si vous utilisez UpdateThingShadow pour créer une ombre en utilisant un nom d'objet qui n'a pas été enregistré dans votre AWS IoT compte, les champs de cette ombre ne sont pas indexés. Cela s'applique à la fois à la shadow classique anonyme et nommée.

Valeur numériques

Si des données de registre ou de shadow sont reconnues par le service en tant que valeurs numériques, elles sont indexées en tant que telles. Vous pouvez formuler des requêtes comportant des plages et des opérateurs de comparaison sur les valeurs numériques (par exemple, "attribute.foo<5" ou "shadow.reported.foo:[75 TO 80]"). Pour être reconnue comme numérique, la valeur des données doit être un numéro JSON valide et littéral. La valeur peut être un entier compris entre -2 ^ 53...2 ^ 53-1, une virgule flottante double précision avec une notation exponentielle facultative ou une partie d'un tableau contenant uniquement ces valeurs.

Valeurs nulles

Les valeurs nulles ne sont pas indexées.

Valeurs maximales

Le nombre maximal de champs personnalisés pour les requêtes d'agrégation est 5.

Le nombre maximal de centiles demandés pour les requêtes d'agrégation est 100.

Autorisation

Vous pouvez spécifier l'index des objets sous la forme d'un Amazon Resource Name (ARN) dans le cadre d'une action AWS IoT politique, comme suit.

Action Ressource

iot:SearchIndex

Un ARN d'index (par exemple, arn:aws:iot:your-aws-regionyour-aws-account:index/AWS_Things).

iot:DescribeIndex

Un ARN d'index (par exemple, arn:aws:iot:your-aws-region:index/AWS_Things).
Note

Si vous disposez d'autorisations pour interroger l'index de la flotte, vous pouvez accéder aux données d'objets dans la totalité de la flotte.