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](thing-registry.md), données [AWS IoT Device Shadow](iot-device-shadows.md), données de [AWS IoT connectivité](life-cycle-events.md) et données de [AWS IoT Device Defender](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/what-is-device-defender.html)violations. **Topics** + [Activation de l'indexation d'objet](#enable-index) + [Description d'un index d'objets](#describe-index) + [Interrogation d'un index d'objets](#search-index) + [Restrictions et limitations](#index-limitations) + [Autorisation](#query-auth) ## Activation de l'indexation d'objet Vous utilisez la commande [update-indexing-configuration](https://docs.aws.amazon.com/cli/latest/reference/iot/update-indexing-configuration.html)CLI ou l'opération [UpdateIndexingConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateIndexingConfiguration.html)API pour créer l'`AWS_Things`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 [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html). Le tableau ci-dessous indique les valeurs valides pour chaque mode d'indexation et la source de données indexée pour chaque valeur. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/iot/latest/developerguide/managing-index.html) ### 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 [update-indexing-configuration](https://docs.aws.amazon.com/cli/latest/reference/iot/update-indexing-configuration.html)CLI 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](#update-index-examples)). Pour plus d’informations, consultez [Champs personnalisés](managing-fleet-index.md#custom-field). ### 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\$1AND\$1SHADOW 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 [ IndexingFilter](https://docs.aws.amazon.com/iot/latest/apireference/API_IndexingFilter.html)Guide de *référence des *AWS IoT*API*. ### 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](#describe-index). 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\$1AND\$1SHADOW | Les données du registre et les données shadow sans nom (classiques) sont indexées. | | REGISTRY\$1ET\$1CONNECTIVITÉ\$1 | Les données de registre et les données de connectivité sont indexées. | | REGISTRY\$1AND\$1SHADOW\$1AND\$1CONNECTIVITY\$1STATUS REGISTRY\$1AND\$1CONNECTIVITY\$1STATUS | Les données de registre, les données shadow sans nom (classiques) et les données de connectivité sont indexées. | | MULTI\$1INDEXING\$1MODE | 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](life-cycle-events.md). ``` "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 ](https://docs.aws.amazon.com//iot/latest/developerguide/thing-registry.html). **Shadows non enregistrés** Si vous créez 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. [UpdateThingShadow](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html) 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.