Bithouse WEB Engine
Web Service API
Web service-rajapinta
Web service -rajapinnan voidaan kutsua seuraavia operaatioita.
| Operaatio | Metodi | URL-pohja | Parametrit |
| Kirjautuminen (käyttäjä) | POST | plc.php |
user=[username] secret=[passwd] |
| Kirjautuminen (robotti) | GET | plc.php | &key=[keyString]&id=[idString] |
| Lue pisteen arvo | GET | plc.php | &get=[pointName] |
| Kirjoita pisteen arvo | GET | plc.php | &set=[pointName]&value=[json] |
| Historia-datan lukeminen | GET | plc.php | &historybuffer=[bufferName] &db=[historyfile]&time=[starttime] |
| Listaa pisteet | GET | plc.php | &list=[namefilter]&fields=[fieldfilter] |
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
Esimerkki:
/plc.php?list=ioPoints/%2A&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&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&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 > 9.0)
/plc.php?list=ioPoints/TK01/%2A&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 &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&historybuffer=ioPoints%2ATK01%2ATE10.pv&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&historybuffer=mittaukset/HUONEISTO_A10/VM01.pv&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"}]