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, dati di AWS IoT Device Shadow , dati di connettività di AWS IoT, e dati di violazioni di AWS IoT Device Defender.
In questo argomento:
Abilitazione dell'indicizzazione degli oggetti
Si utilizza il comando CLI update-indexing-configuration o UpdateIndexingl'operazione Configuration API per creare AWS_Things l'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. QuandothingIndexingModeè impostato su beOFF, 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, impostanamedShadowIndexingModein modo che siaONe specifica i nomi delle copie shadow denominate infilter.
La tabella seguente mostra i valori validi per ogni modalità di indicizzazione e l'origine dati indicizzata per ogni valore.
| Attributo | Valori validi | Registro | Shadow | Connettività | Violazioni DD | Copia shadow con nome |
|---|---|---|---|---|---|---|
thingIndexingMode |
OFF | |||||
| REGISTRY | ✓ | |||||
| REGISTRY_AND_SHADOW | ✓ | ✓ | ||||
thingConnectivityIndexingMode |
Non specificato. | |||||
| OFF | ||||||
| STATUS | ✓ | |||||
deviceDefenderIndexingMode |
Non specificato. | |||||
| OFF | ||||||
| VIOLAZIONI | ✓ | |||||
namedShadowIndexingMode |
Non specificato. | |||||
| OFF | ||||||
| ATTIVATO | ✓ |
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. Puoi utilizzare il comando CLI update-indexing-configuration per creare o aggiornare i campi personalizzati. Vedi un esempio di comando in Updating indexing configuration examples (Esempi di aggiornamento della configurazione di aggiornamento). Per ulteriori informazioni, consulta Custom fields (Personalizza campi).
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_AND_SHADOW e specifica
thingIndexingModei dati di geolocalizzazione nel filtro.geoLocationsIl 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,
namedShadowIndexingModeimpostatela su ON, aggiungete il nome dell'ombra nel filtro e specificate i dati di geolocalizzazione nelnamedShadowNamesfiltro.geoLocationsIl 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 IndexingFilterReference 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).
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 | Descrizione |
|---|---|
| OFF | Nessuna origine dati è configurata o indicizzata. |
| REGISTRY | I dati di registro sono indicizzati. |
| REGISTRY_AND_SHADOW | I dati di registro e i dati shadow (classici) con nome sono indicizzati. |
| REGISTRY_AND_CONNETTIVITY | I dati di registro e i dati di connettività sono indicizzati. |
| REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS | I dati del registro, i dati shadow senza nome (classici) e i dati di connettività sono indicizzati. |
| MULTI_INDEXING_MODE | 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.
"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
trueofalse. 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
threeviene archiviato comedesired.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 althingNamedi un oggetto registrato nel Registro. - Copie shadow non registrate
-
Se usi UpdateThingShadow per creare 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 |
|---|---|
|
|
Un indice ARN (ad esempio, |
|
|
Un indice ARN (ad esempio, |
Nota
Se si dispone di autorizzazioni per eseguire query all'indice del parco istanze, è possibile accedere ai dati degli oggetti sull'intero parco istanze.
