> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/devices/metric-templates.md).
# Métricas
Encontre, crie e gira as métricas partilhadas que dão aos dados dos dispositivos nomes, unidades e tipos de dados consistentes em todo o Kilo.
Uma métrica diz ao Kilo o que significa uma leitura do dispositivo e como armazená-la. Ela combina uma **chave normalizada**, como `temperatura`, com uma unidade, tipo de valor e tipo de dados.
Os dois campos de tipo respondem a perguntas diferentes: **Tipo de dados** indica se a informação é telemetria, metadados do dispositivo ou um atributo personalizado; **Tipo** indica se o seu valor é armazenado como Float, Inteiro, String ou Booleano.
Esta definição partilhada permite que dispositivos de diferentes fabricantes usem os mesmos dashboards e regras. Um dispositivo pode enviar `temp_c` e outro pode enviar `t_celsius`; ao mapear ambas as chaves brutas para a `temperatura` métrica, o Kilo tem uma leitura consistente com que trabalhar.
## Abrir o catálogo de métricas
Aceda a **Dispositivos → Métricas**.
A lista contém todas as métricas disponíveis para a sua organização. Cada linha mostra a sua chave normalizada, unidade de medida, tipo de valor e tipo de dados.
Use os controlos acima da lista para encontrar uma métrica:
* **Pesquisar** corresponde à chave normalizada.
* **Todas as unidades** filtra por unidade e inclui métricas sem unidade. Selecione as unidades e clique **Aplicar**.
* **Todos os tipos** filtra por String, Inteiro, Float ou Booleano e aplica-se imediatamente.
* **Todos os tipos de dados** filtra por Telemetria, Metadados do dispositivo ou Atributos personalizados e aplica-se imediatamente.
* **Ordenar por** ordena as métricas por **Mais recentes** ou **Mais antigas**.
Os filtros de unidade, tipo e tipo de dados aceitam vários valores ao mesmo tempo.
As métricas criadas pela sua organização fornecem **Editar** e **Eliminar** ações. As métricas fornecidas pelo Kilo não, porque as suas definições são partilhadas entre implementações.
## Criar uma métrica
1. Aceda a **Dispositivos → Métricas**.
2. Clique em **Adicionar métrica**.
3. Preencha os quatro campos na caixa de diálogo **Adicionar Métrica** .
4. Clique em **Adicionar**.
### Tipo de dados
Escolha que tipo de informação a métrica representa:
| Tipo de dados | Use-a para | Exemplos |
| ---------------------------- | ----------------------------------------------------- | -------------------------------------------------------------- |
| **Telemetria** | Leituras que mudam ao longo do tempo | Temperatura, humidade, nível da bateria, pressão |
| **Metadados do dispositivo** | Informação que o dispositivo reporta sobre si próprio | Versão do firmware, revisão do hardware |
| **Atributos personalizados** | Informação que a sua organização acrescenta | Data de instalação, etiqueta do ativo, intervalo de manutenção |
Apenas métricas de Telemetria aparecem ao mapear leituras recebidas do dispositivo. Metadados do dispositivo e Atributos personalizados não são oferecidos como mapeamentos de telemetria.
### Tipo
Escolha como o Kilo armazena o valor:
| Tipo | Use-a para | Exemplos |
| ------------ | -------------------------- | -------------------------------- |
| **Float** | Números com casas decimais | `22.5`, `67.3`, `3.28` |
| **Inteiro** | Números inteiros | `85`, `-120`, `42` |
| **String** | Texto | `"aberto"`, `"em espera"` |
| **Booleano** | Verdadeiro ou falso | Movimento detetado, alarme ativo |
Os widgets de gráfico e os ecrãs Last Data no estilo medidor requerem uma métrica Inteiro ou Float. O ecrã Last Data **Valor** também pode mostrar valores de texto e Booleanos.
### Chave normalizada
A chave normalizada é o nome padrão da medição, independente do nome bruto enviado por um dispositivo.
Abrir **Chave normalizada** e selecione uma chave existente ou escolha **Criar uma nova chave normalizada**. Use um nome descritivo como `soil_moisture`, e não um nome específico do dispositivo como `sensor_3_value`. Nomes em minúsculas com underscores mantêm o catálogo consistente.
Cada chave normalizada pode pertencer apenas a uma métrica. Se a chave selecionada já estiver em uso, o formulário apresenta **Já existe uma métrica com esta chave normalizada**.
As chaves normalizadas são criadas, renomeadas e eliminadas a partir deste campo. As chaves fornecidas pelo Kilo não podem ser renomeadas nem removidas.
### Unidade de medida
Selecione a unidade apresentada ao lado do valor, como °C, %, lx ou mV. Escolha uma unidade existente ou selecione **Criar uma nova unidade** e introduza o símbolo exatamente como deve aparecer.
É necessária uma unidade para Telemetria. É opcional para Metadados do dispositivo e Atributos personalizados, onde valores como uma versão de firmware ou etiqueta de ativo podem não ter unidade.
As unidades são criadas, renomeadas e eliminadas a partir deste campo. As unidades fornecidas pelo Kilo não podem ser renomeadas nem removidas.
## Editar uma métrica
As métricas são partilhadas por toda a sua organização, não configuradas separadamente para cada dispositivo. Editar uma métrica altera a definição para todos os dispositivos mapeados para ela.
1. Encontre a métrica em **Dispositivos → Métricas**.
2. Clique em **Editar**.
3. Atualize os campos obrigatórios.
4. Clique em **Guardar**.
5. Revise a confirmação que descreve o efeito em toda a organização e confirme a alteração.
Se apenas um dispositivo precisar de uma definição diferente, crie uma nova métrica e remapeie esse dispositivo em vez de editar a métrica partilhada.
## Eliminar uma métrica
Clique em **Eliminar** numa métrica criada pela sua organização e confirme a ação.
O Kilo recusa eliminar uma métrica que ainda esteja mapeada para um dispositivo. Remova o mapeamento de todos os dispositivos que a utilizam e tente novamente.
## Mapear uma leitura do dispositivo para a métrica
Criar uma métrica não a liga automaticamente a um dispositivo. Abra o **Métricas** separador do dispositivo e mapeie a chave bruta enviada pelo dispositivo para a métrica normalizada.
Depois de vários tipos de dispositivos mapearem as suas chaves de temperatura brutas para `temperatura`, o mesmo widget de dashboard, regra ou consulta pode usar todas elas sem lógica específica do fabricante.
## Resolução de problemas
| Problema | O que verificar |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Está em falta uma métrica num gráfico ou num ecrã Last Data no estilo medidor | Confirme que o seu **Tipo** é Inteiro ou Float e que o dispositivo envia um valor numérico. |
| Está em falta uma métrica num mapeamento de dispositivo | Confirme que o seu **Tipo de dados** é Telemetria. |
| Não é possível selecionar uma chave normalizada | Outra métrica pode já estar a usá-la. Pesquise essa chave no catálogo. |
| Editar e Eliminar não estão disponíveis | A métrica, chave ou unidade foi fornecida pelo Kilo e não pode ser alterada. |
| A eliminação é recusada | Remova a métrica de todos os mapeamentos de dispositivos antes de a eliminar. |
## Ver também
* [Registar Dispositivos](/kilo-docs-pt/kilo-iot-server/devices/registering-devices.md) — mapear dados brutos do dispositivo durante o registo
* [Gestão de dispositivos](/kilo-docs-pt/kilo-iot-server/devices/device-management.md) — alterar mapeamentos num dispositivo existente
* [Widget de Gráfico](/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets/chart-widget.md) — apresentar métricas numéricas ao longo do tempo
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/devices/metric-templates.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
