Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Gestione dell'indicizzazione degli oggetti L'indice creato per tutti i tuoi oggetti è `AWS_Things`. È possibile controllare cosa indicizzare dalle seguenti origini dati: dati di [registro di AWS IoT](thing-registry.md), dati di [AWS IoT Device Shadow ](iot-device-shadows.md), dati di [connettività di AWS IoT](life-cycle-events.md), e dati di violazioni di [AWS IoT Device Defender](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/what-is-device-defender.html). **Topics** + [ ## Abilitazione dell'indicizzazione degli oggetti ](#enable-index) + [ ## Descrizione di un indice dell'oggetto ](#describe-index) + [ ## Esecuzione di query su un indice di oggetti ](#search-index) + [ ## Restrizioni e limitazioni ](#index-limitations) + [ ## Autorizzazione ](#query-auth) ## Abilitazione dell'indicizzazione degli oggetti Si utilizza il comando [update-indexing-configuration](https://docs.aws.amazon.com/cli/latest/reference/iot/update-indexing-configuration.html)CLI o l'operazione [UpdateIndexingConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateIndexingConfiguration.html)API per creare l'`AWS_Things`indice e controllarne la configurazione. Il parametro `--thing-indexing-configuration` (`thingIndexingConfiguration`) consente di controllare il tipo di dati indicizzati (ad esempio, registro, copia shadow, dati di connettività del dispositivo e dati di violazioni di Device Defender). Il parametro `--thing-indexing-configuration` accetta una stringa con la seguente struttura: ``` { "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" } ] } } ``` ### Modalità di indicizzazione delle cose È possibile specificare diverse modalità di indicizzazione degli oggetti nella configurazione di indicizzazione, a seconda delle fonti di dati da cui si desidera indicizzare e cercare i dispositivi: + `thingIndexingMode`: controlla se il registro o l'ombra sono indicizzati. Quando `thingIndexingMode` è impostato su be`OFF`, l'indicizzazione degli oggetti è disabilitata. + `thingConnectivityIndexingMode`: specifica se i dati di connettività dell'oggetto sono indicizzati. + `deviceDefenderIndexingMode`: specifica se i dati delle violazioni di Device Defender sono indicizzati. + `namedShadowIndexingMode`: specifica se i dati shadow denominati sono indicizzati. Per selezionare le copie shadow denominate da aggiungere alla configurazione di indicizzazione del parco istanze, imposta `namedShadowIndexingMode` in modo che sia `ON` e specifica i nomi delle copie shadow denominate in [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html). La tabella seguente mostra i valori validi per ogni modalità di indicizzazione e l'origine dati indicizzata per ogni valore. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/iot/latest/developerguide/managing-index.html) ### Campi gestiti e campi personalizzati **Campi gestiti** I campi gestiti contengono dati associati a oggetti, gruppi di oggetti, ombre dei dispositivi, connettività dei dispositivi e violazioni di Device Defender. AWS IoT definisce il tipo di dati nei campi gestiti. Specifica i valori di ogni campo gestito quando crei un oggetto  AWS IoT . Ad esempio i nomi degli oggetti, i gruppi di oggetti e le descrizioni degli oggetti sono tutti campi gestiti. L'indicizzazione del parco istanze indica i campi gestiti in base alla modalità di indicizzazione che specifici. I campi gestiti non possono essere modificati o visualizzati in `customFields`. **Campi personalizzati** È possibile aggregare gli attributi, i dati di Device Shadow e i dati delle violazioni di Device Defender creando campi personalizzati per indicizzarli. L'attributo `customFields` è un elenco di coppie di nomi di campi e tipi di dati. È possibile eseguire query di aggregazione in base al tipo di dati. La modalità di indicizzazione che scegli influenza i campi che è possibile specificare in `customFields`. Ad esempio, se si specifica la modalità di indicizzazione `REGISTRY`, non è possibile specificare un campo personalizzato da una copia shadow dell'oggetto. È possibile utilizzare il comando [update-indexing-configuration](https://docs.aws.amazon.com/cli/latest/reference/iot/update-indexing-configuration.html)CLI per creare o aggiornare i campi personalizzati (vedere un comando di esempio in [Aggiornamento degli esempi di configurazione dell'indicizzazione](#update-index-examples)). Per ulteriori informazioni, consulta [Custom fields (Personalizza campi)](managing-fleet-index.md#custom-field). ### Filtro di indicizzazione Il filtro di indicizzazione fornisce selezioni aggiuntive per ombre denominate e dati di geolocalizzazione. **`namedShadowNames`** Per aggiungere ombre denominate alla configurazione di indicizzazione della flotta, impostate be e specificate i nomi delle ombre denominate `namedShadowIndexingMode` `ON` nel filtro. `namedShadowNames` **Esempio** ``` "filter": { "namedShadowNames": [ "namedShadow1", "namedShadow2" ] } ``` `geoLocations` Per aggiungere dati di geolocalizzazione alla configurazione di indicizzazione della flotta: + Se i dati di geolocalizzazione sono archiviati in un'ombra classica (senza nome), impostala su REGISTRY\$1AND\$1SHADOW e specifica `thingIndexingMode` i dati di geolocalizzazione nel filtro. `geoLocations` Il filtro di esempio seguente specifica un oggetto GeoLocation in un'ombra classica (senza nome): ``` "filter": { "geoLocations": [ { "name": "shadow.reported.location", "order": "LonLat" } ] } ``` + Se i dati di geolocalizzazione sono archiviati in un'ombra denominata, `namedShadowIndexingMode` impostatela su ON, aggiungete il nome dell'ombra nel filtro e specificate i dati di geolocalizzazione nel `namedShadowNames` filtro. `geoLocations` Il filtro di esempio riportato di seguito specifica un oggetto GeoLocation in un'ombra denominata (): `nameShadow1` ``` "filter": { "namedShadowNames": [ "namedShadow1" ], "geoLocations": [ { "name": "shadow.name.namedShadow1.reported.location", "order": "LonLat" } ] } ``` *Per ulteriori informazioni, consulta API [ IndexingFilter](https://docs.aws.amazon.com/iot/latest/apireference/API_IndexingFilter.html)Reference *AWS IoT*.* ### Aggiornamento degli esempi di configurazione di indicizzazione Per aggiornare la configurazione di indicizzazione, usa il comando CLI AWS IoT **update-indexing-configuration**. Gli esempi seguenti mostrano come utilizzare **update-indexing-configuration**. Sintassi breve: ``` 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}]' ``` Sintassi 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} ] } }' ``` Il comando non produce output. Per controllare lo stato dell'indice degli oggetti, esegui il comando CLI `describe-index`: ``` aws iot describe-index --index-name "AWS_Things" ``` L'output del comando `describe-index` è simile al seguente: ``` { "indexName": "AWS_Things", "indexStatus": "ACTIVE", "schema": "MULTI_INDEXING_MODE" } ``` **Nota** L'indicizzazione del parco istanze può richiedere un momento per aggiornare l'indice del parco istanze. Consigliamo di attendere fino al momento in cui `indexStatus` mostra ACTIVE prima di utilizzarlo. È possibile avere valori diversi nel campo dello schema a seconda delle origini dati configurate. Per ulteriori informazioni, consulta [Describing a thing index (Descrizione di un indice dell'oggetto)](#describe-index). Per ottenere i dettagli di configurazione dell'indicizzazione delle cose, esegui il comando CLI `get-indexing-configuration`: ``` aws iot get-indexing-configuration ``` L'output del comando `get-indexing-configuration` è simile al seguente: ``` { "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" } } ``` Per aggiornare i campi personalizzati, esegui il comando `update-indexing-configuration`. Di seguito è riportato l'esempio: ``` 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}]' ``` Questo comando ha aggiunto `shadow.desired.intensity` alla configurazione di indicizzazione. **Nota** L'aggiornamento della configurazione di indicizzazione dei campi personalizzati sovrascrive tutti i campi personalizzati esistenti. Assicurarsi di specificare tutti i campi personalizzati durante la chiamata a **update-indexing-configuration**. Dopo che l'indice è stato ricostruito è possibile utilizzare query di aggregazione sui campi appena aggiunti, ricercare dati del registro, dati shadow e dati di stato connettività dell'oggetto. Quando si modifica la modalità di indicizzazione, assicurarsi che tutti i campi personalizzati siano validi utilizzando la nuova modalità di indicizzazione. Ad esempio, se si inizia con la modalità `REGISTRY_AND_SHADOW` con un campo personalizzato chiamato `shadow.desired.temperature`, è necessario eliminare il campo personalizzato `shadow.desired.temperature` prima di cambiare la modalità di indicizzazione in `REGISTRY`. Se la configurazione di indicizzazione contiene campi personalizzati che non sono indicizzati dalla modalità di indicizzazione, l'aggiornamento non riesce. ## Descrizione di un indice dell'oggetto Il comando seguente mostra come usare il comando dell'interfaccia a riga di comando **describe-index** per recuperare lo stato corrente dell'indice degli oggetti. ``` aws iot describe-index --index-name "AWS_Things" ``` L'output del comando è simile al seguente: ``` { "indexName": "AWS_Things", "indexStatus": "BUILDING", "schema": "REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS" } ``` La prima volta che esegui l'indicizzazione della flotta, crea il tuo indice. AWS IoT Non puoi eseguire query sull'indice se `indexStatus` è nello stato `BUILDING`. `schema` per l'indice degli oggetti indica quale tipo di dati (`REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS`) sarà indicizzato. La modifica della configurazione dell'indice comporta la ricostruzione dell'indice. Durante questo processo, `indexStatus` è `REBUILDING`. È possibile eseguire query sui dati nell'indice degli oggetti, mentre è in fase di ricostruzione. Ad esempio, se modifichi la configurazione dell'indice da `REGISTRY` a `REGISTRY_AND_SHADOW` mentre l'indice è in fase di ricompilazione, puoi eseguire query sui dati del registro, inclusi gli aggiornamenti più recenti. Tuttavia, non puoi eseguire query sui dati shadow fino al completamento della ricompilazione. L'intervallo di tempo necessario per creare o ricostruire l'indice dipende dalla quantità di dati. È possibile visualizzare valori diversi nel campo dello schema a seconda delle origini dati che hai configurato. La tabella seguente mostra i diversi valori dello schema e le descrizioni corrispondenti: | Schema | Description | | --- | --- | | OFF | Nessuna origine dati è configurata o indicizzata. | | REGISTRY | I dati di registro sono indicizzati. | | REGISTRY\$1AND\$1SHADOW | I dati di registro e i dati shadow (classici) con nome sono indicizzati. | | REGISTRY\$1AND\$1CONNETTIVITY | I dati di registro e i dati di connettività sono indicizzati. | | REGISTRY\$1AND\$1SHADOW\$1AND\$1CONNECTIVITY\$1STATUS | I dati del registro, i dati shadow senza nome (classici) e i dati di connettività sono indicizzati. | | MULTI\$1INDEXING\$1MODE | I dati delle copie shadow con nome o delle violazioni di Device Defender vengono indicizzati, oltre ai dati del registro, delle copie shadow (classiche) senza nome o della connettività. | ## Esecuzione di query su un indice di oggetti Utilizzare il comando dell'interfaccia a riga di comando **search-index** per eseguire query dei dati nell'indice. ``` 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" } ``` Nella risposta JSON, `"connectivity"`, abilitata dall'impostazione `thingConnectivityIndexingMode=STATUS`, fornisce un valore booleano, un timestamp e un disconnectReason che indica se il dispositivo è collegato ad AWS IoT Core. Il dispositivo `"mything1"` scollegato (`false`) a POSIX time `1556649874716` a causa di `CONNECTION_LOST`. Per ulteriori informazioni sui motivi di disconnessione, consulta [Eventi del ciclo di vita](life-cycle-events.md). ``` "connectivity": { "connected":false, "timestamp":1556649874716, "disconnectReason": "CONNECTION_LOST" } ``` Il dispositivo `"mything2"` connesso (`true`) a POSIX time `1556649855046`: ``` "connectivity": { "connected":true, "timestamp":1556649855046 } ``` I timestamp vengono forniti in millisecondi dall'epoca, perciò `1556649855046` rappresenta 6:44:15.046 PM di martedì 30 aprile 2019 (GMT). **Importante** Se un dispositivo è stato disconnesso per circa un'ora, il valore `"timestamp"` e il valore `"disconnectReason"` dello stato di connettività potrebbe mancare. ## Restrizioni e limitazioni Queste sono le limitazioni e le restrizioni per `AWS_Things`. **Campi della copia shadow con valori di tipo complesso** Un campo della copia shadow viene indicizzato solo se il relativo valore è un tipo semplice, come un oggetto JSON che non contiene una matrice o una matrice composta interamente da tipi semplici. Per tipo semplice si intende una stringa, un numero o un valore letterale `true` o `false`. Ad esempio, per il seguente stato shadow, il valore del campo `"palette"` non viene indicizzato perché è una matrice che contiene elementi di tipo complesso. Il valore del campo `"colors"` viene indicizzato perché ogni valore della matrice è una stringa. ``` { "state": { "reported": { "switched": "ON", "colors": [ "RED", "GREEN", "BLUE" ], "palette": [ { "name": "RED", "intensity": 124 }, { "name": "GREEN", "intensity": 68 }, { "name": "BLUE", "intensity": 201 } ] } } } ``` **Nomi di campi della copia shadow nidificati** I nomi dei campi della copia shadow nidificati vengono archiviati come stringa delimitata da punto (.). Ad esempio, dato un documento shadow: ``` { "state": { "desired": { "one": { "two": { "three": "v2" } } } } } ``` Il nome del campo `three` viene archiviato come `desired.one.two.three`. Se sei in possesso di un documento shadow, è archiviato in questo modo: ``` { "state": { "desired": { "one.two.three": "v2" } } } ``` Entrambi corrispondono a una query per `shadow.desired.one.two.three:v2`. Come best practice, non utilizzare punti nei nomi dei campi shadow. **Metadati delle copie shadow** Un campo nella sezione metadati delle copie shadow viene indicizzato, ma solo se lo è anche il campo corrispondente nella sezione `"state"` della copia shadow. (Nell'esempio precedente, neanche il campo `"palette"` nella sezione dei metadati delle copie shadow verrà indicizzato.) **Dispositivi non registrati** L'indicizzazione del parco istanze consente di indicizzare lo stato di connettività di un dispositivo la cui connessione `clientId` è identica al `thingName` di un oggetto registrato nel [Registro](https://docs.aws.amazon.com//iot/latest/developerguide/thing-registry.html). **Copie shadow non registrate** Se [UpdateThingShadow](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html)crei un'ombra utilizzando il nome di un oggetto che non è stato registrato nel tuo AWS IoT account, i campi in questa ombra non vengono indicizzati. Questo vale sia per la classica shadow senza nome che per shadow con nome. **Valori numerici** Se eventuali dati del registro o dati shadow vengono riconosciuti dal servizio come valori numerici, verranno indicizzati come tali. Puoi formulare delle query che includono intervalli e operatori di confronto in merito ai valori numerici, ad esempio `"attribute.foo<5"` o `"shadow.reported.foo:[75 TO 80]"`. Per essere riconosciuto come numerico, il valore dei dati deve essere un numero JSON di tipo letterale valido. Il valore può essere un numero intero compreso nell'intervallo -2^53...2^53-1 o in virgola mobile a precisione doppia con notazione esponenziale opzionale, oppure una parte di una serie contenente solo questi valori. **Valori nulli** I valori nulli non sono indicizzati. **Valori massimi** Il numero massimo di campi personalizzati per le query di aggregazione è 5. Il numero massimo di percentili richiesti per le query di aggregazione è 100. ## Autorizzazione Puoi specificare l'indice degli oggetti come Amazon Resource Name (ARN) in un'azione AWS IoT politica, come segue. **** | Azione | Risorsa | | --- | --- | | `iot:SearchIndex` | Un indice ARN (ad esempio, `arn:aws:iot:your-aws-regionyour-aws-account:index/AWS_Things`). | | `iot:DescribeIndex` | Un indice ARN (ad esempio, `arn:aws:iot:your-aws-region:index/AWS_Things`). | **Nota** Se si dispone di autorizzazioni per eseguire query all'indice del parco istanze, è possibile accedere ai dati degli oggetti sull'intero parco istanze.