Gerenciar a indexação de objetos

O índice criado para todas as suas objetos é AWS_Things. É possível controlar o que indexar a partir das seguintes fontes de dados: dados de registro do AWS IoT, dados da sombra do dispositivo do AWS IoT, dados de conectividade do AWS IoT e dados de violações do AWS IoT Device Defender.

Habilitar a indexação de objetos

Use o comando update-indexing-configuration da CLI ou a operação de API UpdateIndexingConfiguration para criar o índice AWS_Things e controlar sua configuração. Ao usar o parâmetro --thing-indexing-configuration (thingIndexingConfiguration), você controla o tipo de dados (por exemplo, dados de registro, sombra, conectividade do dispositivo e violações do Device Defender) que é indexado.

O parâmetro --thing-indexing-configuration leva uma string com a seguinte estrutura:

{
  "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 indexação de objetos

Você pode especificar diferentes modos de indexação em sua configuração de indexação, dependendo de quais fontes de dados você quer indexar e nas quais deseja pesquisar dispositivos:

A tabela abaixo mostra os valores válidos para cada modo de indexação e a fonte de dados indexada para cada valor.

Campos gerenciados e campos personalizados

Campos gerenciados

Os campos gerenciados contêm dados associados com objetos, grupos de objetos, sombras de dispositivos, conectividade de dispositivos e violações do Device Defender. O AWS IoT define o tipo de dado de campos gerenciados. Você especifica os valores de cada campo gerenciado ao criar um objeto do AWS IoT. Por exemplo, nomes de objetos, grupos de objetos e descrições de objetos são todos os campos gerenciados. A indexação de frotas indexa campos gerenciados com base no modo de indexação especificado por você. Os campos gerenciados não podem ser alterados e não aparecem em customFields.

Campos personalizados

Você pode agregar atributos, dados de sombra do dispositivo e dados de violações do Device Defender criando campos personalizados para indexá-los. O atributo customFields é uma lista de pares de nomes de campos e tipos de dados. É possível realizar consultas de agregação com base no tipo de dados. O modo de indexação selecionado afeta os campos que podem ser especificados em customFields. Por exemplo, ao especificar o modo de indexação REGISTRY, não será possível especificar um campo personalizado de uma sombra de um objeto. Você pode usar o comando update-indexing-configuration da CLI para criar ou atualizar os campos personalizados (consulte um exemplo de comando em Atualização de exemplos de configuração de indexação). Para acessar mais informações, consulte Campos personalizados.

Filtro de indexação

O filtro de indexação fornece seleções adicionais para sombras nomeadas e dados de localização geográfica.

namedShadowNames

Para adicionar sombras nomeadas à sua configuração de indexação de frotas, defina namedShadowIndexingMode como ON e especifique os nomes de sombras nomeadas no filtro namedShadowNames.

Exemplo

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

geoLocations

Para adicionar dados de localização geográfica à sua configuração de indexação de frota:

Para obter mais informações, consulte IndexingFilter na Referência de APIs de AWS IoT.

Atualizar exemplos de configuração de indexação

Para atualizar a configuração de indexação, use o comando da CLI AWS IoT update-indexing-configuration. O exemplo a seguir mostra como usar update-indexing-configuration.

Sintaxe curta:

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

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

Esse comando não retorna nenhuma saída.

Para verificar o status do índice do objeto, execute o comando describe-index da CLI:

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

A saída do comando describe-index é semelhante a:

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

Para obter seus detalhes de configuração de indexação de objetos, execute o comando get-indexing-configuration da CLI:

aws iot get-indexing-configuration

A saída do comando get-indexing-configuration é semelhante a:

{
    "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 atualizar os campos personalizados, execute o comando update-indexing-configuration. Um exemplo é este:

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

Esse comando adicionou shadow.desired.intensity à configuração de indexação.

Depois que o índice é reconstruído, você pode usar a consulta de agregação nos campos recém-adicionados, dados de registro de pesquisa, dados de sombra e dados de status de conectividade de objeto.

Ao alterar o modo de indexação, verifique se todos os campos personalizados são válidos utilizando o novo modo de indexação. Por exemplo, se você começar usando o modo REGISTRY_AND_SHADOW com um campo personalizado chamado shadow.desired.temperature, deverá excluir o campo personalizado shadow.desired.temperature antes de alterar o modo de indexação para REGISTRY. Se a configuração de indexação contiver campos personalizados que não são indexados pelo modo de indexação, a atualização falhará.

Descrever um índice de objetos

O comando a seguir mostra como usar o comando describe-index da CLI para recuperar o status atual do índice de objetos.

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

A resposta do comando pode ser semelhante a:

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

Na primeira vez que você indexar frotas, o AWS IoT cria o índice. Não é possível consultar o índice se indexStatus estiver no estado BUILDING. O schema do índice de objetos indica qual tipo de dados (REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS) é indexado.

A alteração da configuração do índice faz com que o índice seja recompilado. Durante esse processo, o indexStatus é REBUILDING. É possível executar consultas em dados no índice de objetos enquanto ele está sendo reconstruído. Por exemplo, se você alterar a configuração do índice de REGISTRY para REGISTRY_AND_SHADOW enquanto o índice estiver sendo recompilado, poderá consultar dados do registro, incluindo as últimas atualizações. No entanto, você não pode consultar os dados de sombra até que a reconstrução seja concluída. O tempo necessário para compilar ou recompilar o índice depende da quantidade de dados.

Você pode observar valores diferentes no campo do esquema conforme as fontes de dados configuradas. A tabela a seguir exibe os diferentes valores de esquema e as descrições correspondentes:

Consultar um índice de objetos

Use o comando search-index da CLI para consultar dados no í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"
}

Na resposta JSON, "connectivity" (conforme habilitado pela configuração thingConnectivityIndexingMode=STATUS) fornece um valor booliano, um registro de data/hora e um disconnectReason que indicam se o dispositivo está conectado ao AWS IoT Core. O dispositivo "mything1" desconectado (false) no horário POSIX 1556649874716 devido a CONNECTION_LOST. Para acessar mais informações sobre motivos de desconexão, consulte Eventos de ciclo de vida.

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

O dispositivo "mything2" conectado (true) no horário POSIX 1556649855046:

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

Os registros de data/hora são expressos em milissegundos desde o epoch, portanto, 1556649855046 representa 18:44:15.046 na terça-feira, 30 de abril de 2019 (UTC).

Restrições e limitações

Estas são as restrições e limitações para AWS_Things.

Autorização

É possível especificar o índice de objetos como um nome do recurso da Amazon (ARN) em uma ação de política do AWS IoT, da seguinte forma.