# Bithouse WEB Engine

Web Service API

# Web service-rajapinta

Web service -rajapinnan voidaan kutsua seuraavia operaatioita.

<table border="1" id="bkmrk-operaatio-metodi-url" style="border-collapse: collapse; width: 100%; height: 253.36px;"><tbody><tr style="height: 29.7969px;"><td style="width: 24.9691%; height: 29.7969px;">**Operaatio**</td><td style="width: 24.9691%; height: 29.7969px;">**Metodi**</td><td style="width: 24.9691%; height: 29.7969px;">**URL-pohja**</td><td style="width: 24.9691%; height: 29.7969px;">**Parametrit**</td></tr><tr style="height: 57.7812px;"><td style="width: 24.9691%; height: 57.7812px;">Kirjautuminen (käyttäjä)</td><td style="width: 24.9691%; height: 57.7812px;">POST</td><td style="width: 24.9691%; height: 57.7812px;">plc.php</td><td style="width: 24.9691%; height: 57.7812px;">user=\[username\]

secret=\[passwd\]

</td></tr><tr style="height: 46.5938px;"><td style="width: 24.9691%; height: 46.5938px;">Kirjautuminen (robotti)</td><td style="width: 24.9691%; height: 46.5938px;">GET</td><td style="width: 24.9691%; height: 46.5938px;">plc.php</td><td style="width: 24.9691%; height: 46.5938px;">&amp;key=\[keyString\]&amp;id=\[idString\]</td></tr><tr style="height: 29.7969px;"><td style="width: 24.9691%; height: 29.7969px;">Lue pisteen arvo</td><td style="width: 24.9691%; height: 29.7969px;">GET</td><td style="width: 24.9691%; height: 29.7969px;">plc.php</td><td style="width: 24.9691%; height: 29.7969px;">&amp;get=\[pointName\]</td></tr><tr style="height: 29.7969px;"><td style="width: 24.9691%; height: 29.7969px;">Kirjoita pisteen arvo</td><td style="width: 24.9691%; height: 29.7969px;">GET</td><td style="width: 24.9691%; height: 29.7969px;">plc.php</td><td style="width: 24.9691%; height: 29.7969px;">&amp;set=\[pointName\]&amp;value=\[json\]</td></tr><tr style="height: 29.7969px;"><td style="width: 24.9691%; height: 29.7969px;">Historia-datan lukeminen</td><td style="width: 24.9691%; height: 29.7969px;">GET</td><td style="width: 24.9691%; height: 29.7969px;">plc.php</td><td style="width: 24.9691%; height: 29.7969px;">&amp;historybuffer=\[bufferName\]  
&amp;db=\[historyfile\]&amp;time=\[starttime\]</td></tr><tr style="height: 29.7969px;"><td style="width: 24.9691%; height: 29.7969px;">Listaa pisteet</td><td style="width: 24.9691%; height: 29.7969px;">GET</td><td style="width: 24.9691%; height: 29.7969px;">plc.php</td><td style="width: 24.9691%; height: 29.7969px;">&amp;list=\[namefilter\]&amp;fields=\[fieldfilter\]</td></tr></tbody></table>

**HUOM!** Operaatioita voidaan suorittaa vain onnistuneen kirjautumisen jälkeen.

Rajapinnassa on **kaksi eri kirjautumistapaa:**  
 • POST-pohjainen kirjautuminen on tarkoitettu ihmisten käytettäväksi käyttöpaneeleiden kautta. Luo uuden session. (ei siis yleensä web service käyttöön).  
 • GET-pohjainen (shared key -tyyppinen) kirjautuminen on tarkoitettu roboteille ja automaattisten tiedonkeräysjärjestelmien käytettäväksi (ei luo sessiota).

Jaettu tunnistautumisavain syötetään laitteeseen käyttöönoton yhteydessä. Rajapinnan tarjoama data on JSON-muotoista.

Versiossa 3 voi valvomon kautta suorittaa kyselyjä myös ala-asemille. Tällöin ala-aseman NodeID annetaan "remote" -parametrina, mutta muilta osin komento on sama.

# Kirjautuminen

##### **Käyttäjä**

Käyttäjän kirjautuminen on tarkoitettu käyttöpäätteille. Käyttäjä kirjataan sisään ja luodaan tarvittaessa uusi sessio palvelimelle asiakasta varten.

Esimerkki:

/plc.php

POST  
 user=kayttaja  
 secret=1111

Vastaus:  
\[{"time":"1505129923"}\]

Esimerkki:

/plc.php

POST  
 user=kayttaja  
 secret=111111

Vastaus:  
\[{"error":true,"code":99,"msg":"Authentication failed"}\]

  
**HUOM!** Ilman sisäänkirjautumista ei voi käyttää mitään muuta web-rajapinnan toimintoa!

##### **Robotti**

Robottimallinen kirjautuminen suorittaa sisäänkirjautumisen palvelulle, automaattista tietojen siirtoa varten.

Käyttäjällä joka kirjautuu tällaisella avaintunnuksella (shared key) ei ole täysiä valtuuksia, mm. arvojen kirjoittaminen tietokantaan tai PLC-skriptien suorittaminen web service -rajapinnan yli ei ole sallittua.

Esimerkki:  
 /plc.php?key=12312345

Vastaus:  
\[{"time":"1505129923"}\]

Esimerkki:  
 /plc.php?key=133333335

Vastaus:  
\[{"time":"1505129923"}\]

Vastaus:  
\[{"error":true,"code":99,"msg":"Authentication failed"}\]

  
**HUOM!** Ilman sisäänkirjautumista ei voi käyttää mitään muuta web-rajapinnan toimintoa!

##### **Yhdistetty kirjautuminen ja kysely**

Shared key -autentikointiavain on mahdollista antaa suoraan mm. list- tai get-kyselyiden yhteydessä URL-parametrina, jolloin erillistä kirjautumista ei tarvita.

Esimerkki:

/plc.php?list=ioPoints/%2A&amp;key=1234512345

Vastaus:  
\[{"list":\["ioPoints\\/TK01\\/TE10","ioPoints\\/TK01\\/TE30"\]},{"time":"1505137744"}\]

# Datapisteet

##### **Lukeminen**

  
Read datapoint value lukee datapisteiden arvoja WS-rajapinnan ylitse. Samalla komennolla voidaan lukea useita pisteitä erottamalla niiden nimet puolipilkulla ( ; ).

Esimerkki: Luetaan koko piste ”sys/settings/networkSettings”.  
/plc.php?get=sys/settings/networkSettings

Vastaus:  
\[{"get":"{\\"defaultGateway\\":\\"192.168.0.1\\",\\"subnetMask\\":\\"255.255.255.0\\",\\"ipAddress\\":\\"192.168.0.128\\",\\"dnsServer\\":\\"8.8.8.8\\",\\"broadcastAddress\\":\\"192.168.0.255\\"}"},{"time":"1505132981"}\]

Esimerkki: Luetaan kahden prosessidatapisteen oloarvot (pisteet ioPoints/TK01/TE10 ja ioPoints/TK01/TE30).

/plc.php?get=ioPoints/TK01/TE10.pv;ioPoints/TK01/TE30.pv

Vastaus:  
\[{"get":"20.6"},{"get":"19.6"},{"time":"1505133163"}\]

Esimerkki: Luetaan sellaisen pisteen arvo, jota ei ole olemassa.

/plc.php?get=ioPoints/TK01/TE100.pv

Vastaus:  
\[{"get":"-4294967296"},{"time":"1505133224"}\]

##### **kirjoittaminen**

  
Datapisteen arvon kirjoittaminen WS-rajapinnan ylitse.

Value-parametri, eli kirjoitettava arvo annetaan JSON-muodossa.

**Huom! Ei käytössä shared key -autentikoinnin kautta.**

Esimerkki: Kirjoitetaan tuloilman asetusarvo (piste ”ioPoints/TK01/TE10\_SP”).

/plc.php?set=ioPoints/TK01/TE10.pv&amp;value=22.0

Vastaus:  
\[{"set":"true"},{"time":"1505137224"}\]

##### **Listaus**  
  


Prosessorin datapisteiden listaaminen. Suodatusta listassa voidaan tehdä joko pistenimissä (wildcard-merkillä \*) tai niiden sisältämien arvojen perusteella.

Syntaksi *list*- ja *field*-parametreille on sama kuin Data.list() -kutsussa.

 **list**  Tällä parametrilla annetaan suodausehto pisteiden nimelle. Wildcardina toimii merkki ’\*’, joka on URL-koodattuna %2A.

 **field** Tämän parametrin avulla voidaan suodattaa pisteitä kenttien ja jopa kenttien arvojen perusteella. Tässä yhteydessä ei voi suoraan käyttää Wild card -merkkejä, koska lausekkeen täytyy olla validi vertailu.

Esimerkki 1: Listataan kaikki TK01:n pisteet, eli nimisuodattimena ”ioPoints/TK01/\*”.

/plc.php?list=ioPoints/TK01/%2A

Vastaus:  
\[{"list":\["ioPoints\\/TK01\\/TE10","ioPoints\\/TK01\\/TE30"\]},{"time":"1505137744"}\]

  
Esimerkki 2: Listataan kaikki pisteet joilla on kenttä ’dataSource’

/plc.php?list=ioPoints/TK01/%2A&amp;field=(dataSource)

Esimerkki 3: Listataan kaikki pisteet joilla kenttä pv on suurempi kuin 9.0

Muista että field parametrille täytyy tehdä URL enkoodaus! Selväkielisenä vertailu on (pv &gt; 9.0)

/plc.php?list=ioPoints/TK01/%2A&amp;field=(pv%20%3E%209.0)

# Historiadatan lukeminen

  
Actiweb tallentaa historiadatan (mm. trendi-data) time series -tietokantaan. Tätä dataa on mahdollista kysellä ”historybuffer”-operaatiolla.

Parametreina pitää antaa tietokantatiedoston nimi ja luettavan datapuskurin nimi. Datapuskurin nimi on aina sama kuin logattavan pisteen nimi yhdistettynä seurattavan parametrin nimeen – yleensä pisteestä seurataan **pv**-parametriä, eli mittauksen oloarvoa - t.s. lukemaa. Muita parametreja ovat mm. **description** joka tarkoittaa selitetekstiä, **dispUnit** eli yksikkö. Historiapuskuriin tallennetaan kuitenkin normaalisti vain mittauksen pv kenttä. Näin puskurin nimeksi muodostuu esimerkiksi ”ioPoints/TK01/TE10.pv”.

Samaa pistettä voidaan tallentaa useaan eri tiedostoon. Jokaisella historia-tiedostolla on omat erikseen määritellyt näytteenottovälinsä, ja maksimikokonsa, jonka jälkeen vanhimpia näytteitä aletaan poistaa.

Historiatiedostoja ja puskureita voidaan luoda, poistaa ja asetuksia säätä web-käyttöliittymän ylitse.

Ohjelmisto luo automaattisesti ”quicktrend”-nimisen historiatiedoston, jonka näytteistysväli on (oletuksena) 30 sekuntia, ja koko 3000 näytettä. Tähän tiedostoon luodaan datapuskuri kaikille niille tietokannasta löytyville pisteille, joilla on ”pv”-parametri (eli nykyinen oloarvo).

GET-operaation parametrilla **time** voidaan määrittää aika, jonka jälkeinen data puskurista halutaan lukea. Aika annetaan n.s. unix epookkina, eli sekunteina ajanhetken 1970.1.1 klo 00:00 jälkeen.

Aika voidaan antaa myös negatiivisena lukuna, jolloin sen tulkitaan tarkoittavan sekuntimäärää ennen nykyhetkeä. Toisinsanoen &amp;time=-86400 tarkoittaa, että halutaan lukea näytteet, joiden aikaleima on alle 24 tuntia vanha.

Esimerkki: Luetaan pikatrendi (tiedosto **quicktrend**) pisteeltä ”ioPoints/TK01/TE10” ja parametrilta ”pv”, edellisen 5 minuutin ajalta.

/plc.php?db=quicktrend&amp;historybuffer=ioPoints%2ATK01%2ATE10.pv&amp;time=-300

Vastaus:  
\[{"historybuffer":\[\["1505743059","1.000000"\],\["1505743089","21.100000"\],\["1505743119","21.300000"\],\["1505743149","21.200000"\],\["1505743179","21.300000"\],\["1505743209","21.300000"\],\["1505743239","21.400000"\],\["1505743269","21.300000"\],\["1505743299","21.200000"\],\["1505743329","21.200000"\]\]},{"time":"1505743354"}\]

Esimerkiksi kulutusmittaukset tallennetaan tavallisesti **reports** nimiseen tietokantaan, johon oletuksena tallennetaan lukema 30 min välein kellon aikaan sidotusti niin, että näyte tallennetaan tasatunnein, ja puolelta. Alla olevalla kutsulla saa luettua viimeisen 32 päivän lukemat **reports** puskurista, ja mittarilta **mittaukset/HUONEISTO\_A10/VM01.**

/plc.php?db=reports&amp;historybuffer=mittaukset/HUONEISTO\_A10/VM01.pv&amp;time=-2764800

Vastaus:  
\[{"historybuffer":\[\["1505743059","1.000000"\],\["1505743089","21.100000"\],\["1505743119","21.300000"\],\["1505743149","21.200000"\],\["1505743179","21.300000"\],\["1505743209","21.300000"\],\["1505743239","21.400000"\],\["1505743269","21.300000"\],\["1505743299","21.200000"\],\["1505743329","21.200000"\]\]},{"time":"1505743354"}\]