Administración de la indexación de objetos - AWS IoT Core
Habilitación de la indexación de objetosDescripción de un índice de objetoConsulta de un índice de objetoRestricciones y limitacionesAutorización

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Administración de la indexación de objetos

El índice creado para todos sus objetos es AWS_Things. Puede controlar qué indexar de los siguientes orígenes de datos: datos de registro de AWS IoT, datos de AWS IoT Device Shadow, datos de conectividad de AWS IoT y datos de infracciones de AWS IoT Device Defender.

Habilitación de la indexación de objetos

Utilice el comando CLI update-indexing-configuration o UpdateIndexingla operación de la API de configuración para crear AWS_Things el índice y controlar su configuración. Utilizando el parámetro --thing-indexing-configuration (thingIndexingConfiguration), controla qué tipo de datos se indexan (por ejemplo, registro, sombra, datos de conectividad del dispositivo y datos de infracciones de Device Defender).

El parámetro --thing-indexing-configuration toma una cadena con la siguiente estructura:

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

Modos de indexación de cosas

Puede especificar distintos modos de indexación en la configuración de indexación, en función de las fuentes de datos que desee indexar y de los dispositivos de búsqueda desde los que desee realizar la búsqueda:

  • thingIndexingMode: Controla si el registro o la sombra están indexados. Cuando thingIndexingMode se establece como talOFF, la indexación de objetos está deshabilitada.

  • thingConnectivityIndexingMode: Especifica si los datos de conectividad del objeto están indexados.

  • deviceDefenderIndexingMode: Especifica si los datos de infracciones de Device Defender están indexados.

  • namedShadowIndexingMode: Especifica si los datos ocultos con nombre están indexados. Para seleccionar sombras con nombre y agregarlas a la configuración de indexación de su flota, establezca namedShadowIndexingMode en ON y especifique los nombres de las sombras con nombre en filter.

La siguiente tabla muestra los valores válidos para cada modo de indexación y la fuente de datos que está indexada para cada valor.

Atributo Valores válidos Registro Sombra Conectividad Infracciones de DD Sombra con nombre
thingIndexingMode OFF
REGISTRY ✓
REGISTRY_AND_SHADOW ✓ ✓
thingConnectivityIndexingMode No especificado.
OFF
STATUS ✓
deviceDefenderIndexingMode No especificado.
OFF
VIOLATIONS ✓
namedShadowIndexingMode No especificado.
OFF
ON ✓

Campos administrados y campos personalizados

Campos administrados

Los campos gestionados contienen datos asociados a cosas, grupos de cosas, dispositivos ocultos, conectividad de los dispositivos e infracciones de Device Defender. AWS IoT define el tipo de datos en los campos gestionados. El usuario especifica los valores de cada campo administrado cuando se crea un objeto de AWS IoT . Por ejemplo, los nombres de objetos, los grupos de objetos y las descripciones de objetos son todos campos administrados. La indexación de flotas indexa los campos administrados en función del modo de indexación que usted especifique. Los campos administrados no se pueden cambiar ni pueden aparecer en customFields.

Campos personalizados

Puede agregar atributos, datos de Device Shadow y datos de infracciones de Device Defender creando campos personalizados para indexarlos. El atributo customFields es una lista de pares de campos y tipos de datos con nombre. Puede realizar consultas de agregación en función del tipo de datos. El modo de indexación que elija afecta a los campos se puede especificar en customFields. Por ejemplo, si especifica el modo de indexación REGISTRY, no puede especificar un campo personalizado de una sombra de objeto. Puede usar el comando de la CLI update-indexing-configuration para crear o actualizar los campos personalizados (consulte un comando de ejemplo en Actualización de ejemplos de configuración de indexación). Para obtener más información, consulte Campos personalizados.

Filtro de indexación

El filtro de indexación proporciona selecciones adicionales para las sombras con nombre y los datos de geolocalización.

namedShadowNames

Para añadir sombras con nombre a la configuración de indexación de su flota, configúrelo como ON y especifique namedShadowIndexingMode los nombres de las sombras con nombre en el filtro. namedShadowNames

Ejemplo

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

geoLocations

Para añadir datos de geolocalización a la configuración de indexación de su flota:

  • Si sus datos de geolocalización se almacenan en una sombra clásica (sin nombre), establézcala como REGISTRY_AND_SHADOW y especifique thingIndexingMode los datos de geolocalización en el filtro. geoLocations

    El siguiente filtro de ejemplo especifica un objeto de GeoLocation en una sombra clásica (sin nombre):

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

  • Si los datos de geolocalización están almacenados en una sombra con nombre, configúrela en namedShadowIndexingMode ACTIVADA, añada el nombre de la sombra en el namedShadowNames filtro y especifique los datos de geolocalización en el filtro. geoLocations

    El siguiente filtro de ejemplo especifica un objeto de geolocalización en una sombra con nombre (): nameShadow1

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

Para obtener más información, consulte la referencia IndexingFilterde la AWS IoTAPI.

Actualización de ejemplos de configuración de indexación

Para actualizar la configuración de indexación, utilice el comando AWS IoT update-indexing-configuration CLI. En los siguientes ejemplos se muestra cómo utilizar update-indexing-configuration.

Sintaxis corta:

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

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

Este comando no proporciona ninguna salida.

Para comprobar el estado del índice del objeto, ejecute el comando de la CLI describe-index: 

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

El resultado del comando describe-index tendrá un aspecto similar al siguiente:

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

La indexación de la flota puede tardar un momento en actualizar el índice de la flota. Recomendamos esperar a que indexStatus aparezca activo antes de usarla. Puede tener valores diferentes en el campo de esquema en función de los orígenes de datos que haya configurado. Para obtener más información, consulte Descripción de un índice de objeto.

Para obtener los detalles de la configuración de indexación, ejecute el comando de la CLI get-indexing-configuration: 

aws iot get-indexing-configuration

El resultado del comando get-indexing-configuration tendrá un aspecto similar al siguiente:

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

Para actualizar los campos personalizados, puede ejecutar el comando update-indexing-configuration. A continuación tiene un ejemplo:

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

Este comando se agregó shadow.desired.intensity a la configuración de indexación.

nota

La actualización de los campos personalizados en la configuración de indexación sobrescribe todos los campos personalizados existentes. Asegúrese de especificar todos los campos personalizados cuando llame a update-indexing-configuration.

Después de reconstruir el índice, puede utilizar una consulta de agregación en los campos recién agregados, los datos de registro de búsqueda, los datos de sombras y los datos de estado de conectividad de objetos.

Al cambiar el modo de indexación, asegúrese de que todos los campos personalizados son válidos en el nuevo modo de indexación. Por ejemplo, si utiliza el modo REGISTRY_AND_SHADOW con un campo personalizado llamado shadow.desired.temperature, debe eliminar el campo personalizado shadow.desired.temperature antes de cambiar el modo de indexación a REGISTRY. Si la configuración de indexación contiene campos personalizados que no están indexados por el modo de indexación, se producirá un error en la actualización.

Descripción de un índice de objeto

El comando siguiente muestra cómo utilizar el comando describe-index de la CLI para recuperar el estado actual del índice del objeto:

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

La respuesta del comando tendrá un aspecto similar al siguiente:

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

La primera vez que indexa la flota, AWS IoT crea su índice. Cuando indexStatus está en el estado BUILDING, no se puede consultar el índice. El valor schema del índice de objetos indica qué tipo de datos (REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS) se indexan.

Si se cambia la configuración del índice, el índice se vuelve a compilar. Durante este proceso, indexStatus es REBUILDING. Puede ejecutar consultas en los datos del índice de objetos mientras se está generando. Por ejemplo, si cambia la configuración del índice de REGISTRY a REGISTRY_AND_SHADOW, cuando el índice se vuelve a generar, puede consultar los datos del registro, incluidas las últimas actualizaciones. Sin embargo, no puede consultar los datos de sombra hasta que se complete la recompilación. El tiempo que tarda en compilar o recompilar el índice depende de la cantidad de datos.

Puede ver diferentes valores en el campo de esquema en función de los orígenes de datos que haya configurado. En la siguiente tabla, se muestran los diferentes valores de esquema y las descripciones correspondientes:

Esquema Descripción
OFF No hay ningún origen de datos configurado ni indexado.
REGISTRY Solo se indexan los datos de registro.
REGISTRY_AND_SHADOW Se indexan los datos del registro y los datos de sombras sin nombre (clásicos).
REGISTRY_AND_CONNECTIVITY Se indexan los datos de registro y conectividad.
REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS Se indexan los datos de registro, los datos de sombras sin nombre (clásicos) y los datos de conectividad.
MULTI_INDEXING_MODE

Se indexan los datos de sombras con nombre o las infracciones de Device Defender, además de los datos de registro, de sombras sin nombre (clásicos) o de conectividad.

Consulta de un índice de objeto

Puede utilizar el comando search-index de la CLI para consultar los datos del índice.

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

En la respuesta JSON,"connectivity" (según lo permita configuración de thingConnectivityIndexingMode=STATUS) proporciona un valor booleano, una marca temporal y un parámetro disconnectReason que indica si el dispositivo está conectado a AWS IoT Core. El dispositivo "mything1" desconectado (false) en tiempo POSIX 1556649874716 debido a CONNECTION_LOST. Para obtener información sobre los motivos de desconexión, consulte Eventos del ciclo de vida. 

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

El dispositivo "mything2" conectado (true) en tiempo POSIX 1556649855046:

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

Las marcas temporales se indican en milisegundos desde la fecha de inicio, por lo que 1556649855046 representa 6:44:15.046 p.m. el martes 30 de abril de 2019 (UTC).

importante

Si un dispositivo se ha desconectado durante aproximadamente una hora, el valor "timestamp" y el valor "disconnectReason" del estado de conectividad podrían no aparecer.

Restricciones y limitaciones

Estas son las restricciones y limitaciones de AWS_Things.

Campos de sombra con tipos complejos

Un campo de sombra se indexa solo si el valor del campo es un tipo sencillo, como un objeto JSON que no incluya una matriz o una matriz que conste completamente de tipos sencillos. Un tipo sencillo es una cadena, un número o uno de los literales true o false. Por ejemplo, dado el siguiente estado de sombra, el valor del campo "palette" no se indexa porque es una matriz que incluye elementos de tipos complejos. El valor del campo "colors" sí se indexará porque cada valor de la matriz es una cadena. 

{
    "state": {
        "reported": {
            "switched": "ON",
            "colors": [ "RED", "GREEN", "BLUE" ],
            "palette": [
                {
                    "name": "RED", 
                    "intensity": 124
                },
                {
                    "name": "GREEN", 
                    "intensity": 68
                },
                {
                    "name": "BLUE", 
                    "intensity": 201
                }
            ]
        }
    }
}
Nombres de campos de sombra anidados

Los nombres de los campos de sombra anidados se almacenan como una cadena delimitada por punto (.). Por ejemplo, dado un documento de sombra:

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

El nombre del campo three se almacena como desired.one.two.three. Si también tiene un documento de sombra, se guarda del modo siguiente:

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

Ambos coinciden con una consulta para shadow.desired.one.two.three:v2. La práctica recomendada es no utilizar puntos en los nombres de campos de sombra.

Metadatos de sombra

Un campo en una sección de metadatos de sombra se indexa, pero solo si se indexa el campo correspondiente en la sección "state" de la sombra. (En el ejemplo anterior, el campo "palette" de la sección de metadatos de la sombra tampoco se indexa).

Dispositivos no registrados

La indexación de flotas indexa el estado de conectividad de un dispositivo cuya conexión clientId es la misma que la thingName de un dispositivo registrado en el Registro.

Sombras no registradas

Si utilizas UpdateThingShadow para crear una sombra con el nombre de una cosa que no esté registrado en tu AWS IoT cuenta, los campos de esta sombra no se indexarán. Esto se aplica tanto a la sombra sin nombre clásica como a la sombra con nombre.

Valores numéricos

Si el servicio reconoce como valor numérico algún dato de sombra o de registro, se indexa como tal. Puede formar consultas que impliquen rangos y operadores de comparación en valores numéricos (por ejemplo "attribute.foo<5" o "shadow.reported.foo:[75 TO 80]"). Para que se reconozca como numérico, el valor de los datos debe ser un número JSON válido y de tipo literal. El valor puede ser un entero en el rango -2^53...2^53-1, un punto flotante de doble precisión con notación exponencial opcional, o parte de una matriz que contenga solo estos valores.

Valores nulos

Los valores nulos no se indexan.

Valores máximos

El número máximo de campos personalizados para consultas de agregación es 5.

El número máximo de percentiles solicitados para consultas de agregación es 100.

Autorización

Puede especificar el índice de cosas como un nombre de recurso de Amazon (ARN) en una acción AWS IoT política, de la siguiente manera.

Acción Recurso

iot:SearchIndex

El ARN de un índice (por ejemplo, arn:aws:iot:your-aws-regionyour-aws-account:index/AWS_Things).

iot:DescribeIndex

El ARN de un índice (por ejemplo, arn:aws:iot:your-aws-region:index/AWS_Things).
nota

Si tiene los permisos para consultar el índice de la flota, podrá obtener acceso a los datos de los objetos en toda la flota.