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á.
# Usar funções temporais em expressões de fórmula
Use funções temporais para retornar valores com base em carimbos de data/hora dos pontos de dados.
## Usar funções temporais em métricas
Apenas em [métricas](metrics.md), você pode usar as seguintes funções que retornam valores com base em a função de horas dos pontos de dados:
Os argumentos da função temporal devem ser propriedades do modelo de ativo local ou expressões aninhadas. Isso significa que você não pode usar propriedades de modelos de ativos filho em funções temporais.
Você pode usar expressões aninhadas em funções temporais. Ao usar expressões aninhadas, as seguintes regras se aplicam:
+ Cada argumento pode ter apenas uma variável.
Por exemplo, `latest( t*9/5 + 32 )` é suportada.
+ Os argumentos não podem ser funções de agregação.
Por exemplo, `first( sum(x) )` não é suportada.
| Função | Description |
| --- | --- |
| `first(x)` | Retorna o valor da variável fornecida com o primeiro a função de hora ao longo do intervalo de tempo atual. |
| `last(x)` | Retorna o valor da variável fornecida com o a função de hora mais recente ao longo do intervalo de tempo atual. |
| `earliest(x)` | Retorna o último valor da variável fornecida antes do início do intervalo de tempo atual.
Se a propriedade de entrada tiver pelo menos um ponto de dados em seu histórico, esta função calcula um ponto de dados para cada intervalo de tempo. Para mais detalhes, consulte [time-range-defintion](#time-range-def). |
| `latest(x)` | Retorna o último valor da variável fornecida com o último carimbo de data/hora antes do fim do intervalo de tempo atual.
Se a propriedade de entrada tiver pelo menos um ponto de dados em seu histórico, esta função calcula um ponto de dados para cada intervalo de tempo. Para mais detalhes, consulte [time-range-defintion](#time-range-def). |
| `statetime(x)` | Retorna a quantidade de tempo em segundos que as variáveis fornecidas são positivas ao longo do intervalo de tempo atual. É possível usar as [funções comparativas](expression-comparison-functions.md) para criar uma propriedade de transformação para a função `statetime` consumir.
Por exemplo, se tiver uma propriedade `Idle` que seja `0` ou `1`, você poderá calcular o tempo ocioso por intervalo de tempo com esta expressão: `IdleTime = statetime(Idle)`. Para obter mais informações, consulte o [exemplo de cenário de statetime](#statetime-example).
Essa função não é compatível com as propriedades de métrica como variáveis de entrada.
Se a propriedade de entrada tiver pelo menos um ponto de dados em seu histórico, esta função calcula um ponto de dados para cada intervalo de tempo. |
| `TimeWeightedAvg(x, [interpolation])` | Retorna a média dos dados de entrada ponderada com intervalos de tempo entre os pontos.Consulte [Parâmetros de funções ponderado no tempo](#timeweighted-parameter) para obter detalhes sobre cálculos e intervalos.
O argumento opcional `interpolaton` deve ser uma constante de string:[See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/iot-sitewise/latest/userguide/expression-temporal-functions.html) |
| `TimeWeightedStDev(x, [algo])` | Retorna o desvio padrão dos dados de entrada ponderados com intervalos de tempo entre os pontos.
Consulte [Parâmetros de funções ponderado no tempo](#timeweighted-parameter) para obter detalhes sobre cálculos e intervalos.
O cálculo usa o algoritmo de computação Último Transporte Observado para intervalos entre pontos de dados. Nessa abordagem, o ponto de dados é calculado como o último valor observado até o próximo a função de hora de ponto de dados de entrada. O peso é calculado como intervalo de tempo em segundos entre pontos de dados ou limites de intervalo.
O argumento opcional `algo` deve ser uma constante de string:[See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/iot-sitewise/latest/userguide/expression-temporal-functions.html)
As fórmulas a seguir são usadas para computação onde:[See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/iot-sitewise/latest/userguide/expression-temporal-functions.html)
Equação para o desvio padrão populacional:
Equação para desvio padrão de frequência: |
O diagrama a seguir mostra como AWS IoT SiteWise computa as funções temporais`first`,`last`,`earliest`, e`latest`, em relação ao intervalo de tempo atual.
**nota**
O intervalo de tempo para `first(x)`, `last(x)` é (início da janela atual, fim da janela atual).
O intervalo de tempo para `latest(x)` é (início do tempo, fim da janela atual).
O intervalo de tempo para `earliest(x)` é (início do tempo, fim da janela anterior).
**Parâmetros de funções ponderadas pelo tempo**
As funções ponderadas pelo tempo calculadas para a janela agregada levam em consideração o seguinte:
+ Pontos de dados dentro da janela
+ Intervalos de tempo entre pontos de dados
+ Último ponto de dados antes da janela
+ Primeiro ponto de dados após a janela (para alguns algoritmos)
**Termos:**
+ **Ponto de dados ruim** — qualquer ponto de dados com qualidade inadequada ou valor não numérico. Isso não é considerado no cálculo do resultado de uma janela.
+ **Intervalo ruim** — intervalo após um ponto de dados inválido. O intervalo antes do primeiro ponto de dados conhecido também é considerado um intervalo ruim.
+ **Bom ponto de dados** — qualquer ponto de dados com boa qualidade e valor numérico.
**nota**
AWS IoT SiteWise só consome dados `GOOD` de qualidade quando calcula transformações e métricas. Ele ignora os pontos de dados `UNCERTAIN` e `BAD`.
O intervalo antes do primeiro ponto de dados conhecido é considerado um **intervalo ruim**. Consulte [Tutoriais de expressão de fórmulas](expression-tutorials.md) para obter mais informações.
O intervalo após o último ponto de dados conhecido continua indefinidamente, e afeta todas as janelas seguintes. Quando um novo ponto de dados chega, a função recalcula o intervalo.
Seguindo as regras acima, o resultado agregado da janela é calculado e limitado aos limites da janela. Por padrão, a função só envia o resultado da janela se a janela inteira tiver um **bom intervalo**.
Se o **intervalo bom** da janela for menor que seu comprimento, a função não enviará a janela.
Quando os pontos de dados que afetam o resultado da janela mudam, a função recalcula a janela, mesmo que os pontos de dados estejam fora da janela.
Se a propriedade de entrada tiver pelo menos um ponto de dados em seu histórico e um cálculo for sido iniciado, a função calculará as funções agregadas ponderadas pelo tempo para cada intervalo de tempo.
**Example Exemplo de cenário de statetime**
Considere um exemplo em que você tem um ativo com as seguintes propriedades:
+ `Idle` – medida `0` ou `1`. Quando o valor é `1`, a máquina está ociosa.
+ `Idle Time` – métrica que usa a fórmula `statetime(Idle)` para calcular a quantidade de tempo em segundos na qual a máquina está ociosa, por intervalo de 1 minuto.
A propriedade `Idle` tem os pontos de dados a seguir:
| | | | | | |
| --- |--- |--- |--- |--- |--- |
| a função de hora | 14:00:00 | 14:00:30 | 14:01:15 | 14:02:45 | 14:04:00 |
| Idle | 0 | 1 | 1 | 0 | 0 |
AWS IoT SiteWise calcula a `Idle Time` propriedade a cada minuto a partir dos valores de`Idle`. Depois que esse cálculo for concluído, a propriedade `Idle Time` terá os seguintes pontos de dados.
| | | | | | |
| --- |--- |--- |--- |--- |--- |
| a função de hora | 14:00:00 | 14:01:00 | 14:02:00 | 14:03:00 | 14:04:00 |
| Idle Time | N/A | 30 | 60 | 45 | 0 |
AWS IoT SiteWise executa os seguintes cálculos `Idle Time` no final de cada minuto.
+ Às 14:00 (para 13:59 a 14:00)
+ Não há dados para `Idle` antes das 14:00, portanto nenhum ponto de dados é calculado.
+ Às 14:01 (para 14:00 a 14:01)
+ Às 14:00:00, a máquina está ativa (`Idle` é `0`).
+ Às 14:00:30, a máquina está ociosa (`Idle` é `1`).
+ `Idle` não muda novamente antes do final do intervalo às 14:01:00, de maneira que `Idle Time` são 30 segundos.
+ Às 14:02 (para 14:01 a 14:02)
+ Às 14:01:00, a máquina está ociosa (de acordo com o último ponto de dados às 14:00:30).
+ Às 14:01:15, a máquina ainda está ociosa.
+ `Idle` não muda novamente antes do final do intervalo às 14:02:00, de maneira que `Idle Time` são 60 segundos.
+ Às 14:03 (para 14:02 a 14:03)
+ Às 14:02:00, a máquina está ociosa (de acordo com o último ponto de dados às 14:01:15).
+ Às 14:02:45, a máquina está ativa.
+ `Idle` não muda novamente antes do final do intervalo às 14:03:00, de maneira que `Idle Time` são 45 segundos.
+ Às 14:04 (para 14:03 a 14:04)
+ Às 14:03:00, a máquina está ativa (de acordo com o último ponto de dados às 14:02:45).
+ `Idle` não muda novamente antes do final do intervalo às 14:04:00, de maneira que `Idle Time` são 0 segundos.
**Example Exemplo TimeWeightedAvg e TimeWeightedStDev cenário**
As tabelas a seguir fornecem exemplos de entradas e saídas para essas métricas de janela de um minuto: `Avg(x), TimeWeightedAvg(x), TimeWeightedAvg(x, "linear"), stDev(x), timeWeightedStDev(x), timeWeightedStDev(x, 'p')`
Exemplo de entrada para janela agregada de um minuto:
Todos esses pontos de dados têm qualidade `GOOD`.
| | |
| --- |--- |
| 03:00:00 | 4,0 |
| 03:01:00 | 2,0 |
| 03:01:10 | 8.0 |
| 03:01:50 | 20.0 |
| 03:02:00 | 14.0 |
| 03:02:05 | 10.0 |
| 03:02:10 | 3.0 |
| 03:02:30 | 20.0 |
| 03:03:30 | 0.0 |
Saída de resultados agregados:
Nenhum — resultado não produzido para esta janela.
| Hora | `Avg(x)` | `TimeWeightedAvg(x)` | `TimeWeightedAvg(X, "linear")` | `stDev(X)` | `timeWeightedStDev(x)` | `timeWeightedStDev(x, 'p')` |
| --- | --- | --- | --- | --- | --- | --- |
| 3:00:00 | 4 | Nenhum | Nenhum | 0 | Nenhum | Nenhum |
| 3:01:00 | 2 | 4 | 3 | 0 | 0 | 0 |
| 3:02:00 | 14 | 9 | 13 | 6 | 5.430610041581775 | 5.385164807134504 |
| 3:03:00 | 11 | 13 | 12.875 | 8.54400374531753 | 7.724054437220943 | 7.659416862050705 |
| 3:04:00 | 0 | 10 | 2,5 | 0 | 10.084389681792215 | 10 |
| 3:05:00 | Nenhum | 0 | 0 | Nenhum | 0 | 0 |
## Usar funções temporais em transformações
Somente em [transformações](transforms.md), você pode usar a função `pretrigger()` para recuperar o valor de qualidade `GOOD` de uma variável antes da atualização da propriedade que iniciou o cálculo da transformação atual.
Considere um exemplo em que um fabricante usa AWS IoT SiteWise para monitorar o status de uma máquina. O fabricante usa as seguintes medidas e transformações para representar o processo:
+ Uma medida `current_state`, que pode ser 0 ou 1.
+ Se a máquina estiver no estado de limpeza, `current_state` é igual a 1.
+ Se a máquina estiver no estado de fabricação, `current_state` é igual a 1.
+ Uma transformação `cleaning_state_duration` é igual a `if(pretrigger(current_state) == 1, timestamp(current_state) - timestamp(pretrigger(current_state)), none)`. Essa transformação retorna há quanto tempo a máquina está no estado de limpeza em segundos, no formato Unix epoch. Para obter mais informações, consulte [Usar funções condicionais em expressões de fórmula](expression-conditional-functions.md) e a função [a função de hora(s)](expression-date-and-time-functions.md).
Se a máquina permanecer no estado de limpeza por mais tempo do que o esperado, o fabricante poderá investigar a máquina.
Você também pode usar a função `pretrigger()` em transformações multivariadas. Por exemplo, você têm duas medidas, chamadas `x` e `y`, e uma transformação, `z`,igual a `x + y + pretrigger(y)`. A tabela a seguir mostra os valores para `x`, `y` e `z` das 9:00 às 9:15.
**nota**
Este exemplo pressupõe que os valores das medições cheguem em ordem cronológica. Por exemplo, o valor de `x` para 09:00 chega antes do valor de `x` para 09:05.
Se os pontos de dados das 9:05 chegarem antes dos pontos de dados das 9:05, `z` não será calculado às 9:05.
Se o valor de `x` para 9:05 chegar antes do valor de `x` para 09:00 e os valores de `y` chegarem cronologicamente, `z` será igual a `22 = 20 + 1 + 1` às 9:05
| | 09:00 | 09:05 | 09:10 | 09:15 |
| --- | --- | --- | --- | --- |
| `x` | 10 | 20 | | 30 |
| `y` | 1 | 2 | 3 | |
| `z = x + y + pretrigger(y)` | `y` não recebe nenhum ponto de dados antes das 09:00. Portanto, `z` não é calculado às 09:00. | 23 = 20 \+ 2 \+ 1
`pretrigger(y)` é igual a 1. | 25 = 20 \+ 3 \+ 2
`x` não recebe um novo ponto de dados. `pretrigger(y)` é igual a 2. | 36 = 30 \+ 3 \+ 3
`y` não recebe um novo ponto de dados. Portanto, `pretrigger(y)` é igual a 3 às 09:15. |