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 da AWS IoT](thing-registry.md), dados da [sombra do dispositivo da AWS IoT](iot-device-shadows.md), dados de [conectividade da AWS IoT](life-cycle-events.md) e dados de violações do [AWS IoT Device Defender](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/what-is-device-defender.html). **Topics** + [Habilitar a indexação de objetos](#enable-index) + [Descrever um índice de objetos](#describe-index) + [Consultar um índice de objetos](#search-index) + [Restrições e limitações](#index-limitations) + [Autorização](#query-auth) ## Habilitar a indexação de objetos Você usa o comando [update-indexing-configuration](https://docs.aws.amazon.com/cli/latest/reference/iot/update-indexing-configuration.html)CLI ou a operação da [UpdateIndexingConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateIndexingConfiguration.html)API 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 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: + `thingIndexingMode`: controla se o registro ou a sombra estão indexados. Quando `thingIndexingMode` é definido como `OFF`, a indexação de itens é desativada. + `thingConnectivityIndexingMode`: especifica se dados de conectividade são indexados. + `deviceDefenderIndexingMode`: especifica se os dados de violações do Device Defender são indexados. + `namedShadowIndexingMode`: especifica se os dados de sombra nomeada 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 [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html). A tabela abaixo mostra os valores válidos para cada modo de indexação e a fonte de dados indexada para cada valor. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/managing-index.html) ### 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-configuration](https://docs.aws.amazon.com/cli/latest/reference/iot/update-indexing-configuration.html)CLI para criar ou atualizar os campos personalizados (veja um exemplo de comando em [Atualizar exemplos de configuração de indexação](#update-index-examples)). Para acessar mais informações, consulte [Campos personalizados](managing-fleet-index.md#custom-field). ### 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: + Se seus dados de localização geográfica estiverem armazenados em uma sombra clássica (sem nome), defina `thingIndexingMode` como REGISTRY\$1AND\$1SHADOW e especifique seus dados de localização geográfica 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 localização geográfica estiverem armazenados em uma sombra nomeada, defina `namedShadowIndexingMode` como ON, adicione o nome da sombra no filtro `namedShadowNames` e especifique seus dados de localização geográfica no filtro `geoLocations`. O exemplo de filtro abaixo especifica um objeto geoLocation em uma sombra nomeada (`nameShadow1`): ``` "filter": { "namedShadowNames": [ "namedShadow1" ], "geoLocations": [ { "name": "shadow.name.namedShadow1.reported.location", "order": "LonLat" } ] } ``` Para obter mais informações, consulte [ IndexingFilter](https://docs.aws.amazon.com/iot/latest/apireference/API_IndexingFilter.html)a *Referência da *AWS IoT*API*. ### 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](#describe-index). 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: | Schema | Description | | --- | --- | | DESL. | Nenhuma fonte de dados está configurada ou indexada. | | REGISTRY | Os dados de registro são indexados. | | REGISTRY\$1AND\$1SHADOW | Os dados de registro e dados de sombra (clássica) sem nome são indexados. | | REGISTRY\$1AND\$1CONNECTIVITY | Os dados do registro e os dados de conectividade são indexados. | | REGISTRY\$1AND\$1SHADOW\$1AND\$1CONNECTIVITY\$1STATUS | Os dados de registro, dados de sombra (clássica) sem nome e dados de conectividade são indexados. | | MULTI\$1INDEXING\$1MODE | 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](life-cycle-events.md). ``` "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](https://docs.aws.amazon.com//iot/latest/developerguide/thing-registry.html). **Sombras não registradas** Se você costuma [UpdateThingShadow](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html)criar uma sombra usando um nome de coisa que não foi registrado na 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.