# AVEVA PI

> Referência do driver AVEVA PI: PI Web API sobre HTTPS, autenticação por token bearer ou Basic, endereçamento de AF e de PI point, leituras e escritas.

O driver AVEVA PI lê e escreve um **AVEVA PI System** pelo **PI Web API**,
a interface REST do sistema (JSON sobre HTTP). É um driver em modo cliente (**o Ganter
Lab conecta ao serviço PI Web API**) e o transporte é **HTTPS por
padrão**: o driver põe as credenciais do dispositivo em toda requisição que faz, então
uma conexão sem criptografia as publicaria. O HTTP simples existe apenas como escolha explícita
por dispositivo.

Uma tag endereça um **atributo AF**, um **PI point** ou um stream cru do PI Web API,
e lê o valor de snapshot (atual) dele.

## Campos de conexão {#connection-fields}

| Campo | O que é | Formato | Padrão |
|---|---|---|---|
| Host | O nome de host ou endereço IP do servidor PI Web API. Dá para colar o endereço inteiro (`https://pi-host/piwebapi`): o `https://` ou `http://` na frente ajusta o transporte mais abaixo e sai, uma porta vai para o campo da porta e o caminho para o caminho do recurso. | Nome de host ou IP | vazio |
| Porta | A porta TCP do serviço. Um dispositivo novo a deixa vazia, e um campo vazio significa a porta em que o transporte escolhido responde, 443 por HTTPS e 80 em claro: o campo mostra essa porta em cinza e acompanha a escolha do transporte, que é também como se lê um dispositivo salvo com 0. | 1 a 65535, ou vazio | vazio |
| Caminho do recurso | O caminho da raiz de serviço anexado à autoridade. Em branco, ou uma `/` sozinha, significa a raiz padrão do PI Web API, `piwebapi`. Qualquer outro caminho é o caminho que o driver abre, exatamente como digitado: um serviço publicado atrás de um proxy reverso em `/pi` é alcançado em `/pi`, e nada é anexado a ele. Escreva o caminho inteiro de que um navegador precisaria, `piwebapi` incluído onde o serviço ainda responde ali. | texto de caminho | em branco (= `piwebapi`) |
| Enviar por HTTP simples | Rebaixa este dispositivo de HTTPS para HTTP em claro. Desmarcado significa HTTPS, o transporte normal do PI Web API. O painel declara a consequência: em HTTP simples, o token bearer ou a senha é enviado sem criptografia em toda requisição. Use isso só num PI Web API que não responde em nenhum outro transporte. | ligado / desligado | desligado |
| Usuário | Conta para autenticação **HTTP Basic**, usada só quando nenhum token bearer está definido. Vazio (e sem token) deixa as requisições anônimas. | Texto livre | vazio |
| Senha | A senha que acompanha o usuário. Protegida em repouso por usuário do Windows; um segredo digitado sob outra conta do Windows aparece como ilegível e precisa ser digitado de novo. | Texto livre | vazio |
| Token bearer | Um token enviado como `Authorization: Bearer …` em toda requisição. Quando definido, ele **prevalece sobre** o par usuário e senha. Protegido em repouso do mesmo jeito. | Texto do token | vazio |

Ao conectar, o driver verifica a raiz de serviço (HEAD, recorrendo a GET). Em
HTTPS, o certificado TLS do serviço é aceito quando o Windows confia nele, ou quando você
aprovou exatamente esse certificado em [Acesso a equipamentos](#equipment-access), na página
deste driver. O intervalo de leitura é configurável: o padrão do dispositivo (1000 ms) vale
para toda tag que não declare o próprio.

## Preparar o PI Web API {#prepare-pi-web-api}

O driver entra com usuário e senha pelo HTTP Basic, ou com um token bearer. O PI Web API vem
com o Kerberos como único método de autenticação, e o driver não fala Kerberos, então um
serviço recém-instalado costuma recusar a estação até que uma destas coisas seja feita no
servidor do PI Web API:

| Caminho | Onde se define | Depois |
| --- | --- | --- |
| Autenticação Basic | PI Web API Admin Utility, página Authentication Options: marque Basic e aplique. Ou PI System Explorer, banco Configuration, o elemento System Configuration em OSIsoft > PI Web API > o nome da instância: acrescente Basic ao atributo AuthenticationMethods e faça o check-in da mudança. Reinicie o serviço do PI Web API. | Usuário e Senha no cartão Conexão do dispositivo levam uma conta do Windows que o PI System aceite; uma conta de domínio se escreve DOMINIO\usuario |
| Token bearer | PI Web API configurado com o AVEVA Identity Manager (autenticação Bearer) | O token vai no campo Token bearer do dispositivo |

Quando o serviço responde 401 sem oferecer o Basic, a página do dispositivo diz isso, com
estes passos, no lugar do erro em inglês do driver; quando ele oferece o Basic e recusa a
conta que o dispositivo enviou, a página diz que o usuário ou a senha foi recusado e aponta
o cartão Conexão. Qualquer um dos avisos some sozinho quando o serviço responde. O registro
e o agente leem os mesmos passos. Um token bearer que o serviço recusa é dito nas palavras do
próprio driver.

## Endereçamento da tag {#tag-addressing}

O campo **Caminho PI** da tag aceita quatro formas:

| Forma | Se parece com | Como é resolvida |
|---|---|---|
| Caminho de atributo AF | `\\AFServer\Database\Element\SubElement\|Attribute` | Consultado uma vez por `attributes?path=…` para obter o WebId do atributo |
| Caminho de PI point | `\\PIServer\TagName` | Consultado uma vez por `points?path=…` para obter o WebId do ponto |
| WebId | A própria cadeia opaca do WebId | Usado diretamente (reconhecido como um símbolo longo sem `\`, `\|` nem `/`) |
| URL relativa | `streams/{webId}/value`, `streamsets/…`, `attributes?…`, `points?…` | Enviada como está, sob a raiz de serviço |

As consultas de caminho ficam em cache por 12 horas, então a leitura cíclica em regime não as
repete. Nas três primeiras formas, a leitura busca com GET o **valor de snapshot** do stream
(`streams/{webId}/value`) e extrai o campo `Value` do JSON; uma URL relativa é
lida literalmente, então aponte-a para um endpoint que responda com um documento de valor. O
resultado é convertido para o tipo de dado declarado da tag.

O veredito do próprio arquivo sobre a amostra é lido junto. Um valor que o arquivo marca
como **não bom**, como **questionável** ou como **substituído** (um número digitado à
mão, e não medido) não é uma leitura do equipamento, então não é
publicado como tal: a tag vai a qualidade ruim e o motivo diz qual dos
três casos era. O mesmo acontece quando a resposta não carrega valor, ou responde com
um estado digital em vez de um valor único, caso em que o nome do estado faz parte
do motivo. Nada é inventado no lugar deles, e nenhum documento chega como se
fosse a medição.

Uma leitura que o PI Web API recusa (um status fora da faixa de sucesso, como uma conta
sem acesso de leitura ao ponto) também vai a qualidade ruim, e o motivo nomeia o status e
o que o serviço disse junto (`HTTP 403 Forbidden: …`). Um caminho que o serviço não conhece
diz isso, nomeando o caminho. Um endereço vazio, um endereço em nenhuma das quatro formas e uma
resposta que não se lê como o tipo declarado também dão o motivo. Um serviço que não responde
nada é a conexão do dispositivo falhando: o dispositivo relata isso e reconecta, e as tags dele
apontam para ele.

Exemplos:

- `\\PI-SRV01\FURNACE.TEMP`, um PI point clássico.
- `\\AF-SRV\Plant\Line 3\Furnace|Temperature`, um atributo AF.
- `streams/F1DPmNQx2kqBk0qbIVMoxAVBJw/value`, uma URL de stream crua, útil quando você
  já tem o WebId de outra ferramenta.

## Escritas {#writes}

Tags com modo de acesso gravável escrevem pelo endpoint de stream do PI Web API: um
POST de `{"Timestamp":"*","Value":…}` (o carimbo de tempo `*` significa agora) para
`streams/{webId}/value`. A escrita precisa de um WebId resolvível, então ela funciona em tags
endereçadas por caminho AF, por caminho de PI point, por WebId e também por uma URL relativa
`streams/…`: o WebId é lido dessa URL e a escrita cai no endpoint de valor daquele stream,
seja qual for o sub-recurso do lado da leitura (`recorded`, por exemplo) que o endereço carregava
depois dele. Três formas relativas são recusadas, porque cada uma responde com um documento em vez
de responder com o valor de um stream, e uma escrita endereçaria o recurso errado:
`streamsets/…`, `attributes?…` e `points?…`. A recusa nomeia as formas aceitas.
Se a escrita chega ou não também depende de o PI Web API estar configurado para escritas
e de a conta ter acesso de escrita ao ponto. Uma escrita que o PI Web API recusa recebe como resposta o status e o que o serviço disse junto (por exemplo `HTTP 403 Forbidden: …`), e quem escreveu o valor lê o motivo.

O valor que você digita na caixa de escrita da tag é o valor de engenharia; os
estágios de conversão da tag são revertidos antes de o valor bruto ir para o barramento, como descrito
na página [Connector](connector).

## Tipos de dado suportados {#supported-data-types}

Boolean, Int32, Int64, Float, Double e String. PI points numéricos são tipicamente
Float ou Double. Um estado digital não é um valor único, então um ponto que responde com
um lê como qualidade ruim nomeando o estado, seja qual for o tipo que a tag declara.

## Comandos {#commands}

Além de ler e escrever pontos, é possível pedir a um endpoint do PI Web API que faça algo, e
quais requisições ele aceita é assunto do próprio serviço. Declare cada uma no dispositivo, no
cartão **Comandos** da página dele: um nome, a URL relativa a que ela é enviada por POST sob a
raiz de serviço e, opcionalmente, o nome do único valor que ela recebe, que viaja como corpo da
requisição. O verbo Executar da linha a envia e relata o que o serviço respondeu; o comando
também vira um método no dispositivo, dentro do espaço de endereços OPC UA desta estação. Uma
requisição que o serviço recusa recebe como resposta o status e o que o serviço disse junto, com
as mesmas palavras de uma escrita recusada.

## Descoberta {#discovery}

O botão **Descobrir** lê um serviço. Ponha o endereço dele e o elemento AF de onde a caminhada
começa no cartão Escopo da varredura da página do driver, separados por um `#`:
`https://pi-host/piwebapi#\\AF-SRV\Plant\Line 3`. A varredura resolve aquele elemento, percorre
todo elemento abaixo dele e oferece o dispositivo com um ponto por atributo, cada um endereçado
pelo stream dele. A varredura lê o serviço sem credenciais, porque roda antes de
existir o dispositivo que as guardaria, então um PI Web API que autentica toda requisição
não responde nada e o dispositivo é adicionado à mão: adicione o serviço por host e adicione
tags pelos caminhos AF ou PI delas, como o fluxo de adicionar um dispositivo na página
[Connector](connector) descreve.

A página de um dispositivo PI não mostra **Descobrir tags**: a caminhada começa num elemento AF, que o dispositivo não guarda, então os pontos de um dispositivo vêm desta varredura ou são adicionados à mão (veja [Descobrir as tags de um dispositivo](connector-discovery#discovering-a-devices-tags)).

## Acesso a equipamentos {#equipment-access}

Um PI Web API cuja porta não tem nenhum certificado atribuído cria e usa um certificado autoassinado próprio, que nenhuma raiz instalada no Windows garante. Essa raiz não precisa ser instalada neste computador. A primeira conexão é recusada, o dispositivo mostra **Esperando a aprovação do certificado** na árvore e na página dele, cujo botão **Revisar o certificado** abre este cartão no certificado, e o certificado espera em **Acesso a equipamentos**, no fim da página do driver AVEVA PI, o mesmo cartão que a página do driver OPC UA traz, até você decidir:

| Grupo | O que lista | O que você pode fazer |
|---|---|---|
| Esperando aprovação | Cada certificado recusado, sob o nome que ele declara: a impressão digital SHA-256, o endereço em que foi encontrado, quando tentou pela última vez e quantas vezes, e os detalhes (titular, emissor, nomes de domínio, datas de validade). O que o **Revisar o certificado** de um dispositivo abriu fica marcado como Selecionado para revisão. | **Aprovar** aceita o certificado a partir da próxima tentativa de conexão. **Bloquear** continua recusando-o sem listá-lo aqui de novo. **Descartar todos os certificados pendentes** esvazia a lista sem aprovar nem bloquear nada. |
| Equipamentos aprovados | Os certificados que você aprovou ou importou, com quem decidiu e quando, e o endereço em que cada um foi encontrado por último. | **Retirar a aprovação** encerra a conexão e devolve o certificado à lista. **Importar certificado** aprova um arquivo de certificado público que você já tem (.der, .cer, .crt ou .pem) antes da primeira conexão. |
| Equipamentos bloqueados | Os certificados que você bloqueou. Um certificado bloqueado é recusado mesmo que o Windows confie nele. | **Desbloquear** devolve o certificado à lista, sem aprová-lo. |

Confira a impressão digital com quem administra o servidor PI antes de aprovar o certificado. Uma aprovação aceita aquele certificado e nenhum outro, e só dentro das datas de validade dele; ela substitui a raiz que falta no Windows e o nome que o certificado traz, então um PI Web API chamado pelo endereço IP conecta mesmo que o certificado dele traga outro nome, e nada mais do certificado é afrouxado. Quando o equipamento responde num endereço cujo certificado você aprovou com outro (um certificado renovado, outro certificado vinculado à porta), a leitura para, o novo espera aqui e a estação avisa "Certificado mudou: `<nome>`" com um botão **Revisar**. Um certificado em que o Windows já confia é aceito como antes e nunca aparece aqui; nada é aprovado automaticamente.

A própria falha do driver diz o motivo em vez de um erro de TLS sem nome: "O certificado deste equipamento (os primeiros 16 caracteres da impressão digital) espera a sua aprovação em Acesso a equipamentos, na página do driver AVEVA PI. A leitura começa assim que você aprová-lo." Um bloqueado diz "…está bloqueado nesta estação. Revise-o em Acesso a equipamentos, na página do driver AVEVA PI." Um certificado fora das datas de validade, revogado ou com a assinatura quebrada é recusado com esse motivo e nunca é listado, porque nenhuma aprovação o torna válido. Uma varredura do serviço pelo cartão Escopo da varredura esbarra nas mesmas decisões: um certificado desconhecido encerra a varredura com essa frase e espera aqui.

As decisões ficam na pasta de dados da estação, em `ua\pki\aveva-pi`, e sobrevivem a um reinício. Os verbos só são desenhados para um papel que pode configurar o Connector, e só agem na janela da própria estação: um navegador em outro aparelho lê o cartão sem mudá-lo, e nenhuma ferramenta de agente aprova um certificado (`connector_browse` indica o dispositivo em espera com `awaitingCertificate`). A lista guarda até 100 certificados esperando aprovação; quando está cheia, um novo continua recusado mas não é listado, e o cartão diz isso.