PI Web API

Integração com o AVEVA PI System (antiga OSIsoft) pela PI Web API. Roda em processo no cms-api sobre HTTPS — sem SDK nativo, sem microserviço separado e sem dependência binária.

Apesar de falar HTTP, não é uma integração HTTP genérica: o CMS conhece o vocabulário do PI (tags, janelas de tempo, qualidade de amostra) e resolve por conta própria a parte mais chata do produto, que é o WebId.

Por que o WebId importa

Toda leitura e escrita na PI Web API endereça a tag por um WebId — um identificador opaco gerado pelo servidor, que muda se a tag for apagada e recriada, ou se o PI for migrado.

Uma integração HTTP crua guardaria esse WebId na URL da coleta. No dia em que a tag fosse recriada, toda configuração passaria a devolver 404 sem nenhuma pista do motivo, e alguém teria que reescrever URL por URL.

No CMS, o que você configura é o caminho da tag (\\PISRV01\FIC101.PV) — legível, estável e exportável. O WebId vive só num cache interno; quando o PI responde que ele não existe mais, o CMS re-resolve o caminho sozinho e repete a chamada. A configuração não quebra.

Conexão

Cadastre o servidor em Conexões Externas, na categoria Protocolos Industriais:

• URL Base — pode colar a raiz do site (https://pi.empresa.com); o sufixo /piwebapi é acrescentado quando faltar.
• Autenticação — Basic (usuário e senha), Bearer (token) ou Anônimo.
• Data Server padrão — o botão Buscar servidores lista os PI Data Archives visíveis para a credencial; clicar no nome preenche o campo. Com ele preenchido, as tags podem ser informadas só pelo nome (FIC101.PV) em vez do caminho completo.
• Validar certificado TLS — deixe ligado. Se o PI usa certificado autoassinado ou de CA interna, prefira colar a CA em Certificado da CA a desligar a validação.

O botão Testar Conexão valida em duas etapas — endereço/credencial e depois o Data Server — e reprova na hora um nome de servidor inexistente, em vez de deixar o erro aparecer só na primeira coleta.

Uma Aplicação com Keep Alive PI_WEB_API monitora o servidor no cockpit. O teste também acusa quando a PI Web API responde mas o Data Archive por trás está desconectado — situação em que nenhuma tag pode ser lida, mas o HTTP continua devolvendo 200.

Catálogo de tags

O ícone de catálogo na linha da conexão abre o navegador de tags: filtra por nome com o curinga * do próprio PI e mostra descrição, unidade de engenharia e tipo do ponto.

Ele é cache-first — abre instantâneo e funciona com o PI fora do ar, servindo o catálogo já conhecido. O botão Atualizar do PI força a ida ao servidor.

O mesmo navegador reaparece como seletor de tag nas telas de Coleta e Entrega: clicar numa tag já a adiciona com um alias sugerido.

Coleta — PI_WEB_API

Coleta agendada (pull), no mesmo agendador de HTTP_GET/SQL_SERVER — sem conexão persistente —, ou sob demanda, quando tem Parâmetros de Entrada. São quatro modos de leitura:

O payload gerado é {alias: valor} para cada tag configurada. Com Incluir metadados, ganha um bloco _meta com timestamp, qualidade e unidade por tag.

{
  "vazao": 128.4,
  "temperatura": 87.2,
  "_meta": {
    "vazao": { "timestamp": "2026-08-21T14:03:00Z", "boa": true, "unidade": "m3/h" }
  }
}

No modo Valor Atual, todas as tags são lidas numa única chamada (/streamsets/value) — vinte tags custam uma requisição, não vinte.

Varredura incremental de histórico

Início e Fim aceitam a sintaxe de tempo do PI (* = agora, *-1h = uma hora atrás) ou uma data ISO. Aceitam também {{ultimaExecucao}}, o placeholder do CMS:

Início: {{ultimaExecucao}}     Fim: *

Com isso, cada execução lê exatamente o histórico ainda não lido — sem repetir nem pular amostras entre ciclos. É a forma recomendada de trazer histórico contínuo do PI para uma fila.

Janela vinda de fora

Início, Fim e Intervalo também podem vir de quem aciona a Coleta. O bloco Parâmetros de Entrada (API) fica logo abaixo do modo de leitura, antes dos campos da janela: declare ali os nomes — por exemplo data_inicio e data_final — e use-os nos campos como {{data_inicio}} e {{data_final}}.

Início: {{data_inicio}}     Fim: {{data_final}}     Intervalo: {{passo}}

Com ao menos um parâmetro, a Coleta deixa o agendador e passa a rodar sob demanda: pela API dinâmica de Coleta, por um Gatilho ou por um agente de IA.

POST /api/collect/PI_DEMO_HIST/PI_DEMO_HIST_LEITURA
{ "data_inicio": "*-8h", "data_final": "*" }

Parâmetro que não vier na chamada usa o valor padrão dele; sem valor padrão, o campo cai no padrão do PI — *-1h no Início, * no Fim e 1h no Intervalo. Os campos aceitam também Variáveis ({{NOME}}), como o resto do CMS.

Assistente de tempo

Ninguém precisa decorar a sintaxe do PI. O ícone de calendário ao lado de Início, Fim e Intervalo abre um assistente que monta a expressão a partir de escolhas em linguagem comum:

No topo ficam os atalhos mais usados e, quando a Coleta tem Parâmetros de Entrada, um botão para cada um deles. Uma prévia mostra a expressão, o que ela significa e em que data e hora cairia se a coleta rodasse agora. O assistente abre já posicionado no valor atual do campo — e continua possível digitar direto no campo qualquer expressão que o PI aceite.

Emissão

Nos modos com janela de tempo, a Coleta pode gerar uma mensagem com a série inteira ou uma mensagem por amostra. A segunda foi pensada para o modo Interpolado, em que todas as tags compartilham os mesmos instantes; em Recorded, cada tag tem seus próprios instantes de gravação e o agrupamento raramente junta mais de uma tag por mensagem.

Qualidade e tags obrigatórias

Com Só qualidade boa ligado (padrão), amostras que o próprio PI marcou como ruins ou questionáveis são descartadas. Uma tag marcada obrigatória cuja única amostra veio ruim conta como “sem valor” e a coleta falha — em vez de propagar um número no qual o PI não confia.

Testar Leitura

O botão Testar Leitura executa a configuração do formulário, mesmo sem salvar. Enquanto o PI responde, o botão mostra os segundos passando; o resultado abre num popup quando a leitura termina:

• Resumo da consulta — as tags, o modo de leitura, o período já resolvido (a expressão que de fato foi ao PI), o intervalo, o tipo de resumo ou o teto de amostras, os parâmetros usados, quantos registros vieram (e quantos foram descartados por qualidade), quantas mensagens a Coleta geraria e quanto tempo levou. Uma tabela mostra, por tag, o caminho e quantos valores chegaram.
• Registros — cada valor lido: tag, data e hora, valor, unidade e qualidade, com o total de linhas. A tabela mostra os primeiros 500.
• Payload — o JSON exato que a Coleta colocaria na fila (as cinco primeiras mensagens).

Se a leitura funcionou mas a Coleta recusaria o resultado — uma tag obrigatória sem valor, por exemplo —, o popup mostra o erro e os registros que o PI devolveu, que é justamente o que ajuda a entender o porquê.

No teste não existe chamada de fora: cada Parâmetro de Entrada usa o seu valor padrão, e {{ultimaExecucao}} vale uma hora atrás.

Entrega — PI_WEB_API_WRITE

Grava valores em tags do PI a partir do payload da mensagem — o caminho de volta, do ERP/MES para o historiador.

O produtor da mensagem não conhece caminho de tag nenhum: ele envia um objeto plano com os aliases configurados, e a tela mostra o payload modelo pronto para copiar.

{ "setpoint": "*" }

• Timestamp — Agora carimba o instante do envio; Campo do payload usa um campo da própria mensagem, para quando o dado foi produzido antes de chegar ao CMS.
• Modo de escrita — Replace sobrescreve um valor já existente no mesmo instante, Insert grava mesmo havendo outro, No Replace só grava se ainda não houver nada naquele instante.

Como na Coleta, a gravação vai em lote numa chamada só, e apenas as tags presentes no payload são gravadas — uma tag ausente não é sobrescrita com nulo. Tags com valor padrão configurado caem para ele quando a mensagem não as traz.

Testar sem um PI real

A tela Simuladores traz uma aba PI Web API que imita o contrato REST do produto dentro do próprio CMS — sem porta nova e sem instalar nada.

• Tags com comportamento próprio (senoide, rampa, onda quadrada, ruído, fixo), que variam sozinhas no tempo e servem histórico de qualquer janela.
• A Conexão Externa “PI Simulator (interno)” é criada e mantida automaticamente: basta habilitar o simulador para já usá-lo numa Coleta.
• O botão Regenerar WebIds simula tags recriadas no PI, invalidando de uma vez todos os WebIds entregues — serve para conferir que o CMS re-resolve os caminhos sozinho, sem editar Coleta nenhuma.
• O simulador também recusa requisição sem o header X-Requested-With, como o PI real faz.
• Entende as mesmas expressões de tempo que o assistente gera: *, t, y, dias da semana, deslocamentos em sequência (t+6h+30m) e datas ISO.

Escopo desta versão

Esta versão endereça o PI Data Archive (PI Points). O Asset Framework (navegação por Elemento/Atributo) não entrou — o campo de endereço já se chama “caminho” e o cache é indexado por ele, então o AF cabe depois sem migração de dados.

Autenticação integrada Windows (NTLM/Kerberos) também está fora desta versão; use Basic ou Bearer.