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á.
# Indexação de frotas
Você pode usar a indexação de frotas para indexar, pesquisar e agregar os dados de seus dispositivos das seguintes fontes: [registro da AWS IoT](thing-registry.md), [sombra do dispositivo da AWS IoT](iot-device-shadows.md), [conectividade da AWS IoT](life-cycle-events.md), [Catálogo de pacotes de software do AWS IoT Device Management](software-package-catalog.md) e violações do [AWS IoT Device Defender](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/what-is-device-defender.html). É possível consultar um grupo de dispositivos e agregar estatísticas sobre registros de dispositivos baseados em diferentes combinações de atributos do dispositivo, incluindo estado, conectividade e violações do dispositivo. Com a indexação de frotas, é possível organizar, investigar e solucionar problemas em sua frota de dispositivos.
A indexação de frotas oferece os seguintes recursos.
## Gerenciamento de atualizações de índice
É possível configurar um índice de frota para indexar atualizações dos seus grupos de objetos, registros de objetos, sombras de dispositivos, conectividade de dispositivos e violações de dispositivos. Quando você ativa a indexação de frotas, o AWS IoT cria um índice das suas objetos ou grupos de objetos. `AWS_Things` é o índice criado para todas as suas objetos. `AWS_ThingGroups` é o índice que contém todos seus grupos de objetos. Quando a indexação de frotas estiver ativa, você poderá executar consultas em seu índice. Por exemplo, você pode encontrar todos os dispositivos portáteis com mais de 70% de duração da bateria. AWS IoT atualiza o índice continuamente com seus dados mais recentes. Para acessar mais informações, consulte [Gerenciar a indexação de frotas](managing-fleet-index.md).
## Consultar o status de conectividade de um dispositivo específico
Essa API fornece acesso de baixa latência e alto throughput às informações mais recentes de conectividade específicas do dispositivo. Para acessar mais informações, consulte [Status de conectividade de dispositivos](https://docs.aws.amazon.com/iot/latest/developerguide/device-connectivity-status.html).
## Pesquisa em várias fontes dos dados
É possível criar uma string de consulta com base em [uma linguagem de consulta](query-syntax.md) e usá-la para pesquisar em fontes de dados. Você também precisa configurar as fontes de dados na configuração de indexação da frota para que a configuração de indexação contenha as fontes de dados nas quais você deseja pesquisar. A string de consulta descreve o objeto que você quer encontrar. Você pode criar consultas usando campos AWS gerenciados, campos personalizados e quaisquer atributos de suas fontes de dados indexadas. Para acessar mais informações sobre fontes de dados compatíveis com a indexação de frotas, consulte [Gerenciamento da indexação de objetos](managing-index.md).
## Consulta de dados agregados
É possível pesquisar seus dispositivos em busca de dados agregados e retornar estatísticas, percentil, cardinalidade ou uma lista de objetos com consultas de pesquisa sobre campos específicos. Você pode executar agregações em campos AWS gerenciados ou em qualquer atributo configurado como campos personalizados nas configurações de indexação da frota. Para acessar mais informações sobre consulta de agregação, consulte [Consultar dados agregados](index-aggregate.md).
## Monitoramento de dados agregados e criação de alarmes usando as métricas da frota
Você pode usar métricas de frota para enviar dados agregados CloudWatch automaticamente, analisar tendências e criar alarmes para monitorar o estado agregado de sua frota com base em limites predefinidos. Para acessar mais informações sobre métricas de frota, consulte [Métricas de frota](iot-fleet-metrics.md).
# Gerenciamento da indexação de frotas
A indexação de frotas gerencia dois tipos de índices: indexação de objetos e indexação de grupos de objetos.
## Indexação de objetos
O índice criado para todas as suas objetos é chamado de `AWS_Things`. A indexação de coisas comporta as 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). Ao adicionar essas fontes de dados à sua configuração de indexação de frotas, é possível pesquisar objetos, consultar dados agregados e criar grupos dinâmicos de objetos e métricas de frota com base em suas consultas de pesquisa.
**Registro** -AWS IoT fornece um registro que ajuda você a gerenciar coisas. É possível adicionar os dados do registro à configuração de indexação da frota para pesquisar dispositivos com base nos nomes, descrições e outros atributos do registro das objetos. Para acessar mais informações sobre o registro, consulte [Como gerenciar objetos com o registro](thing-registry.md).
**Sombra**- o [serviço de sombra do dispositivo do AWS IoT](iot-device-shadows.md) oferece sombras que ajudam você a armazenar os dados de estado de um dispositivo. A indexação de objetos é compatível tanto com sombras clássicas sem nome quanto sombras nomeadas. Para indexar sombras nomeadas, ative as configurações de sombra nomeada e especifique os nomes de sombra na configuração de indexação de objetos. Por padrão, você pode adicionar até 10 nomes de sombra por Conta da AWS. Para saber como aumentar o limite de número de nomes de sombras, consulte [AWS IoT Device Management Cotas](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#fleet-indexing-limits) na *Referência geral da AWS *.
Para adicionar sombras nomeadas para indexação:
+ Se você usa o [console do AWS IoT](https://console.aws.amazon.com/iot/home), ative a **Indexação de objetos**, selecione **Adicionar sombras nomeadas** e adicione os nomes das sombras por meio da **Seleção de sombras nomeadas**.
+ Se você usar o AWS Command Line Interface (AWS CLI), `namedShadowIndexingMode` defina como ser `ON` e especifique os nomes das sombras em [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html). Para ver exemplos de comandos da CLI, consulte [Gerenciamento da indexação de objetos](managing-index.md#enable-index).
**Importante**
20 de julho de 2022 é a versão de Disponibilidade Geral (GA) da integração de indexação de frotas de gerenciamento de AWS IoT dispositivos com sombras AWS IoT Core nomeadas e AWS IoT Device Defender detecção de violações. Com esta versão do GA, é possível indexar sombras nomeadas específicas especificando nomes das sombras. Caso tenha adicionado suas sombras nomeadas para indexação durante o período de pré-visualização pública desse atributo, de 30 de novembro de 2021 a 19 de julho de 2022, recomendamos que você reconfigure suas definições de indexação de frotas e escolha nomes de sombra específicos para reduzir o custo de indexação e otimizar o desempenho.
Para acessar mais informações sobre as sombras, consulte [Serviço de sombra do dispositivo do AWS IoT](iot-device-shadows.md).
**Conectividade** - os dados de conectividade do dispositivo ajudam você a identificar o status da conexão dos dispositivos. Esses dados de conectividade são orientados por [eventos do ciclo de vida](life-cycle-events.md). Quando um cliente se conecta ou desconecta, AWS IoT publica eventos do ciclo de vida com mensagens para tópicos do MQTT. Uma mensagem de conexão ou desconexão pode ser uma lista de elementos JSON fornecendo detalhes sobre o status da conexão. Para acessar mais informações sobre a conectividade de dispositivos, consulte [Eventos de ciclo de vida](life-cycle-events.md).
**Violações do Device Defender** - os dados de AWS IoT Device Defender violações ajudam a identificar comportamentos anômalos do dispositivo em relação aos comportamentos normais que você define em um Perfil de Segurança. Um perfil de segurança contém um conjunto de comportamentos esperados. Cada comportamento utiliza uma métrica que especifica o comportamento normal dos dispositivos. Para acessar mais informações sobre violações do Device Defender, consulte [Detectar AWS IoT Device Defender](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/device-defender-detect.html).
Para acessar mais informações, consulte [Gerenciamento da indexação de objetos](managing-index.md).
## Indexação de grupo de objetos
`AWS_ThingGroups` é o índice que contém todos os seus grupos de objetos. Você pode usar esse índice para pesquisar grupos com base no nome do grupo, na descrição, nos atributos e em todos os nomes de grupo pai.
Para acessar mais informações, consulte [Gerenciamento da indexação de grupos de objetos](thinggroup-index.md).
## 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 AWS IoT algo. 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`. Para acessar mais informações, consulte [Campos personalizados](#custom-field).
A seguir está uma lista dos campos gerenciados para indexação de objetos:
+ Campos gerenciados para o registro
```
"managedFields" : [
{name:thingId, type:String},
{name:thingName, type:String},
{name:registry.version, type:Number},
{name:registry.thingTypeName, type:String},
{name:registry.thingGroupNames, type:String},
]
```
+ Campos gerenciados para sombras clássicas sem nome
```
"managedFields" : [
{name:shadow.version, type:Number},
{name:shadow.hasDelta, type:Boolean}
]
```
+ Campos gerenciados para sombras nomeadas
```
"managedFields" : [
{name:shadow.name.shadowName.version, type:Number},
{name:shadow.name.shadowName.hasDelta, type:Boolean}
]
```
+ Campos gerenciados para conectividade de objetos
```
"managedFields" : [
{name:connectivity.timestamp, type:Number},
{name:connectivity.version, type:Number},
{name:connectivity.connected, type:Boolean},
{name:connectivity.disconnectReason, type:String}
]
```
+ Campos gerenciados para o Device Defender
```
"managedFields" : [
{name:deviceDefender.violationCount, type:Number},
{name:deviceDefender.securityprofile.behaviorname.metricName, type:String},
{name:deviceDefender.securityprofile.behaviorname.lastViolationTime, type:Number},
{name:deviceDefender.securityprofile.behaviorname.lastViolationValue, type:String},
{name:deviceDefender.securityprofile.behaviorname.inViolation, type:Boolean}
]
```
+ Campos gerenciados para grupos de objetos
```
"managedFields" : [
{name:description, type:String},
{name:parentGroupNames, type:String},
{name:thingGroupId, type:String},
{name:thingGroupName, type:String},
{name:version, type:Number},
]
```
A tabela a seguir lista os campos gerenciados que não podem ser pesquisados.
| Fonte de dados | Campo gerenciado que não pode ser pesquisado |
| --- | --- |
| Registro | registry.version |
| Sombra nomeada | shadow.version |
| Sombra nomeada | shadow.name.\$1.version |
| Device Defender | deviceDefender.version |
| Grupos de objetos | version |
## Campos personalizados
Você pode agregar atributos de objetos, 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](managing-index.md#update-index-examples)).
+ **Nomes de campos personalizados**
Os nomes de campo personalizados para atributos de objetos e grupos de objetos iniciam com `attributes.`, seguidos pelo nome do atributo. Se a indexação de sombra sem nome estiver ativada, as objetos podem ter nomes de campos personalizados que iniciem com `shadow.desired` ou `shadow.reported`, seguidos pelo nome do valor de dados da sombra sem nome. Se a indexação de sombra nomeada estiver ativada, as objetos podem ter nomes de campos personalizados que iniciem com `shadow.name.*.desired.` ou `shadow.name.*.reported.`, seguidos pelo valor de dados da sombra nomeada. Se a indexação de violações do Device Defender estiver ativada, as objetos poderão ter nomes de campos personalizados que iniciem com`deviceDefender.`, seguidos pelo valor dos dados de violações do Device Defender.
O nome do valor de dados ou atributo que acompanha o prefixo só pode possuir caracteres alfanuméricos, - (hífen) e \$1 (sublinhado). Ele não pode ter espaços.
Caso haja uma inconsistência de tipo entre um campo personalizado na configuração e o valor sendo indexado, a indexação de frotas ignorará o valor inconsistente para consultas de agregação. CloudWatch Os registros são úteis para solucionar problemas de consulta de agregação. Para obter mais informações, consulte [Solução de problemas de consultas de agregação para o serviço de indexação de frota](fleet-indexing-troubleshooting.md#aggregation-troubleshooting).
+ **Nomes de campos personalizados**
Os tipos de campos personalizados têm os seguintes valores compatíveis: `Number`, `String` e `Boolean`.
# 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.
# Gerenciamento da indexação de grupos de objetos
`AWS_ThingGroups` é o índice que contém todos os seus grupos de objetos. Você pode usar esse índice para pesquisar grupos com base no nome do grupo, na descrição, nos atributos e em todos os nomes de grupo pai.
## Habilitar a indexação de grupos de objetos
Você pode usar a `thing-group-indexing-configuration` configuração na [UpdateIndexingConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateIndexingConfiguration.html)API para criar o `AWS_ThingGroups` índice e controlar sua configuração. Você pode usar a [GetIndexingConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_GetIndexingConfiguration.html)API para recuperar a configuração de indexação atual.
Use o comando **update-indexing-configuration** da CLI para atualizar as configurações da indexação de grupos de objetos:
```
aws iot update-indexing-configuration --thing-group-indexing-configuration thingGroupIndexingMode=ON
```
Você também pode atualizar configurações para a indexação de objetos e grupos de objetos em um único comando, como mostrado a seguir:
```
aws iot update-indexing-configuration --thing-indexing-configuration thingIndexingMode=REGISTRY --thing-group-indexing-configuration thingGroupIndexingMode=ON
```
Estes são valores válidos para `thingGroupIndexingMode`.
DESL.
Sem indexing/delete índice.
ON
Criar ou configurar o índice `AWS_ThingGroups`.
Para recuperar as configurações atuais de indexação de objetos e grupos de objetos, execute o comando **get-indexing-configuration** da CLI:
```
aws iot get-indexing-configuration
```
A resposta do comando é semelhante a:
```
{
"thingGroupIndexingConfiguration": {
"thingGroupIndexingMode": "ON"
}
}
```
## Descrever índices de grupos
Para recuperar o status atual do índice `AWS_ThingGroups`, use o comando **describe-index** da CLI:
```
aws iot describe-index --index-name "AWS_ThingGroups"
```
A resposta do comando é semelhante a:
```
{
"indexStatus": "ACTIVE",
"indexName": "AWS_ThingGroups",
"schema": "THING_GROUPS"
}
```
AWS IoT cria seu índice na primeira vez que você indexa. Você não pode consultar o índice se o `indexStatus` é `BUILDING`.
## Consultar um índice de grupos de objetos
Para consultar dados no índice, use o comando **search-index** da CLI:
```
aws iot search-index --index-name "AWS_ThingGroups" --query-string "thingGroupName:mythinggroup*"
```
## Autorização
Você pode especificar o índice de grupos de coisas como um ARN de recurso em uma ação de AWS IoT política, da seguinte maneira.
****
| Ação | Recurso |
| --- | --- |
| `iot:SearchIndex` | O ARN de um índice (por exemplo, `arn:aws:iot:your-aws-region:index/AWS_ThingGroups`). |
| `iot:DescribeIndex` | O ARN de um índice (por exemplo, `arn:aws:iot:your-aws-region:index/AWS_ThingGroups`). |
# Consultas do status de conectividade do dispositivo
AWS IoT A indexação de frota oferece suporte à consulta de conectividade de dispositivos individuais, permitindo que você recupere com eficiência o status da conectividade e os metadados relacionados para dispositivos específicos. Esse recurso complementa os recursos existentes de indexação e consulta em toda a frota.
## Como funciona
O suporte à consulta de conectividade de dispositivos pode ser usado para recuperação otimizada do status de conectividade de um único dispositivo. Essa API fornece acesso de baixa latência e alto throughput às informações mais recentes de conectividade específicas do dispositivo. Depois de habilitar a indexação de conectividade, você terá acesso a essa API de consulta, que será cobrada como consultas padrão. Para acessar mais informações, consulte [Preços do AWS IoT Device Management](https://aws.amazon.com/iot-device-management/pricing/#:~:text=Search%20queries%20(per%2010%2C000%20queries)).
## Recursos
Com o suporte à consulta de conectividade de dispositivos, você pode:
1. Consultar o estado atual de conectividade (conectado ou desconectado) de determinado dispositivo usando o respectivo `thingName`.
1. Recuperar metadados adicionais de conectividade, incluindo:
1. Motivo da desconexão
1. Carimbos de data/hora do evento de conexão ou desconexão mais recente.
**nota**
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).
## Benefícios
1. **Baixa latência:** reflete o estado mais recente de conectividade do dispositivo e oferece baixa latência para refletir as alterações do estado de conexão do IoT Core. O IoT Core determina que um dispositivo está desconectado assim que recebe uma solicitação de desconexão dele ou no caso de um dispositivo se desconectar sem enviar uma solicitação de desconexão. O IoT Core aguardará 1,5x do tempo de keep-alive configurado antes de decidir desconectar o cliente. A API de status da conectividade exibirá essas alterações normalmente em menos de um segundo após o IoT Core determinar a mudança de estado conectado de um dispositivo.
1. **Alto throughput:** aceita 350 transações por segundo (TPS) por padrão e pode ser ajustável para um valor maior mediante solicitação.
1. **Retenção de dados:** armazena dados de eventos indefinidamente quando o ConnectivityIndexing modo Fleet Indexing (FI) está ativado e o item não é excluído. Se você desabilitar a indexação de conectividade, os registros não serão retidos.
**nota**
Se a indexação do status de conectividade tiver sido habilitada antes do lançamento dessa API, o Fleet Indexing começará a rastrear as alterações do status de conectividade após o lançamento da API e exibirá o status atualizado com base nessas alterações.
## Pré-requisitos
Para usar o suporte à consulta de conectividade do dispositivo:
1. [Configurar uma AWS conta](https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html)
1. Integre e registre dispositivos AWS IoT Core na sua região preferida
1. [Habilite o Fleet Indexing](https://docs.aws.amazon.com/iot/latest/developerguide/managing-index.html) com indexação de conectividade.
**nota**
Nenhuma configuração adicional será necessária se você já tiver a indexação de conectividade habilitada.
Para receber instruções detalhadas de configuração, consulte o [Guia do desenvolvedor da AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/setting-up.html).
## Exemplos
```
aws iot get-thing-connectivity-data --thing-name myThingName
```
```
{
"connected": true,
"disconnectReason": "NONE",
"thingName": "myThingName",
"timestamp": "2024-12-19T10:00:00.000000-08:00"
}
```
+ `thingName`: o nome do dispositivo conforme indicado na solicitação. Isso também corresponde ao clientId usado para se conectar ao AWS IoT Core.
+ `disconnectReason`: motivo da desconexão. Será NONE para um dispositivo conectado.
+ `connected`: o valor booliano verdadeiro indicando que esse dispositivo está conectado no momento.
+ `timestamp`: o carimbo de data/hora que representa a desconexão mais recente do dispositivo em milissegundos.
```
aws iot get-thing-connectivity-data --thing-name myThingName
```
```
{
"connected": false,
"disconnectReason": "CLIENT_INITIATED_DISCONNECT",
"thingName": "myThingName",
"timestamp": "2024-12-19T10:30:00.000000-08:00"
}
```
+ `thingName`: o nome do dispositivo conforme indicado na solicitação. Isso também corresponde ao clientId usado para se conectar ao AWS IoT Core.
+ `disconnectReason`: O motivo da desconexão é CLIENT\$1INITIATED\$1DISCONNECT indicando que o cliente indicou que ele se desconectaria. AWS IoT Core
+ `connected`: o valor booliano falso indicando que esse dispositivo está desconectado no momento.
+ `timestamp`: o carimbo de data/hora que representa a desconexão mais recente do dispositivo em milissegundos.
```
aws iot get-thing-connectivity-data --thing-name neverConnectedThing
```
```
{
"connected": false,
"disconnectReason": "UNKNOWN",
"thingName": "neverConnectedThing"
}
```
+ `thingName`: o nome do dispositivo conforme indicado na solicitação. Isso também corresponde ao clientId usado para se conectar ao AWS IoT Core.
+ `disconnectReason`: motivo da desconexão. Será “UNKNOWN” para um dispositivo que nunca foi conectado ou para o qual o Fleet Indexing não tenha o último motivo de desconexão armazenado.
+ `connected`: o valor booliano falso indicando que esse dispositivo está desconectado no momento.
+ `timestamp`: o carimbo de data/hora não é exibido para um dispositivo que nunca foi conectado ou para o qual o Fleet Indexing não tem o último carimbo de data/hora armazenado.
# Consulta de dados agregados
AWS IoT fornece quatro APIs (`GetStatistics`,`GetCardinality`,`GetPercentiles`, e`GetBucketsAggregation`) que permitem pesquisar dados agregados em sua frota de dispositivos.
**nota**
Para problemas com valores ausentes ou inesperados para a agregação APIs, leia o guia de solução de [problemas de indexação de frotas](fleet-indexing-troubleshooting.md).
## GetStatistics
A [GetStatistics](https://docs.aws.amazon.com/iot/latest/apireference/API_GetStatistics.html)API e o comando **get-statistics** CLI retornam a contagem, a média, a soma, o mínimo, o máximo, a soma dos quadrados, a variância e o desvio padrão para o campo agregado especificado.
O comando da CLI **get-statistics** usa os seguintes parâmetros:
`index-name`
O nome do índice a ser pesquisado. O valor padrão é `AWS_Things`.
`query-string`
A consulta usada para pesquisar o índice. Você pode especificar `"*"` para obter a contagem de todas as coisas indexadas em seu Conta da AWS.
`aggregationField`
(Opcional) O campo a ser agregado. Esse campo deve ser um campo gerenciado ou personalizado definido ao chamar **update-indexing-configuration**. Se você não especificar um campo de agregação, `registry.version` será usado como o campo de agregação.
`query-version`
A versão da consulta a ser usada. O valor padrão é `2017-09-30`.
O tipo de campo de agregação pode afetar as estatísticas retornadas.
### GetStatistics com valores de string
Se você agregar em um campo de string, chamar `GetStatistics` retornará uma contagem de dispositivos que têm atributos que correspondem à consulta. Por exemplo:
```
aws iot get-statistics --aggregation-field 'attributes.stringAttribute'
--query-string '*'
```
Esse comando retorna o número de dispositivos que contêm um atributo chamado `stringAttribute`:
```
{
"statistics": {
"count": 3
}
}
```
### GetStatistics com valores booleanos
Quando você chama `GetStatistics` com um campo de agregação booliano:
+ AVERAGE é a porcentagem de dispositivos que correspondem à consulta.
+ MINIMUM é 0 ou 1 conforme as seguintes regras:
+ Se todos os valores do campo de agregação forem `false`, MINIMUM será 0.
+ Se todos os valores do campo de agregação forem `true`, MINIMUM será 1.
+ Se os valores do campo de agregação forem uma mistura de `false` e `true`, MINIMUM será 0.
+ MAXIMUM é 0 ou 1 conforme as seguintes regras:
+ Se todos os valores do campo de agregação forem `false`, MAXIMUM será 0.
+ Se todos os valores do campo de agregação forem `true`, MAXIMUM será 1.
+ Se os valores do campo de agregação forem uma mistura de `false` e `true`, MAXIMUM será 1.
+ SUM é a soma do equivalente inteiro dos valores boolianos.
+ COUNT é a contagem de objetos que correspondem aos critérios da string de consulta e contêm um valor de campo de agregação válido.
### GetStatistics com valores numéricos
Quando você chama `GetStatistics` e especifica um campo de agregação do tipo `Number`, `GetStatistics` retorna os seguintes valores:
contagem
A contagem de objetos que correspondem aos critérios da string de consulta e contêm um valor de campo de agregação válido.
média
A média dos valores numéricos que correspondem à consulta.
soma
A soma dos valores numéricos que correspondem à consulta.
mínimo
O menor dos valores numéricos que correspondem à consulta.
máximo
O maior dos valores numéricos que correspondem à consulta.
sumOfSquares
A soma dos quadrados dos valores numéricos que correspondem à consulta.
variância
A variação dos valores numéricos que correspondem à consulta. A variância de um conjunto de valores é a média dos quadrados das diferenças de cada valor em relação ao valor médio do conjunto.
stdDeviation
O desvio padrão dos valores numéricos que correspondem à consulta. O desvio padrão de um conjunto de valores é uma medida de como os valores estão distribuídos.
O exemplo a seguir mostra como chamar **get-statistics** com um campo personalizado numérico.
```
aws iot get-statistics --aggregation-field 'attributes.numericAttribute2'
--query-string '*'
```
```
{
"statistics": {
"count": 3,
"average": 33.333333333333336,
"sum": 100.0,
"minimum": -125.0,
"maximum": 150.0,
"sumOfSquares": 43750.0,
"variance": 13472.22222222222,
"stdDeviation": 116.06990230986766
}
}
```
Para campos de agregação numéricos, se os valores de campo excederem o valor duplo máximo, os valores estatísticos estarão vazios.
## GetCardinality
A [GetCardinality](https://docs.aws.amazon.com/iot/latest/apireference/API_GetCardinality.html)API e o comando **get-cardinality** CLI retornam a contagem aproximada de valores exclusivos que correspondem à consulta. Por exemplo, você pode querer encontrar o número de dispositivos com níveis de bateria inferiores a 50%:
```
aws iot get-cardinality --index-name AWS_Things --query-string "batterylevel
> 50" --aggregation-field "shadow.reported.batterylevel"
```
Este comando retorna o número de itens com níveis de bateria superiores a 50%:
```
{
"cardinality": 100
}
```
`cardinality` é sempre retornado por **get-cardinality** mesmo se não houver campos correspondentes. Por exemplo:
```
aws iot get-cardinality --query-string "thingName:Non-existent*"
--aggregation-field "attributes.customField_STR"
```
```
{
"cardinality": 0
}
```
O comando da CLI **get-cardinality** usa os seguintes parâmetros:
`index-name`
O nome do índice a ser pesquisado. O valor padrão é `AWS_Things`.
`query-string`
A consulta usada para pesquisar o índice. Você pode especificar `"*"` para obter a contagem de todas as coisas indexadas em seu Conta da AWS.
`aggregationField`
O campo a ser agregado.
`query-version`
A versão da consulta a ser usada. O valor padrão é `2017-09-30`.
## GetPercentiles
A [GetPercentiles](https://docs.aws.amazon.com/iot/latest/apireference/API_GetPercentiles.html)API e o comando **get-percentiles** CLI agrupam os valores agregados que correspondem à consulta em agrupamentos de percentis. Os agrupamentos de percentil padrão são: 1, 5, 25, 50, 75, 95, 99, embora você possa especificar o seu próprio quando chamar `GetPercentiles`. Esta função retorna um valor para cada grupo de percentis especificado (ou os agrupamentos de percentil padrão). O grupo de percentis “1” contém o valor de campo agregado que ocorre em aproximadamente um por cento dos valores que correspondem à consulta. O grupo de percentil “5” contém o valor de campo agregado que ocorre em aproximadamente cinco por cento dos valores que correspondem à consulta, e assim por diante. O resultado é uma aproximação. Quanto mais valores correspondem à consulta, mais precisos os valores do percentil.
O exemplo a seguir mostra como chamar o comando **get-percentiles** da CLI.
```
aws iot get-percentiles --query-string "thingName:*" --aggregation-field
"attributes.customField_NUM" --percents 10 20 30 40 50 60 70 80 90 99
```
```
{
"percentiles": [
{
"value": 3.0,
"percent": 80.0
},
{
"value": 2.5999999999999996,
"percent": 70.0
},
{
"value": 3.0,
"percent": 90.0
},
{
"value": 2.0,
"percent": 50.0
},
{
"value": 2.0,
"percent": 60.0
},
{
"value": 1.0,
"percent": 10.0
},
{
"value": 2.0,
"percent": 40.0
},
{
"value": 1.0,
"percent": 20.0
},
{
"value": 1.4,
"percent": 30.0
},
{
"value": 3.0,
"percent": 99.0
}
]
}
```
O comando a seguir mostra a saída retornada de **get-percentiles** quando não há documentos correspondentes.
```
aws iot get-percentiles --query-string "thingName:Non-existent*"
--aggregation-field "attributes.customField_NUM"
```
```
{
"percentiles": []
}
```
O comando da CLI **get-percentile** usa os seguintes parâmetros:
`index-name`
O nome do índice a ser pesquisado. O valor padrão é `AWS_Things`.
`query-string`
A consulta usada para pesquisar o índice. Você pode especificar `"*"` para obter a contagem de todas as coisas indexadas em seu Conta da AWS.
`aggregationField`
O campo a ser agregado, que deve ser do tipo `Number`.
`query-version`
A versão da consulta a ser usada. O valor padrão é `2017-09-30`.
`percents`
(Opcional) você pode usar esse parâmetro para especificar agrupamentos de percentil personalizados.
## GetBucketsAggregation
A [GetBucketsAggregation](https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html)API e o comando **get-buckets-aggregation** CLI retornam uma lista de buckets e o número total de itens que se encaixam nos critérios da sequência de caracteres de consulta.
O exemplo a seguir mostra como chamar o comando get-buckets-aggregation da CLI.
```
aws iot get-buckets-aggregation --query-string '*' --index-name AWS_Things --aggregation-field 'shadow.reported.batterylevelpercent' --buckets-aggregation-type 'termsAggregation={maxBuckets=5}'
```
O comando retorna os seguintes:
```
{
"totalCount": 20,
"buckets": [
{
"keyValue": "100",
"count": 12
},
{
"keyValue": "90",
"count": 5
},
{
"keyValue": "75",
"count": 3
}
]
}
```
O comando da CLI get-buckets-aggregation usa os seguintes parâmetros:
`index-name`
O nome do índice a ser pesquisado. O valor padrão é `AWS_Things`.
`query-string`
A consulta usada para pesquisar o índice. Você pode especificar `"*"` para obter a contagem de todas as coisas indexadas em seu Conta da AWS.
`aggregation-field`
O campo a ser agregado.
`buckets-aggregation-type`
O controle básico da forma de resposta e do tipo de agregação do bucket a ser executado.
## Autorização
Você pode especificar o índice de grupos de coisas como um ARN de recurso em uma ação de AWS IoT política, da seguinte maneira.
| Ação | Recurso |
| --- | --- |
| `iot:GetStatistics` | O ARN de um índice (por exemplo, `arn:aws:iot:your-aws-region:index/AWS_Things` ou `arn:aws:iot:your-aws-region:index/AWS_ThingGroups`). |
# Sintaxe de consulta
Na indexação de frotas, uma sintaxe de consulta é utilizada para especificar consultas.
## Recursos compatíveis
A sintaxe de consulta dá suporte aos seguintes atributos:
+ Termos e frases
+ Pesquisar campos
+ Pesquisa de prefixo
+ Pesquisa de intervalo
+ Operadores boolianos `AND`, `OR`, `NOT` e `–`. O hífen é usado para excluir algo dos resultados de pesquisa (por exemplo, `thingName:(tv* AND -plasma)`).
+ Agrupamento
+ Agrupamento de campos
+ Escape de caracteres especiais (tal como *\$1*)
+ O principal uso de curingas é limitado a 1 termo por consulta. Por exemplo, não é possível procurar `thingName:*my` e `thingGroupNames:*echo` na mesma consulta. As consultas que incluem um caractere curinga inicial têm um comprimento máximo de consulta de cem caracteres.
**nota**
Contas com um limite de API de consulta do Fleet Indexing superior a 30 solicitações por segundo estão sujeitas à limitação ao usar os principais termos de consulta curinga. Esse requests-per-second limite de 30 se aplica no nível da conta em todas as consultas APIs de indexação de frotas.
## Atributos não compatíveis
A sintaxe de consulta é compatível com os seguintes atributos:
+ Expressões regulares
+ Aumento
+ Classificação
+ Pesquisas difusas
+ Pesquisa de proximidade
+ Classificação
+ Agregação
+ Caracteres especiais: ```, `@`, `#`, `%`, `\`, `/`, `'`, `;`, e `,`. Observe que `,` só tem suporte em consultas geográficas.
## Observações
Alguns comentários sobre a linguagem de consulta:
+ O operador padrão é AND. Uma consulta de `"thingName:abc thingType:xyz"` é equivalente a `"thingName:abc AND thingType:xyz"`.
+ Se um campo não for especificado, AWS IoT pesquisa o termo em todos os campos Registry, Device Shadow e Device Defender.
+ Todos os nomes de campos diferenciam maiúsculas de minúsculas.
+ A pesquisa não diferencia maiúsculas de minúsculas. As palavras são separadas por caracteres de espaço em branco, conforme definido pelo `Character.isWhitespace(int)` de Java.
+ A indexação de dados de sombra do dispositivo (sombras sem nome e sombras nomeadas) inclui as seções relatadas, desejadas, delta e metadados.
+ As versões da sombra do dispositivo e registro não são pesquisáveis, mas estão presentes na resposta.
+ O número máximo de termos em uma consulta é doze.
+ O caractere especial `,` só tem suporte em consultas geográficas.
# Exemplo de consultas de objetos
Especifique consultas em uma string de consulta usando uma sintaxe de consulta. As consultas são passadas para a API [https://docs.aws.amazon.com/iot/latest/apireference/API_SearchIndex.html](https://docs.aws.amazon.com/iot/latest/apireference/API_SearchIndex.html). A tabela a seguir lista alguns exemplos de sequências de consulta.
| String de consulta | Resultado |
| --- | --- |
| abc | Consulta “abc” em qualquer registro, sombra (sombra clássica sem nome e sombra nomeada) ou campo de violações do Device Defender. |
| thingName:myThingName | Consultas sobre algo com o nome "myThingName”. |
| thingName:my\$1 | Consulto objetos com nomes que começam com "my". |
| thingName:\$1my | Consultas de coisas com nomes que terminam com "my". O uso de curingas à esquerda é limitado a um termo por consulta. As consultas que incluem um caractere curinga à esquerda têm um comprimento máximo de consulta de cem caracteres. |
| thingName:\$1my\$1 | Consultas de coisas que contêm a substring “my”. O uso de curingas à esquerda é limitado a um termo por consulta. As consultas que incluem um caractere curinga à esquerda têm um comprimento máximo de consulta de cem caracteres. |
| thingName:ab? | Consulto objetos com nomes que possuam "ab" e um caractere adicional (por exemplo: "aba", "abb", "abc" e assim por diante). |
| thingTypeName:aa | Consulto objetos que estejam associados ao tipo "aa". |
| thingGroupNames:a | Consulta objetos com um grupo de objetos principal ou um grupo de cobrança chamado "a". |
| thingGroupNames:a\$1 | Consulta objetos com um nome de grupo principal ou nome de grupo de cobrança que corresponda ao padrão "a\$1". |
| attributes.myAttribute:75 | Consulto objetos com um atributo chamado "myAttribute" que tem o valor 75. |
| attributes.myAttribute:[75 TO 80] | Consulto objetos com um atributo chamado "myAttribute" cujo valor esteja dentro de um intervalo numérico (75 a 80, inclusive). |
| attributes.myAttribute:\$175 TO 80] | Consulto objetos com um atributo chamado "myAttribute" cujo valor esteja dentro do intervalo numérico (>75 e <=80). |
| attributes.serialNumber:["abcd" TO "abcf"] | Consulto objetos com um atributo chamado "serialNumber" cujo valor esteja dentro de um intervalo de sequência alfanumérica. Essa consulta retornará objetos com um atributo "serialNumber" com valores "abcd", "abce" ou "abcf". |
| attributes.myAttribute:i\$1t | Consulto objetos com um atributo chamado "myAttribute" em que o valor seja 'i', seguido por qualquer número de caracteres, seguido por 't'. |
| attributes.attr1:abc AND attributes.attr2<5 NOT attributes.attr3>10 | Consulto objetos que combinam termos usando expressões boolianas. Essa consulta retorno objetos que tenham um atributo nomeado "attr1" com um valor "abc", um atributo chamado "attr2" que seja menor que 5 e um atributo chamado "attr3" que não seja maior que 10. |
| shadow.hasDelta:true | Consulto objetos com uma sombra sem nome que possui um elemento delta. |
| NOT attributes.model:legacy | Consulta de objetos em que o atributo denominado "modelo" não é "legado". |
| shadow.reported.stats.battery:\$170 TO 100\$1 (v2 OR v3) NOT attributes.model:legacy | Consulto objetos com o seguinte: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/example-queries.html) |
| shadow.reported.myvalues:2 | Consulto objetos onde a matriz `myvalues` na seção relatada da sombra contém um valor igual a 2. |
| shadow.reported.location:\$1 NOT shadow.desired.stats.battery:\$1 | Consulto objetos com o seguinte: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/example-queries.html) |
| shadow.name..hasDelta:true | Consulto objetos que tenham uma sombra com o nome fornecido e também um elemento delta. |
| shadow.name..desired.filament:\$1 | Consulto objetos que tenham uma sombra com o nome fornecido e também uma propriedade de filamento desejada. |
| shadow.name..reported.location:\$1 | Consulto objetos que tenham uma sombra com o nome fornecido e onde o atributo `location` exista na seção relatada da sombra nomeada. |
| connectivity.connected:true | Consulta todos os dispositivos conectados. |
| connectivity.connected:false | Consulta todos os dispositivos desconectados. |
| connectivity.connected:true AND connectivity.timestamp : [1557651600000 TO 1557867600000] | Consulta todos os dispositivos conectados com um registro de data/hora de conexão >= 1557651600000 e <= 1557867600000. Os registros de data/hora são expressos em milissegundos desde o epoch. |
| connectivity.connected:false AND connectivity.timestamp : [1557651600000 TO 1557867600000] | Consulta todos os dispositivos desconectados com um registro de data/hora de desconexão >= 1557651600000 e <= 1557867600000. Os registros de data/hora são expressos em milissegundos desde o epoch. |
| connectivity.connected:true AND connectivity.timestamp > 1557651600000 | Consulta todos os dispositivos conectados com um registro de data/hora de conexão > 1557651600000. Os registros de data/hora são expressos em milissegundos desde o epoch. |
| connectivity.connected:\$1 | Consulta todos os dispositivos com informações de conectividade presentes. |
| connectivity.disconnectReason:\$1 | Consulta todos os dispositivos com disconnectReason de conectividade presente. |
| connectivity.disconnectReason:CLIENT\$1INITIATED\$1DISCONNECT | Consulta todos os dispositivos desconectados devido a CLIENT\$1INITIATED\$1DISCONNECT. |
| deviceDefender.violationCount:[0 TO 100] | Consulto objetos com valor de contagem de violações do Device Defender que estejam dentro do intervalo numérico (0 a 100, inclusive). |
| deviceDefender..disconnectBehavior.inViolation:true | Consulto objetos que estejam em violação do comportamento disconnectBehavior, conforme definido no perfil de segurança device-SecurityProfile. Observe que inViolation:false não é uma consulta válida. |
| deviceDefender..disconnectBehavior.lastViolationValue.number>2 | Consultas sobre itens que violam o comportamento disconnectBehavior definido no dispositivo do perfil de segurança, SecurityProfile com um valor do último evento de violação maior que 2. |
| deviceDefender..disconnectBehavior.lastViolationTime>1634227200000 | Consultas sobre itens que violam o comportamento `disconnectBehavior` definido no dispositivo do perfil de segurança, SecurityProfile com um último evento de violação após um período especificado. |
| shadow.name.gps-tracker.reported.coordinates:geo\$1distance,47.6204,-122.3491,15.5km | Consultas sobre coisas que estão dentro da distância radial de 15,5 km das coordenadas de 47.6204,-122.3491. Essa sequência de caracteres de consulta se aplica a quando seus dados de localização são armazenados em uma sombra nomeada. |
| shadow.reported.coordinates:geo\$1distance,47.6204,-122.3491,15.5km | Consultas sobre coisas que estão dentro da distância radial de 15,5 km das coordenadas de 47.6204,-122.3491. Essa sequência de caracteres de consulta se aplica a quando seus dados de localização são armazenados em uma sombra clássica. |
# Exemplo de consultas de grupos de objetos
As consultas são especificadas em uma string de consulta usando uma sintaxe de consulta e passadas para a API [https://docs.aws.amazon.com/iot/latest/apireference/API_SearchIndex.html](https://docs.aws.amazon.com/iot/latest/apireference/API_SearchIndex.html). A tabela a seguir lista alguns exemplos de sequências de consulta.
| String de consulta | Resultado |
| --- | --- |
| abc | Consulta "abc" em qualquer campo. |
| thingGroupName:myGroupThingName | Consultas para um grupo de coisas com o nome "myGroupThingNome”. |
| thingGroupName:my\$1 | Consulta grupos de objetos com nomes que começam com "my". |
| thingGroupName:ab? | Consulta grupos de objetos com nomes que têm "ab" e um caractere adicional (por exemplo: "aba", "abb", "abc" e assim por diante). |
| attributes.myAttribute:75 | Consulta grupos de objetos com um atributo chamado "myAttribute" que tem o valor 75. |
| attributes.myAttribute:[75 TO 80] | Consulta grupos de objetos com um atributo chamado "myAttribute" cujo valor está dentro de um intervalo numérico (75 a 80, inclusive). |
| attributes.myAttribute:[75 TO 80] | Consulta grupos de objetos com um atributo chamado "myAttribute" cujo valor está dentro do intervalo numérico (>75 e <=80). |
| attributes.myAttribute:["abcd" TO "abcf"] | Consulta grupos de objetos com um atributo chamado "myAttribute" cujo valor está dentro de um intervalo de sequência alfanumérica. Essa consulta retornará grupos de objetos com um atributo "serialNumber" com valores "abcd", "abce" ou "abcf". |
| attributes.myAttribute:i\$1t | Consulta grupos de objetos com um atributo chamado "myAttribute" cujo valor é 'i', seguido por qualquer número de caracteres, seguido por 't'. |
| attributes.attr1:abc AND attributes.attr2<5 NOT attributes.attr3>10 | Consulta grupos de objetos que combinam termos usando expressões boolianas. Essa consulta retorna grupos de objetos que tenham um atributo chamado "attr1" com um valor "abc", um atributo chamado "attr2" que seja menor que 5 e um atributo chamado "attr3" que não seja maior que 10. |
| NOT attributes.myAttribute:cde | Consulta grupos de objetos onde o atributo chamado "myAttribute" não é "cde". |
| parentGroupNames:(myParentThingGroupName) | Consultas para grupos de coisas cujo nome do grupo principal corresponda a "myParentThingGroupName”. |
| parentGroupNames:(myParentThingGroupName OR myRootThingGroupName) | Consultas para grupos de coisas cujo nome do grupo principal corresponda a "myParentThingGroupName" ou "myRootThingGroupName”. |
| parentGroupNames:(myParentThingGroupNa\$1) | Consultas para grupos de coisas cujo nome do grupo principal começa com "myParentThingGroupNa”. |
# Indexação de dados de localização
Você pode usar a [indexação de frotas da AWS IoT](https://docs.aws.amazon.com//iot/latest/developerguide/iot-indexing.html) para indexar os últimos dados de localização enviados dos seus dispositivos e pesquisar dispositivos usando consultas geográficas. Esse atributo resolve casos de uso de monitoramento e gerenciamento de dispositivos, como rastreamento de localização e pesquisa de proximidade. A indexação de localização funciona de maneira semelhante a outros recursos de indexação de frotas e com configurações adicionais para especificar na [indexação de objetos](managing-fleet-index.md).
Os casos de uso comuns incluem: pesquisar e agregar dispositivos localizados dentro dos limites geográficos desejados, obter informações específicas da localização usando termos de consulta relacionados aos metadados e ao estado do dispositivo de fontes de dados indexadas, fornecer uma visão granular, como a filtragem de resultados para uma área geográfica específica, reduzir os atrasos de renderização nos mapas de monitoramento da frota e rastrear a localização do último dispositivo relatado, identificar dispositivos que estão fora dos limites desejados e gerar alarmes usando [métricas de frota.](iot-fleet-metrics.md) Para começar com indexação de localização e geoconsultas, consulte [Tutorial de inicialização](location-indexing-tutorial.md).
## Formatos de dados compatíveis
AWS IoT a indexação de frotas suporta os seguintes formatos de dados de localização:
1.
**Representação de texto bem conhecida de sistemas de referência de coordenadas**
Uma string que segue o formato [Informações geográficas: representação de texto bem conhecida de sistemas de referência de coordenadas](https://docs.ogc.org/is/12-063r5/12-063r5.html). Um exemplo pode ser `"POINT(long lat)"`.
1.
**Uma string que representa as coordenadas**
Uma string com o formato `"latitude, longitude"` ou `"longitude, latitude"`. Se você usar `"longitude, latitude"`, também deverá especificar `order` em `geoLocations`. Um exemplo pode ser `"41.12,-71.34"`.
1.
**Um objeto com chaves lat(latitude), lon(longitude)**
Esse formato se aplica à sombra clássica e à sombra nomeada. Chaves compatíveis: `lat`, `latitude`, `lon`, `long`, `longitude`. Um exemplo pode ser `{"lat": 41.12, "lon": -71.34}`.
1.
**Uma matriz que representa as coordenadas**
Uma matriz com o formato `[lat,lon]` ou`[lon,lat]`. Se você usar o formato `[lon,lat]`, que é o mesmo das coordenadas em [GeoJSON](https://geojson.org/) (aplicável à sombra clássica e à sombra nomeada), você também deve especificar `order` em `geoLocations`.
Um exemplo pode ser:
```
{
"location": {
"coordinates": [
**Longitude**,
**Latitude**
],
"type": "Point",
"properties": {
"country": "United States",
"city": "New York",
"postalCode": "*****",
"horizontalAccuracy": 20,
"horizontalConfidenceLevel": 0.67,
"state": "New York",
"timestamp": "2023-01-04T20:59:13.024Z"
}
}
}
```
## Como indexar dados de localização
As etapas a seguir mostram como atualizar a configuração de indexação dos dados de localização e usar consultas geográficas para pesquisar dispositivos.
1.
**Saiba onde seus dados de localização estão armazenados**
Atualmente, a indexação de frotas oferece suporte à indexação de dados de localização armazenados em sombras clássicas ou sombras nomeadas.
1.
**Usar formatos de dados de localização compatíveis**
Verifique se o formato dos dados de localização segue um dos [formatos de dados compatíveis](#location-indexing-format).
1.
**Atualizar configuração de indexação**
Se necessário, habilite a configuração de indexação de itens (registro). Você também deve ativar a indexação na sombra clássica ou na sombra nomeada que contenha seus dados de localização. Ao atualizar sua indexação de itens, você deve incluir seus dados de localização na configuração de indexação.
1.
**Criar e executar consultas geográficas**
Dependendo dos seus casos de uso, crie geoconsultas e execute-as para pesquisar dispositivos. A consulta geográfica que você compõe deve seguir a [Sintaxe da consulta](https://docs.aws.amazon.com//iot/latest/developerguide/query-syntax.html). É possível encontrar alguns exemplos em [Exemplo de consultas geográficas](#location-indexing-geoqueries).
## Atualizar a configuração da indexação de objeto
Para indexar dados de localização, atualize a configuração de indexação e inclua seus dados de localização. Dependendo de onde seus dados de localização estão, siga as etapas para atualizar sua configuração de indexação:
### Dados de localização armazenados em sombras clássicas
Se seus dados de localização estiverem armazenados em uma sombra clássica, você deverá definir `thingIndexingMode` como `REGISTRY_AND_SHADOW` e especificar seus dados de localização nos campos `geoLocations` (`name` e `order`) em [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html).
No exemplo de configuração de indexação a seguir, você especifica o caminho dos dados de localização `shadow.reported.coordinates` como `name` e `LonLat` como `order`.
```
{
"thingIndexingMode": "REGISTRY_AND_SHADOW",
"filter": {
"geoLocations": [
{
"name": "shadow.reported.coordinates",
"order": "LonLat"
}
]
}
}
```
+ `thingIndexingMode`
O modo de indexação controla se o Registro ou a sombra é indexado. Quando `thingIndexingMode` é definido como `OFF`, a indexação de itens é desativada.
Para indexar dados de localização armazenados em uma sombra clássica, você deve definir `thingIndexingMode` como `REGISTRY_AND_SHADOW`. Para obter mais informações, consulte [Modos de indexação de objetos](managing-index.md#index-mode).
+ `filter`
O filtro de indexação fornece seleções adicionais para sombras nomeadas e dados de localização geográfica. Para obter mais informações, consulte [Filtro de indexação](managing-index.md#thing-indexing-filter).
+ `geoLocations`
A lista de destinos de localização geográfica que você seleciona para indexar. O número máximo padrão de destinos de localização geográfica para indexação é `1`. Para aumentar o limite, consulte [Cotas de AWS IoT Device Management](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#fleet-indexing-limits).
+ `name`
O nome do campo de destino de localização geográfica. Um exemplo de valor de `name` pode ser o caminho dos dados de localização de sua sombra: `shadow.reported.coordinates`.
+ `order`
A ordem do campo de destino de localização geográfica. Valores válidos: `LatLon` e `LonLat`. `LatLon` significa latitude e longitude. `LonLat` significa longitude e latitude. Esse campo é opcional. O valor padrão é `LatLon`.
### Dados de localização armazenados em sombras nomeadas
Se seus dados de localização estiverem armazenados em uma sombra nomeada, defina `namedShadowIndexingMode` como `ON`, adicione seus nomes de sombra nomeados ao campo `namedShadowNames` em [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html) e especifique seu caminho de dados de localização no campo `geoLocations` em [https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html](https://docs.aws.amazon.com//iot/latest/apireference/API_IndexingFilter.html).
No exemplo de configuração de indexação a seguir, você especifica o caminho dos dados de localização `shadow.name.namedShadow1.reported.coordinates` como `name` e `LonLat` como `order`.
```
{
"thingIndexingMode": "REGISTRY",
"namedShadowIndexingMode": "ON",
"filter": {
"namedShadowNames": [
"namedShadow1"
],
"geoLocations": [
{
"name": "shadow.name.namedShadow1.reported.coordinates",
"order": "LonLat"
}
]
}
}
```
+ `thingIndexingMode`
O modo de indexação controla se o Registro ou a sombra é indexado. Quando `thingIndexingMode` é definido como `OFF`, a indexação de itens é desativada.
Para indexar dados de localização armazenados em uma sombra nomeada, você deve definir `thingIndexingMode` como `REGISTRY` (ou `REGISTRY_AND_SHADOW`). Para obter mais informações, consulte [Modos de indexação de objetos](managing-index.md#index-mode).
+ `filter`
O filtro de indexação fornece seleções adicionais para sombras nomeadas e dados de localização geográfica. Para obter mais informações, consulte [Filtro de indexação](managing-index.md#thing-indexing-filter).
+ `geoLocations`
A lista de destinos de localização geográfica que você seleciona para indexar. O número máximo padrão de destinos de localização geográfica para indexação é `1`. Para aumentar o limite, consulte [Cotas de AWS IoT Device Management](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#fleet-indexing-limits).
+ `name`
O nome do campo de destino de localização geográfica. Um exemplo de valor de `name` pode ser o caminho dos dados de localização de sua sombra: `shadow.name.namedShadow1.reported.coordinates`.
+ `order`
A ordem do campo de destino de localização geográfica. Valores válidos: `LatLon` e `LonLat`. `LatLon` significa latitude e longitude. `LonLat` significa longitude e latitude. Esse campo é opcional. O valor padrão é `LatLon`.
## Exemplo de consultas geográficas
Depois de concluir a configuração de indexação dos dados de localização, execute consultas geográficas para pesquisar dispositivos. Você também pode combinar suas consultas geográficas com outras cadeias de caracteres de consulta. Para obter mais informações, consulte [Sintaxe de consulta](query-syntax.md) e [Exemplo de consultas de objetos](example-queries.md).
**Consulta de exemplo 1**
Este exemplo pressupõe que os dados de localização estão armazenados em uma sombra nomeada `gps-tracker`. A saída desse comando é a lista de dispositivos que estão dentro da distância radial de 15,5 km do ponto central com coordenadas (47,6204,-122,3491).
```
aws iot search-index --query-string \
"shadow.name.gps-tracker.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km"
```
**Consulta de exemplo 2**
Este exemplo pressupõe que os dados de localização estão armazenados em uma sombra clássica. A saída desse comando é a lista de dispositivos que estão dentro da distância radial de 15,5 km do ponto central com coordenadas (47,6204,-122,3491).
```
aws iot search-index --query-string \
"shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km"
```
**Consulta de exemplo 3**
Este exemplo pressupõe que os dados de localização estão armazenados em uma sombra clássica. A saída desse comando é a lista de dispositivos que não estão conectados e estão fora da distância radial de 15,5 km do ponto central com coordenadas (47,6204,-122,3491).
```
aws iot search-index --query-string \
"connectivity.connected:false AND (NOT shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km)"
```
# Tutorial de inicialização
Este tutorial demonstra como usar a [indexação de frotas](iot-indexing.md) para [indexar seus dados de localização](location-indexing-geoquery.md). Para simplificar, você cria um objeto para representar seu dispositivo e armazena os dados de localização em uma sombra nomeada, atualiza a configuração de indexação do objeto para indexação de localização e executa exemplos de consultas geográficas para pesquisar dispositivos dentro de um limite radial.
Este tutorial leva cerca de 15 minutos para ser concluído.
**Topics**
+ [Pré-requisitos](#location-indexing-tutorial-prerequisites)
+ [Criar objeto e sombra](#location-indexing-create-resources)
+ [Atualizar a configuração da indexação de objeto](#location-indexing-update-configuration)
+ [Executar consulta geográfica](#location-indexing-run-geoquery)
## Pré-requisitos
+ Instale a versão mais recente da [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html).
+ Familiarize-se com [Indexação de localização e consultas geográficas](https://docs.aws.amazon.com/iot/latest/developerguide/location-indexing-geoquery.html), [Gerenciar indexação de objeto](https://docs.aws.amazon.com/iot/latest/developerguide/managing-index.html) e [Sintaxe de consulta](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html).
## Criar objeto e sombra
Você cria um objeto para representar seu dispositivo e uma sombra nomeada para armazenar seus dados de localização (coordenadas 47,61564,-122,33584).
1. Execute o comando apresentado a seguir para criar o que representa a bicicleta com o nome Bike-1. *Para obter mais informações sobre como criar algo usando AWS CLI, consulte [create-thing](https://docs.aws.amazon.com//cli/latest/reference/iot/create-thing.html) from Reference. *AWS CLI**
```
aws iot create-thing --thing-name "Bike-1" \
--attribute-payload '{"attributes": {"model":"OEM-2302-12", "battery":"35", "acqDate":"06/09/23"}}'
```
A saída desse comando pode ser semelhante à seguinte:
```
{
"thingName": "Bike-1",
"thingArn": "arn:aws:iot:us-east-1:123456789012:thing/Bike-1",
"thingId": "df9cf01d-b0c8-48fe-a2e2-e16cff6b23df"
}
```
1. Execute o comando a seguir para criar uma sombra nomeada para armazenar os dados de localização da Bike-1 (coordenadas 47.61564, -122.33584). Para obter mais informações sobre como criar uma sombra nomeada usando AWS CLI, consulte [update-thing-shadow](https://docs.aws.amazon.com//cli/latest/reference/iot-data/update-thing-shadow.html)em *AWS CLI**Referência*.
```
aws iot-data update-thing-shadow \
--thing-name Bike-1 \
--shadow-name Bike1-shadow \
--cli-binary-format raw-in-base64-out \
--payload '{"state":{"reported":{"coordinates":{"lat": 47.6153, "lon": -122.3333}}}}' \
"output.txt" \
```
Esse comando não retorna nenhuma saída. Para ver a sombra nomeada que você criou, você pode executar o comando [list-named-shadows-for-thing](https://docs.aws.amazon.com//cli/latest/reference/iot-data/list-named-shadows-for-thing.html) CLI.
```
aws iot-data list-named-shadows-for-thing --thing-name Bike-1
```
A saída desse comando pode ser semelhante à seguinte:
```
{
"results": [
"Bike1-shadow"
],
"timestamp": 1699574309
}
```
## Atualizar a configuração da indexação de objeto
Para indexar dados de localização, atualize sua configuração de indexação para incluir os dados de localização. Como seus dados de localização estão armazenados em uma sombra nomeada neste tutorial, defina `thingIndexingMode` como `REGISTRY` (com um requisito mínimo), defina `namedShadowIndexingMode` como `ON` e adicione seus dados de localização à configuração. Neste exemplo, você deve adicionar o nome da sombra nomeada e o caminho dos dados de localização da sombra para `filter`.
1. Execute o comando para atualizar sua configuração de indexação para indexação de localização.
```
aws iot update-indexing-configuration --cli-input-json '{
"thingIndexingConfiguration": { "thingIndexingMode": "REGISTRY",
"thingConnectivityIndexingMode": "OFF",
"deviceDefenderIndexingMode": "OFF",
"namedShadowIndexingMode": "ON",
"filter": {
"namedShadowNames": ["Bike1-shadow"],
"geoLocations":[{
"name":"shadow.name.Bike1-shadow.reported.coordinates"
}]
},
"customFields": [
{ "name":"attributes.battery",
"type":"Number"}] } }'
```
O comando não produz saída. Talvez seja necessário aguardar um instante até a atualização ser concluída. Para verificar o status, execute o comando da CLI [describe-index](https://docs.aws.amazon.com//cli/latest/reference/iot/describe-index.html). Se você vê `indexStatus` mostrar: `ACTIVE`, sua atualização de indexação de objeto está concluída.
1. Execute o comando para verificar a configuração de indexação. Esta etapa é opcional.
```
aws iot get-indexing-configuration
```
A saída poderá ser parecida com o seguinte:
```
{
"thingIndexingConfiguration": {
"thingIndexingMode": "REGISTRY",
"thingConnectivityIndexingMode": "OFF",
"deviceDefenderIndexingMode": "OFF",
"namedShadowIndexingMode": "ON",
"managedFields": [
{
"name": "shadow.name.*.hasDelta",
"type": "Boolean"
},
{
"name": "registry.version",
"type": "Number"
},
{
"name": "registry.thingTypeName",
"type": "String"
},
{
"name": "registry.thingGroupNames",
"type": "String"
},
{
"name": "shadow.name.*.version",
"type": "Number"
},
{
"name": "thingName",
"type": "String"
},
{
"name": "thingId",
"type": "String"
}
],
"customFields": [
{
"name": "attributes.battery",
"type": "Number"
}
],
"filter": {
"namedShadowNames": [
"Bike1-shadow"
],
"geoLocations": [
{
"name": "shadow.name.Bike1-shadow.reported.coordinates",
"order": "LatLon"
}
]
}
},
"thingGroupIndexingConfiguration": {
"thingGroupIndexingMode": "OFF"
}
}
```
## Executar consulta geográfica
Agora você atualizou sua configuração de indexação para incluir os dados de localização. Tente criar algumas consultas geográficas e executá-las para ver se você consegue obter os resultados de pesquisa desejados. Uma consulta geográfica deve seguir a [Sintaxe da consulta](query-syntax.md). Você pode encontrar alguns exemplos úteis de geoconsultas em [Exemplo de consultas geográficas](location-indexing-geoquery.md#location-indexing-geoqueries).
No comando de exemplo a seguir, você usa a consulta geográfica `shadow.name.Bike1-shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km` para pesquisar dispositivos que estão dentro da distância radial de 15,5 km do ponto central com coordenadas (47,6204, -122,3491).
```
aws iot search-index --query-string "shadow.name.Bike1-shadow.reported.coordinates:geo_distance,47.6204,-122.3491,15.5km"
```
Como você tem um dispositivo localizado nas coordenadas “lat”: 47.6153, “lon”: -122.3333, que fica a uma distância de 15,5 km do ponto central, você deve conseguir ver esse dispositivo (Bike-1) na saída. A saída poderá ser parecida com o seguinte:
```
{
"things": [
{
"thingName": "Bike-1",
"thingId": "df9cf01d-b0c8-48fe-a2e2-e16cff6b23df",
"attributes": {
"acqDate": "06/09/23",
"battery": "35",
"model": "OEM-2302-12"
},
"shadow": "{\"reported\":{\"coordinates\":{\"lat\":47.6153,\"lon\":-122.3333}},\"metadata\":{\"reported\":{\"coordinates\":{\"lat\":{\"timestamp\":1699572906},\"lon\":{\"timestamp\":1699572906}}}},\"hasDelta\":false,\"version\":1}"
}
]
}
```
Para obter mais informações, consulte [Indexação de dados de localização](location-indexing-geoquery.md).
# Métricas de frota
As métricas de frota são um recurso da [indexação de frotas](iot-indexing.md), um serviço gerenciado que permite indexar, pesquisar e agregar os dados de seus dispositivos. AWS IoT Você pode usar métricas de frota para monitorar o estado agregado dos dispositivos da sua frota [CloudWatch](https://console.aws.amazon.com/cloudwatch/)ao longo do tempo, incluindo a revisão da taxa de desconexão dos dispositivos da sua frota ou das alterações médias do nível da bateria em um período especificado.
Usando métricas de frota, você pode criar [consultas de agregação](index-aggregate.md) cujos resultados são continuamente emitidos [CloudWatch](https://console.aws.amazon.com/cloudwatch/)como métricas para analisar tendências e criar alarmes. Para tarefas de monitoramento, é possível especificar as consultas de agregação de diferentes tipos de agregação (**estatística**, **cardinalidade** e **percentual**). É possível salvar todas as suas consultas de agregação para criar métricas de frota para reutilização posterior.
# Tutorial de inicialização
Neste tutorial, você criará uma [métrica de frota](iot-fleet-metrics.md) para monitorar as temperaturas de seus sensores e detectar possíveis anomalias. Ao criar a métrica da frota, você define uma [consulta de agregação](index-aggregate.md) para detectar o número de sensores com temperaturas superiores a 80 graus Fahrenheit. Você especifica a consulta a ser executada a cada 60 segundos e os resultados da consulta são emitidos para CloudWatch, onde é possível visualizar o número de sensores que apresentam riscos potenciais de alta temperatura e definir alarmes. Para concluir este tutorial, você utilizará a [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html).
Neste tutorial, você aprenderá:
+ [Configuração](#fleet-metrics-tutorial-setup)
+ [Criação de métricas de frota](#fleet-metrics-tutorial-create)
+ [Exibir métricas em CloudWatch](#fleet-metrics-tutorial-view-data)
+ [Limpeza de recursos](#fleet-metrics-tutorial-delete-fleet-metrics)
Este tutorial leva cerca de 15 minutos para ser concluído.
## Pré-requisitos
+ Instale a versão mais recente da [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)
+ Familiarize-se com a [consulta de dados agregados](https://docs.aws.amazon.com/iot/latest/developerguide/index-aggregate.html)
+ Familiarize-se com o [uso de métricas da Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html)
## Configuração
Para usar as métricas de frota, ative a indexação de frotas. Para habilitar a indexação de frotas para suas objetos ou grupos de objetos com fontes de dados especificadas e configurações associadas, siga as instruções de [Gerenciar a indexação de objetos](managing-index.md#enable-index) e [Gerenciar a indexação de grupos de objetos](thinggroup-index.md#enable-group-index).
**Realização da configuração**
1. Execute o seguinte comando para ativar a indexação de frotas e especificar as fontes de dados a partir das quais pesquisar.
```
aws iot update-indexing-configuration \
--thing-indexing-configuration "thingIndexingMode=REGISTRY_AND_SHADOW,customFields=[{name=attributes.temperature,type=Number},{name=attributes.rackId,type=String},{name=attributes.stateNormal,type=Boolean}],thingConnectivityIndexingMode=STATUS" \
```
O exemplo de comando da CLI anterior permite que a indexação de frotas ofereça suporte à pesquisa de dados de registro, dados de sombra e status de conectividade de objetos usando o índice `AWS_Things`.
Pode levar alguns minutos para que a alteração de configuração seja concluída. Antes de criar métricas de frota, verifique se a indexação da frota está ativada.
Execute o seguinte comando da CLI para verificar se a indexação da frota foi ativada:
```
aws --region us-east-1 iot describe-index --index-name "AWS_Things"
```
Para obter mais informações, consulte [Habilitar a indexação de itens](managing-index.md#enable-index).
1. Execute o script bash a seguir para criar dez objetos e descrevê-las.
```
# Bash script. Type `bash` before running in other shells.
Temperatures=(70 71 72 73 74 75 47 97 98 99)
Racks=(Rack1 Rack1 Rack2 Rack2 Rack3 Rack4 Rack5 Rack6 Rack6 Rack6)
IsNormal=(true true true true true true false false false false)
for ((i=0; i < 10; i++))
do
thing=$(aws iot create-thing --thing-name "TempSensor$i" --attribute-payload attributes="{temperature=${Temperatures[@]:$i:1},rackId=${Racks[@]:$i:1},stateNormal=${IsNormal[@]:$i:1}}")
aws iot describe-thing --thing-name "TempSensor$i"
done
```
O script cria dez objetos para representar dez sensores. Cada objeto tem atributos de `temperature`, `rackId` e `stateNormal`, conforme descrito na seguinte tabela:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/fleet-metrics-get-started.html)
A saída desse script contém dez arquivos JSON. Um dos arquivos JSON tem a seguinte aparência:
```
{
"version": 1,
"thingName": "TempSensor0",
"defaultClientId": "TempSensor0",
"attributes": {
"rackId": "Rack1",
"stateNormal": "true",
"temperature": "70"
},
"thingArn": "arn:aws:iot:region:account:thing/TempSensor0",
"thingId": "example-thing-id"
}
```
Para obter mais informações, consulte [Criar um objeto](https://docs.aws.amazon.com/iot/latest/developerguide/thing-registry.html#create-thing).
## Criação de métricas de frota
**Para criar uma métrica de frota**
1. Execute o comando a seguir para criar uma métrica de frota chamada*high\$1temp\$1FM*. Você cria a métrica da frota para monitorar o número de sensores com temperaturas superiores a 80 graus Fahrenheit in. CloudWatch
```
aws iot create-fleet-metric --metric-name "high_temp_FM" --query-string "thingName:TempSensor* AND attributes.temperature >80" --period 60 --aggregation-field "attributes.temperature" --aggregation-type name=Statistics,values=count
```
--metric-name
Tipo de dados: string. O parâmetro `--metric-name` especifica o nome da métrica da frota. Neste exemplo, você está criando uma métrica de frota chamada *high\$1temp\$1FM*.
--query-string
Tipo de dados: string. O parâmetro `--query-string` especifica a string de consulta. Neste exemplo, a string de consulta significa consultar todas as coisas com nomes que começam com *TempSensor*e com temperaturas superiores a 80 graus Fahrenheit. Para obter mais informações, consulte [Sintaxe de consulta](query-syntax.md).
--period
Tipo de dados: inteiro. O parâmetro `--period` especifica o tempo, em segundos, até a recuperação dos dados agregados. Neste exemplo, está especificado que a métrica de frota criada por você recupera os dados agregados a cada 60 segundos.
--aggregation-field
Tipo de dados: string. O parâmetro `--aggregation-field` especifica o atributo a ser avaliado. Neste exemplo, o atributo a ser avaliado é a temperatura.
--aggregation-type
O parâmetro `--aggregation-type` especifica o resumo estatístico a ser exibido na métrica da frota. Para tarefas de monitoramento, é possível personalizar as propriedades das consultas de agregação conforme os diferentes tipos de agregação (**estatística**, **cardinalidade** e **percentual**). Neste exemplo, você especifica **contagem** para o tipo de agregação e **Estatísticas** para retornar a contagem de dispositivos que têm atributos que correspondem à consulta, em outras palavras, para retornar a contagem dos dispositivos com nomes começando com *TempSensor*e com temperaturas superiores a 80 graus Fahrenheit. Para obter mais informações, consulte [Consultar dados agregados](index-aggregate.md).
A saída desse comando é semelhante à seguinte:
```
{
"metricArn": "arn:aws:iot:region:111122223333:fleetmetric/high_temp_FM",
"metricName": "high_temp_FM"
}
```
**nota**
Pode levar um momento para que os pontos de dados sejam exibidos CloudWatch.
Para saber mais sobre a criação de uma métrica de frota, leia [Gerenciar métricas de frota](managing-fleet-metrics.md).
Se você não conseguir criar uma métrica de frota, leia [Solução de problemas de métricas de frota](fleet-indexing-troubleshooting.md#fleet-metrics-troubleshooting).
1. (Opcional) Execute o seguinte comando para descrever uma métrica de frota nomeada *high\$1temp\$1FM*:
```
aws iot describe-fleet-metric --metric-name "high_temp_FM"
```
A saída desse comando é semelhante à seguinte:
```
{
"queryVersion": "2017-09-30",
"lastModifiedDate": 1625249775.834,
"queryString": "*",
"period": 60,
"metricArn": "arn:aws:iot:region:111122223333:fleetmetric/high_temp_FM",
"aggregationField": "registry.version",
"version": 1,
"aggregationType": {
"values": [
"count"
],
"name": "Statistics"
},
"indexName": "AWS_Things",
"creationDate": 1625249775.834,
"metricName": "high_temp_FM"
}
```
## Veja as métricas da frota em CloudWatch
Depois de criar a métrica da frota, você pode visualizar os dados métricos em CloudWatch. Neste tutorial, você verá a métrica que mostra o número de sensores com nomes começando com *TempSensor*e com temperaturas superiores a 80 graus Fahrenheit.
**Para visualizar pontos de dados em CloudWatch**
1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. No CloudWatch menu no painel esquerdo, escolha **Métricas** para expandir o submenu e, em seguida, escolha **Todas as métricas**. Isso abrirá a página com uma metade superior para exibir o gráfico e uma metade inferior que contém quatro seções com guias.
1. A primeira seção com guias **Todas as métricas** lista todas as métricas que você pode visualizar em grupos. Escolha **Io TFleet Metrics**. Aqui estão todas as métricas da sua frota.
1. Na seção **Tipo de agregação** da guia **Todas as métricas**, selecione **Tipo de agregação** para visualizar todas as métricas de frota criadas por você.
1. Selecione a métrica da frota para exibir o gráfico à esquerda da seção **Tipo de agregação**. Você verá o valor *count* à esquerda do **nome da métrica**, e esse é o valor do tipo de agregação que você especificou na seção [Criar métricas de frota](#fleet-metrics-tutorial-create) deste tutorial.
1. Escolha a segunda guia, chamada **Métricas gráficas**, à direita da guia **Todas as métricas**, para ver a métrica da frota que você escolheu na etapa anterior.
Você deve conseguir ver um gráfico exibindo o número de sensores com temperaturas maiores que 80 graus Fahrenheit, como este:
![\[AWS IoT métricas da frota\]](http://docs.aws.amazon.com/pt_br/iot/latest/developerguide/images/fm-metric-in-cloudwatch.png)
**nota**
O atributo **Período** tem CloudWatch como padrão 5 minutos. É o intervalo de tempo entre os pontos de dados exibidos CloudWatch. É possível alterar a configuração de **Período** conforme as suas necessidades.
1. (Opcional) É possível definir um alarme métrico.
1. No CloudWatch menu no painel esquerdo, escolha **Alarmes** para expandir o submenu e, em seguida, escolha **Todos os** alarmes.
1. Na página **Alarmes**, selecione **Criar alarme** no canto superior direito. Siga as instruções de **Criar alarme** no console para criar um alarme adequado ao caso de uso. Para obter mais informações, consulte [Usando CloudWatch alarmes da Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html).
Para saber mais, leia [Como usar CloudWatch métricas da Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html).
Se você não conseguir ver os pontos de dados CloudWatch, leia [Solução de problemas nas métricas da frota](fleet-indexing-troubleshooting.md#fleet-metrics-troubleshooting).
## Limpeza
**Exclusão de métricas de frotas**
Deve-se usar o comando **delete-fleet-metric** da CLI para excluir as métricas de frota.
Execute o seguinte comando para excluir a métrica de frota nomeada *high\$1temp\$1FM*.
```
aws iot delete-fleet-metric --metric-name "high_temp_FM"
```
**Limpeza de objetos**
Deve-se usar o comando **delete-thing** da CLI para excluir objetos.
Execute o script a seguir para excluir as dez objetos criadas:
```
# Bash script. Type `bash` before running in other shells.
for ((i=0; i < 10; i++))
do
thing=$(aws iot delete-thing --thing-name "TempSensor$i")
done
```
**Para limpar as métricas em CloudWatch**
CloudWatch não suporta a exclusão de métricas. As métricas expiram baseadas em seus cronogramas de retenção. Para saber mais, [use as CloudWatch métricas da Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html).
# Gerenciar métricas de frota
Este tópico mostra como usar o AWS IoT console e gerenciar AWS CLI as métricas da sua frota.
**Topics**
+ [Gerenciar métricas de frota (console)](#managing-fleet-metrics-console)
+ [Gerenciar métricas de frota (CLI)](#managing-fleet-metrics-cli)
+ [Autorize a marcação de recursos de IoT](#managing-fleet-metrics-policy)
## Gerenciar métricas de frota (console)
As seções a seguir mostram como usar o AWS IoT console para gerenciar as métricas da sua frota. Habilite a indexação de frotas com as fontes de dados e configurações associadas antes de criar métricas de frota.
### Habilitar a indexação de frotas
Caso já tenha ativado a indexação de frotas, pule esta seção.
Caso não tenha ativado a indexação de frotas, siga estas instruções.
1. Abra seu AWS IoT console em [https://console.aws.amazon.com/iot/](https://console.aws.amazon.com/iot/).
1. No AWS IoT menu, escolha **Configurações**.
1. Para ver as configurações detalhadas, na página **Configurações**, role para baixo até a seção **Indexação de frotas**.
1. Para atualizar suas configurações de indexação de frotas, à direita da seção **Indexação de frotas**, selecione **Gerenciar indexação**.
1. Na página **Gerenciar indexação de frotas**, atualize suas configurações de indexação de frotas conforme suas necessidades.
+ **Configuração**
Para ativar a indexação de objetos, ative a **Indexação de objetos** e selecione as fontes de dados a partir das quais você deseja indexar.
Para ativar a indexação de grupos de objetos, ative a **Indexação de grupos de objetos**.
+ **Campos personalizados para agregação - *opcional***
Os campos personalizados são uma lista de pares de nomes de campos e tipos de campos.
Para adicionar um par de campos personalizado, selecione **Adicionar novo campo**. Insira um nome de campo personalizado, como `attributes.temperature`, e escolha um tipo de campo no menu **Tipo de campo**. Observe que o nome de um campo personalizado começa com `attributes.` e será salvo como um atributo para execução de [consultas de agregações de objetos](https://docs.aws.amazon.com/iot/latest/developerguide/index-aggregate.html).
Para atualizar e salvar a configuração, selecione **Atualizar**.
### Criação de uma métrica de frota
1. Abra seu AWS IoT console em [https://console.aws.amazon.com/iot/](https://console.aws.amazon.com/iot/).
1. No AWS IoT menu, escolha **Gerenciar** e, em seguida, escolha **Métricas da frota**.
1. Na página **Métricas de frota**, selecione **Criar métrica de frota** e conclua as etapas de criação.
1. Na etapa 1, **Configure as métricas da frota**
+ Na seção **Consulta**, digite uma string de consulta para especificar as objetos ou grupos de objetos com as quais deseja realizar a pesquisa agregada. A string de consulta consiste em um atributo e um valor. Em **Propriedades**, escolha o atributo desejado ou, caso ele não apareça na lista, digite o atributo no campo. Insira o valor depois de `:`. Um exemplo de string de consulta: `thingName:TempSensor*`. Para cada string de consulta inserida, pressione **enter** em seu teclado. Se você inserir diversas strings de consulta, especifique seu relacionamento escolhendo **e**, **ou**, **e não** ou **ou não** entre elas.
+ Em **Propriedades do relatório**, selecione **Nome do índice**, **Tipo de agregação** e **Campo de agregação** em suas respectivas listas. Em sequência, selecione os dados que você deseja agregar em **Selecionar dados**, onde você pode selecionar vários valores de dados.
+ Escolha **Próximo**.
1. Na etapa 2, **Especifique as propriedades métricas da frota**
+ No campo **Nome da métrica da frota**, digite um nome para a métrica da frota em criação.
+ No campo **Descrição - *opcional***, digite uma descrição para a métrica da frota em criação. Esse campo é opcional.
+ Nos campos **Horas** e **Minutos**, insira a hora (com que frequência) você deseja que a métrica da frota emita dados. CloudWatch
+ Escolha **Próximo**.
1. Na etapa 3, **Revise e crie**
+ Revise as configurações da etapa 1 e etapa 2. Para editar as configurações, escolha **Editar**.
+ Selecione **Criar métrica de frota**.
Após a criação com êxito, a métrica da frota estará listada na página **Métrica da frota**.
### Atualização de uma métrica de frota
1. Na página **Métrica da frota**, selecione a métrica da frota que você quer atualizar.
1. Na página **Detalhes** da métrica de frota, selecione **Editar**. Isso abre as etapas de criação nas quais você pode atualizar sua métrica de frota em qualquer uma das três etapas.
1. Depois de terminar de atualizar a métrica da frota, selecione **Atualizar métrica da frota**.
### Exclusão de uma métrica de frota
1. Na página **Métrica de frota**, selecione a métrica de frota que você quer excluir.
1. Na próxima página, que exibe detalhes da métrica da sua frota, selecione **Excluir**.
1. Na caixa de diálogo, digite o nome da métrica de frota para confirmar a exclusão.
1. Selecione **Excluir**. Essa etapa exclui permanentemente a métrica de frota.
## Gerenciar métricas de frota (CLI)
As seções a seguir mostram como usar o AWS CLI para gerenciar suas métricas de frota. Habilite a indexação de frotas com as fontes de dados e configurações associadas antes de criar métricas de frota. Para habilitar a indexação de frotas para suas objetos ou grupos de objetos siga as instruções de [Gerenciar a indexação de objetos](managing-index.md#enable-index) e [Gerenciar a indexação de grupos de objetos](thinggroup-index.md#enable-group-index).
### Criação de uma métrica de frota
Você pode usar o comando create-fleet-metric CLI para criar uma métrica de frota.
```
aws iot create-fleet-metric --metric-name "YourFleetMetricName" --query-string "*" --period 60 --aggregation-field "registry.version" --aggregation-type name=Statistics,values=sum
```
A saída deste comando possui o nome e o nome do recurso da Amazon (ARN) da sua métrica de frota. A saída será exibida como a seguir:
```
{
"metricArn": "arn:aws:iot:us-east-1:111122223333:fleetmetric/YourFleetMetricName",
"metricName": "YourFleetMetricName"
}
```
### Listagem de métricas de frota
Você pode usar o comando list-fleet-metric CLI para listar todas as métricas da frota em sua conta.
```
aws iot list-fleet-metrics
```
A saída deste comando possui todas as métricas de frota. A saída será exibida como a seguir:
```
{
"fleetMetrics": [
{
"metricArn": "arn:aws:iot:us-east-1:111122223333:fleetmetric/YourFleetMetric1",
"metricName": "YourFleetMetric1"
},
{
"metricArn": "arn:aws:iot:us-east-1:111122223333:fleetmetric/YourFleetMetric2",
"metricName": "YourFleetMetric2"
}
]
}
```
### Descrição de uma métrica de frota
Você pode usar o comando describe-fleet-metric CLI para exibir informações mais detalhadas sobre uma métrica de frota.
```
aws iot describe-fleet-metric --metric-name "YourFleetMetricName"
```
A saída do comando contém as informações detalhadas sobre a métrica de frota especificada. A saída será exibida como a seguir:
```
{
"queryVersion": "2017-09-30",
"lastModifiedDate": 1625790642.355,
"queryString": "*",
"period": 60,
"metricArn": "arn:aws:iot:us-east-1:111122223333:fleetmetric/YourFleetMetricName",
"aggregationField": "registry.version",
"version": 1,
"aggregationType": {
"values": [
"sum"
],
"name": "Statistics"
},
"indexName": "AWS_Things",
"creationDate": 1625790642.355,
"metricName": "YourFleetMetricName"
}
```
### Atualização de uma métrica de frota
Você pode usar o comando update-fleet-metric CLI para atualizar uma métrica de frota.
```
aws iot update-fleet-metric --metric-name "YourFleetMetricName" --query-string "*" --period 120 --aggregation-field "registry.version" --aggregation-type name=Statistics,values=sum,count --index-name AWS_Things
```
O comando update-fleet-metric não produz saída. Você pode usar o comando describe-fleet-metric CLI para ver o resultado.
```
{
"queryVersion": "2017-09-30",
"lastModifiedDate": 1625792300.881,
"queryString": "*",
"period": 120,
"metricArn": "arn:aws:iot:us-east-1:111122223333:fleetmetric/YourFleetMetricName",
"aggregationField": "registry.version",
"version": 2,
"aggregationType": {
"values": [
"sum",
"count"
],
"name": "Statistics"
},
"indexName": "AWS_Things",
"creationDate": 1625792300.881,
"metricName": "YourFleetMetricName"
}
```
### Exclusão de uma métrica de frota
Use o comando delete-fleet-metric CLI para excluir uma métrica de frota.
```
aws iot delete-fleet-metric --metric-name "YourFleetMetricName"
```
Esse comando não produz saída alguma se a exclusão obtiver êxito ou se você especificar uma métrica de frota inexistente.
Para obter mais informações, consulte [Solução de problemas de métricas de frota](fleet-indexing-troubleshooting.md#fleet-metrics-troubleshooting).
## Autorize a marcação de recursos de IoT
Para um controle melhor sobre as métricas da frota que você pode criar, modificar ou usar, você pode anexar tags às métricas da frota.
Para marcar as métricas de frota que você cria usando Console de gerenciamento da AWS ou AWS CLI, você deve incluir a `iot:TagResource` ação na sua política do IAM para conceder permissões ao usuário. Se sua política do IAM não incluir `iot:TagResource`, qualquer ação para criar uma métrica de frota com uma tag retornará um erro `AccessDeniedException`.
Para informações gerais sobre a marcação de recursos, consulte [Marcar seus recursos de AWS IoT](https://docs.aws.amazon.com//iot/latest/developerguide/tagging-iot.html).
### Exemplo de política do IAM
Consulte o seguinte exemplo de políticas do IAM que concedem permissões de marcação ao criar uma métrica da frota:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"iot:TagResource"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:*:*:fleetmetric/*"
]
},
{
"Action": [
"iot:CreateFleetMetric"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:*:*:index/*",
"arn:aws:iot:*:*:fleetmetric/*"
]
}
]
}
```
Para obter mais informações, consulte [Ações, recursos e chaves de condição do AWS IoT](https://docs.aws.amazon.com//service-authorization/latest/reference/list_awsiot.html).