- 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.
Saammeko datan Power BI:hin?
Saatte. Power BI ja muut BI-työkalut lukevat rajapintaa tavallisena HTTP-lähteenä: kyselyyn liitetään API-avain, ja raportti päivitetään ajastetusti. Mitoittakaa 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
Päivityksen aikaikkuna kannattaa rajata uuteen dataan eikä pyytää 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ää. Katsokaa 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. Antakaa 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 varmistamme, 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
- Jaettu salaisuus säilytetään vastaanottajan päässä kuin salasana — ei versionhallintaan, ei lokiin.
- HMAC lasketaan saapuneen pyynnön rungosta sellaisenaan, ennen jäsentämistä. Uudelleensarjallistettu runko antaa eri tiivisteen.
- Laskettua ja saatua allekirjoitusta verrataan vakioaikaisella vertailulla.
- Pyyntö hylätään, jos allekirjoitukset eivät täsmää — ei käsitellä ensin ja tarkisteta jälkikäteen.
- Käsittelystä tehdään idempotentti: uudelleenyritys voi tuoda saman tapahtuman toistamiseen, jos vastaus 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ä, mitoittakaa 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, lukekaa Korkea käytettävyys.
2 000arvoa / sKeruupää ja rajapintapää kannattaa pitää mielessä erikseen
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ä. Älkää siis suunnitelko sen varaan. Tällä hetkellä hälytysten välitys ulos hoidetaan webhookilla vastaanottavaan järjestelmään, joka hoitaa oman viestintänsä.
Miten pääsemme kokeilemaan rajapintaa?
Kokeiluversio on 30 päivää, kaikki ominaisuudet HA-lisäosaa lukuun ottamatta, eikä sitoumusta. Asentakaa se omaan ympäristöönne, luokaa API-avain ja ajakaa ensimmäinen kysely omalla työkalullanne — integraation kelpoisuus selviää nopeammin oikealla datalla kuin dokumentaatiota lukemalla. Lisenssit alkavat 4 000 € kertamaksusta. Jos integraatiossa on jotain, mihin tämä sivu ei vastaa, kysykää suoraan.