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.

Abilitazione dell'indicizzazione degli oggetti

È possibile utilizzare il update-indexing-configurationCLIcomando o l'UpdateIndexingConfigurationAPIoperazione per creare l'AWS_Thingsindice 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 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, imposta namedShadowIndexingMode in modo che sia ON e specifica i nomi delle copie shadow denominate in filter.

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
	VIOLATIONS				✓
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. È possibile utilizzare il update-indexing-configurationCLIcomando per creare o aggiornare i campi personalizzati (vedere un esempio di comando in Aggiornamento degli esempi di configurazione dell'indicizzazione). 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), impostali su REGISTRY _ AND _ e specifica thingIndexingMode i dati di geolocalizzazione nel SHADOW filtro. geoLocations

  Il filtro di esempio riportato di seguito specifica un geoLocation oggetto 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 namedShadowNames filtro e specificate i dati di geolocalizzazione nel filtro. geoLocations

  Il filtro di esempio riportato di seguito specifica un geoLocation oggetto in un'ombra denominata (): nameShadow1

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

Per ulteriori informazioni, vedere IndexingFilterda AWS IoT APIReference.

Aggiornamento degli esempi di configurazione di indicizzazione

Per aggiornare la configurazione di indicizzazione, usa il AWS IoT update-indexing-configuration CLI comando. 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}]'

JSONsintassi:

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 dell'oggetto, esegui il describe-index CLI comando:

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 gli indexStatus spettacoli 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 di Thing, esegui il get-indexing-configuration CLI comando:

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 utilizzare il describe-index CLI comando per recuperare lo stato corrente dell'indice dell'oggetto.

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 del parco veicoli, AWS IoT crea il tuo indice. 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_CONNECTIVITY	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

Usa il search-index CLI comando per interrogare i 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 JSON risposta, "connectivity" (come abilitato dall'thingConnectivityIndexingMode=STATUSimpostazione) fornisce un valore booleano, un timestamp e un disconnectReason che indica se il dispositivo è connesso a. AWS IoT Core Il dispositivo si è "mything1" disconnesso (false) al momento a causa di. POSIX 1556649874716 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) al POSIX momento1556649855046:

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

I timestamp sono espressi in millisecondi dall'epoca, quindi 1556649855046 rappresentano le 18:44:15.046 di martedì 30 aprile 2019 (). UTC

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 ombra viene indicizzato solo se il valore del campo è di tipo semplice, ad esempio un JSON oggetto che non contiene un array o un array composto 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.

Copie shadow non registrate

Se si utilizza UpdateThingShadowper creare un'ombra utilizzando il nome di un oggetto che non è stato registrato nel AWS IoT proprio 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 riconosciuti come numerici, il valore dei dati deve essere un numero di tipo letterale valido. JSON 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.