REST API ja webhookit
DataPortia™ ei ole laitoksen ainoa järjestelmä. REST API v1 ja HMAC-allekirjoitetut webhookit vievät kerätyn datan MES-, ERP- ja BI-järjestelmiin: mittausdata, hälytykset ja järjestelmän tila ovat luettavissa. Rajapinta on tarkoituksella vain luku — siitä ei kirjoiteta takaisin automaatioon.
- 120
- pyyntöä / min Käyttöraja API-avainta kohden
- 24
- kuukautta Säilytysajan oletus, säädettävissä
- 0
- kirjoitusoperaatiota Rajapinta on vain luku
Miten DataPortian data siirretään muihin järjestelmiin?
Dataa saa ulos kolmella tavalla. REST API v1 vastaa kyselyihin ja tunnistautuu API-avaimella. Webhookit työntävät tapahtuman vastaanottajalle heti sen sattuessa, HMAC-allekirjoitettuna. Ajastetut raportit tuottavat saman datan valmiiksi tiedostoksi (PDF, CSV tai XLSX) päivä-, viikko- tai kuukausirytmillä. Kaikki liikenne kulkee HTTPS:n yli automaattisesti hoidetuin sertifikaatein.
| Tapa | Suunta | Tunnistautuminen | Tyypillinen käyttö |
|---|---|---|---|
| REST API v1 | vastaanottaja kysyy | API-avain | BI-raportit, MES-kyselyt, ad hoc -haut |
| Webhook | DataPortia työntää | HMAC-allekirjoitus | hälytysten välitys, tapahtumapohjaiset integraatiot |
| Raporttivienti | ajastettu tiedosto | — | PDF, CSV tai XLSX päivä-, viikko- tai kuukausirytmillä |
Mitä dataa REST API v1 palauttaa?
Rajapinnasta luetaan mittausdata, hälytykset ja järjestelmän tila. Jokainen kutsu tunnistautuu API-avaimella, ja yhdelle avaimelle sallitaan 120 pyyntöä minuutissa. Kirjoitusoperaatioita ei ole lainkaan: rajapinta ei muuta mittapisteitä, ei kuittaa hälytyksiä eikä koske automaation arvoihin. Liikenne kulkee HTTPS:n yli, ja vastaukset tulevat samasta TimescaleDB-kannasta, johon keruu kirjoittaa.
Tarkemmin: aikaleimat ja tapahtumien järjestys
Hälytysten alkuperäinen aikaleima säilyy katkaisematta millisekunnin tarkkuudella, joten tapahtumien järjestys pysyy oikeana myös vastaanottavassa järjestelmässä. Hälytysten käsittely on kuvattu sivulla Hälytykset ja tapahtumat.
Voiko API kirjoittaa arvoja automaatioon?
Ei voi. REST API v1 on vain luku: se ei kirjoita arvoja OPC UA -palvelimelle, ei kuittaa hälytyksiä eikä muuta asetuksia. Asetusarvot ja kuittaukset kulkevat edelleen automaatiojärjestelmän omaa reittiä. Rajaus on tietoinen turvallisuusvalinta: vuotanut API-avain paljastaa mittausdataa, mutta ei anna pääsyä prosessin ohjaukseen.
Vain luku on rajaus, ei puute. Se pitää raportointijärjestelmän hyökkäyspinnan pienenä: pahimmassa tapauksessa menetetään dataa, ei ohjausoikeuksia.
Tarkemmin: mihin suuntaan DataPortia liikennöi
Käytännössä DataPortia toimii automaatioverkossa vain lukevana asiakkaana. Se lukee dataa ja historiaa OPC UA -palvelimelta, mutta ei kirjoita sinne mitään. Jos integraatiosuunnitelmassa on nuoli takaisin prosessiin, se nuoli ei kulje tämän rajapinnan kautta. Keruupää on kuvattu sivulla OPC UA -tiedonkeruu.
Saanko datan Power BI:hin?
Saat. Power BI ja muut BI-työkalut lukevat rajapintaa tavallisena HTTP-lähteenä: kyselyyn liitetään API-avain, ja raportti päivitetään ajastetusti. Mitoita päivitysrytmi käyttörajan mukaan — yhdelle avaimelle sallitaan 120 pyyntöä minuutissa. Raja riittää hyvin ajastettuun raporttiin, mutta ei silmukkaan, joka hakee jokaisen mittapisteen omalla kutsullaan.
Tarkemmin: päivitysrytmin mitoitus ja Excel-vienti
Rajoita päivityksen aikaikkuna uuteen dataan äläkä pyydä koko historiaa uudelleen joka ajolla. Näin sama raportti pysyy käyttörajan sisällä myös silloin, kun pisteitä tulee lisää.
Jos vastaanottaja on Excel eikä BI-palvelin, ajastettu raporttivienti on usein yksinkertaisempi: DataPortia tuottaa XLSX- tai CSV-tiedoston valmiiksi eikä avainta tarvitse ylläpitää. Katso Raportointi.
Miten API-avaimet ja käyttörajat toimivat?
Avain yksilöi kutsuvan järjestelmän ja kantaa myös käyttörajan: 120 pyyntöä minuutissa avainta kohden. Anna jokaiselle integraatiolle oma avain — silloin kuormaa voi seurata järjestelmäkohtaisesti ja yhden avaimen kumoaminen jättää muut ennalleen. Raja lasketaan avaimittain, joten MES:n ja BI:n kyselyt eivät syö toistensa budjettia.
Tarkemmin: avain, käyttöraja, vain luku ja webhook-salaisuus
- API-avain
- Tunniste, joka yksilöi kutsuvan järjestelmän. Kumottu avain lakkaa toimimasta, eivätkä muut avaimet häiriinny siitä.
- Käyttöraja
- 120 pyyntöä minuutissa avainta kohden. Raja on avainkohtainen, joten erilliset avaimet pitävät MES:n ja BI:n kuormat erillään.
- Vain luku
- Rajapinnassa ei ole kirjoitusoperaatioita. Avaimella pääsee lukemaan dataa, ei muuttamaan mitään.
- Webhook-salaisuus
- Jaettu salaisuus, jolla DataPortia allekirjoittaa lähtevät toimitukset ja jolla vastaanottaja tarkistaa ne.
Miten varmistan, että webhook tuli DataPortiasta?
Jokainen webhook-toimitus on HMAC-allekirjoitettu jaetulla salaisuudella. Vastaanottaja laskee saman tiivisteen saamastaan rungosta ja vertaa sitä mukana tulleeseen allekirjoitukseen. Jos ne eivät täsmää, pyyntö on hylättävä. Epäonnistuneet toimitukset yritetään automaattisesti uudelleen, joten hetken alhaalla ollut vastaanotin ei tarkoita kadonnutta tapahtumaa. Tarkistus tehdään ennen kuin runkoa käsitellään.
Tarkemmin: allekirjoituksen tarkistus vaiheittain
- Säilytä jaettu salaisuus vastaanottajan päässä kuin salasana — ei versionhallintaan, ei lokiin.
- Laske HMAC saapuneen pyynnön rungosta sellaisenaan, ennen kuin jäsennät sen. Uudelleensarjallistettu runko antaa eri tiivisteen.
- Vertaa laskettua ja saatua allekirjoitusta vakioaikaisella vertailulla.
- Hylkää pyyntö, jos allekirjoitukset eivät täsmää. Älä käsittele ensin ja tarkista jälkikäteen.
- Tee käsittelystä idempotentti: uudelleenyritys voi tuoda saman tapahtuman toistamiseen, jos vastauksesi jäi matkalle.
Milloin rajapinta ei riitä?
Rajapinta ei sovi prosessin ohjaukseen eikä jatkuvaan reaaliaikasyötteeseen. Se ei myöskään palauta dataa, jota ei enää ole: säilytysaika on säädettävä ja oletuksena 24 kuukautta. Jos vastaanottava järjestelmä tarvitsee tuhansia pisteitä lyhyellä syklillä, mitoita kyselyt ja aikaikkunat etukäteen, ennen kuin integraatio viedään tuotantoon.
Tarkemmin: keruun läpäisy ja varautuminen palvelinvikaan
Keruupää ja rajapintapää kannattaa pitää mielessä erikseen. DataPortia ottaa vastaan yli 2 000 arvoa sekunnissa ja kirjoittaa ne TimescaleDB-kantaan, mutta REST API on tarkoitettu jäsenneltyihin kyselyihin, ei saman virran edelleenlähetykseen. Jos integraation on kestettävä palvelinvika, lue Korkea käytettävyys.
Usein kysytyt kysymykset
Alla integraattorien tavallisimmat kysymykset rajapinnasta: verkkoyhteys, historian pituus, vastaanottajan katkokset, avaimen kumoaminen ja hälytysten välitys ulos. Vastaukset pysyvät siinä, mikä tuotteessa on tänään, ja kehityksessä oleva on merkitty erikseen. Tuotteen kokonaiskuva löytyy sivulta DataPortia.
Toimiiko rajapinta ilman internet-yhteyttä?
Kyllä. DataPortia on on-premises-ohjelmisto ja tarjoilee rajapinnan omasta Kestrel-palvelimestaan HTTPS:n yli. Kutsujan on oltava samassa verkossa tai muuten tavoittamassa palvelinta — ja webhookin vastaanottajan puolestaan tavoitettavissa palvelimelta. Pilvipalvelua ei tarvita kummassakaan suunnassa.
Kuinka pitkälle historiaan rajapinnasta pääsee?
Säilytysajan verran. Oletus on 24 kuukautta ja arvo on säädettävissä laitoksen tarpeen mukaan. Pakkaus säästää levytilaa; se ei rajoita sitä, miltä aikaväliltä dataa voi hakea. Säilytys ja pakkaus on kuvattu tarkemmin sivulla OPC UA -tiedonkeruu.
Mitä tapahtuu, jos vastaanottava järjestelmä on hetken alhaalla?
Webhook-toimitukset yritetään automaattisesti uudelleen. REST API:n puolella katkos ei hävitä mitään: data on kannassa, ja kutsuja hakee puuttuvan aikavälin, kun yhteys palaa. Uudelleenyritysten takia vastaanottajan käsittelyn on siedettävä sama tapahtuma kahdesti.
Voiko avaimen kumota kesken kaiken?
Voi. Avain on integraatiokohtainen tunniste, ja sen kumoaminen katkaisee vain sillä tehdyt kutsut. Koska raja ja identiteetti ovat avainkohtaisia, muiden järjestelmien kutsut jatkuvat ennallaan. Tämä on käytännön syy antaa jokaiselle järjestelmälle oma avain heti alusta.
Voiko hälytykset lähettää tekstiviestinä?
Kehityksessä Tekstiviestihälytyksiä ei ole voitu testata, eikä ominaisuus ole käytettävissä. Älä siis suunnittele sen varaan. Tällä hetkellä hälytysten välitys ulos hoidetaan webhookilla vastaanottavaan järjestelmään, joka hoitaa oman viestintänsä.
Miten pääsen kokeilemaan rajapintaa?
Kokeiluversio on 30 päivää, kaikki ominaisuudet HA-lisäosaa lukuun ottamatta, eikä sitoumusta. Asenna se omaan ympäristöösi, luo API-avain ja aja ensimmäinen kysely omalla työkalullasi — integraation kelpoisuus selviää nopeammin oikealla datalla kuin dokumentaatiota lukemalla. Lisenssit alkavat 4 000 € kertamaksusta. Jos integraatiossa on jotain, mihin tämä sivu ei vastaa, kysy suoraan.