Gerenciar a indexação de objetos - AWS IoT Core
Habilitar a indexação de objetosDescrever um índice de objetosConsultar um índice de objetosRestrições e limitaçõesAutorização

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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

Você usa o comando update-indexing-configurationCLI ou a operação da UpdateIndexingConfigurationAPI para criar o AWS_Things índice 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 coisas

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

  • thingIndexingMode: controla se o registro ou a sombra estão indexados. Quando thingIndexingMode está definido como sendoOFF, a indexação de itens é desativada.

  • thingConnectivityIndexingMode: especifica se os dados de conectividade do item estão indexados.

  • deviceDefenderIndexingMode: especifica se os dados de violações do Device Defender estão indexados.

  • namedShadowIndexingMode: especifica se os dados de sombra nomeados são indexados. Para selecionar sombras nomeadas para adicionar à sua configuração de indexação de frotas, defina namedShadowIndexingMode como ON e especifique os nomes de sombras nomeadas em filter.

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

Atributo Valores válidos Registro Shadow Conectividade Violações de DD Sombra nomeada
thingIndexingMode DESL.
REGISTRY ✓
REGISTRY_AND_SHADOW ✓ ✓
thingConnectivityIndexingMode Não especificado.
DESL.
STATUS ✓
deviceDefenderIndexingMode Não especificado.
DESL.
VIOLAÇÕES ✓
namedShadowIndexingMode Não especificado.
DESL.
ON ✓

Campos gerenciados e campos personalizados

Campos gerenciados

Os campos gerenciados contêm dados associados a coisas, grupos de coisas, sombras de dispositivos, conectividade de dispositivos e violações do Device Defender. AWS IoT define o tipo de dados nos 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-configurationCLI para criar ou atualizar os campos personalizados (veja um exemplo de comando em Atualizar 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 geolocalização.

namedShadowNames

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

Exemplo

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

geoLocations

Para adicionar dados de geolocalização à sua configuração de indexação de frota:

  • Se seus dados de geolocalização estiverem armazenados em uma sombra clássica (sem nome), thingIndexingMode defina como REGISTRY_AND_SHADOW e especifique seus dados de geolocalização no filtro. geoLocations

    O exemplo de filtro abaixo especifica um objeto GeoLocation em uma sombra clássica (sem nome):

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

  • Se seus dados de geolocalização estiverem armazenados em uma sombra nomeada, namedShadowIndexingMode defina como ON, adicione o nome da sombra no namedShadowNames filtro e especifique seus dados de geolocalização no geoLocations filtro.

    O exemplo de filtro abaixo especifica um objeto GeoLocation em um nome shadow ()nameShadow1:

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

Para obter mais informações, consulte IndexingFiltera Referência da AWS IoTAPI.

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

Para atualizar sua configuração de indexação, use o comando AWS IoT update-indexing-configuration CLI. 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"
}
nota

A indexação da frota pode levar alguns minutos para atualizar o índice da frota. Recomendamos aguardar até que indexStatus exiba ATIVO antes de usá-lo. Os seus valores no campo do esquema podem ser diferentes, dependendo das fontes de dados que configurou. Para acessar mais informações, consulte Descrever um índice de objetos.

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.

nota

Atualizar a configuração de indexação de campos personalizados substitui todos os campos personalizados existentes. Especifique todos os campos personalizados ao chamar update-indexing-configuration.

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

A primeira vez que você faz a indexação de frotas, AWS IoT cria seu í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:

Esquema Descrição
DESL. Nenhuma fonte de dados está configurada ou indexada.
REGISTRY Os dados de registro são indexados.
REGISTRY_AND_SHADOW Os dados de registro e dados de sombra (clássica) sem nome são indexados.
REGISTRY_AND_CONNECTIVITY Os dados do registro e os dados de conectividade são indexados.
REGISTRY_AND_SHADOW_AND_CONNECTIVITY_STATUS Os dados de registro, dados de sombra (clássica) sem nome e dados de conectividade são indexados.
MULTI_INDEXING_MODE

Os dados de sombra nomeada ou de violações do Device Defender são indexados, além dos dados de registro, sombra (clássica) sem nome ou conectividade.

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).

Importante

Se um dispositivo foi desconectado por aproximadamente uma hora, o valor de "timestamp" e o valor de "disconnectReason" do status de conectividade poderá ser ausente.

Restrições e limitações

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

Campos de sombra com tipos complexos

Um campo de sombra será indexado somente se o valor do campo for um tipo simples, como um objeto JSON que não contém uma matriz ou uma matriz que consiste inteiramente em tipos simples. Tipo simples é uma string, um número ou um dos literais true ou false. Por exemplo, dado estado de sombra a seguir, o valor do campo "palette" não é indexado porque é uma matriz que contém itens de tipos complexos. O valor de campo "colors" é indexado, pois cada valor na matriz é uma string. 

{
    "state": {
        "reported": {
            "switched": "ON",
            "colors": [ "RED", "GREEN", "BLUE" ],
            "palette": [
                {
                    "name": "RED", 
                    "intensity": 124
                },
                {
                    "name": "GREEN", 
                    "intensity": 68
                },
                {
                    "name": "BLUE", 
                    "intensity": 201
                }
            ]
        }
    }
}
Nomes de campo de sombra aninhados

Os nomes de campos de sombra aninhados são armazenados como uma string delimitada por ponto (.). Por exemplo, considerando um documento de sombra:

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

O nome do campo three é armazenado como desired.one.two.three. Se você também tiver um documento de sombra, ele é armazenado da seguinte maneira:

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

Ambos correspondem a uma consulta para shadow.desired.one.two.three:v2. Como prática recomendada, não use pontos em nomes de campos de sombra.

Metadados de sombra

Um campo de uma seção de metadados de sombra é indexado, mas somente se o campo correspondente na seção "state" da sombra for indexado. (No exemplo anterior, o campo "palette" na seção de metadados da sombra também não é indexado.)

Dispositivos não registrados

A indexação da frota indexa o status de conectividade de um dispositivo cuja conexão clientId é a mesma de thingName de um objeto registrada no Registro.

Sombras não registradas

Se você costuma UpdateThingShadowcriar uma sombra usando um nome de coisa que não foi registrado em sua AWS IoT conta, os campos nessa sombra não são indexados. Isso se aplica tanto à sombra clássica sem nome quanto à sombra nomeada.

Valores numéricos

Se qualquer registro ou dado de sombra for reconhecido pelo serviço como um valor numérico, ele será indexado dessa maneira. Você pode realizar consultas envolvendo intervalos e operadores de comparação de valores numéricos, (por exemplo "attribute.foo<5" ou "shadow.reported.foo:[75 TO 80]"). Para ser reconhecido como numérico, o valor dos dados deve ser um número JSON do tipo literal e válido. O valor pode ser um número inteiro no intervalo -2^53...2^53-1, um ponto flutuante de precisão dupla com notação exponencial opcional ou parte de uma matriz que contém apenas esses valores.

Valores nulos

Valores nulos não são indexados.

Valores máximos

O número máximo de campos personalizados para consultas de agregação é cinco.

O número máximo de percentis solicitados para consultas de agregação é 100.

Autorização

Você pode especificar o índice de coisas como um Amazon Resource Name (ARN) em uma ação AWS IoT política, da seguinte forma.

Ação Recurso

iot:SearchIndex

O ARN de um índice (por exemplo, arn:aws:iot:your-aws-regionyour-aws-account:index/AWS_Things).

iot:DescribeIndex

O ARN de um índice (por exemplo, arn:aws:iot:your-aws-region:index/AWS_Things).
nota

Se você tiver permissões para consultar o índice de frota, você poderá acessar os dados das objetos em toda a frota.