REST API och webhookar
DataPortia™ är inte anläggningens enda system. REST API v1 och HMAC-signerade webhookar för ut insamlade data till MES-, ERP- och BI-system: mätdata, larm och systemstatus går att läsa. Gränssnittet är avsiktligt endast läsande — därifrån skrivs ingenting tillbaka till automationen.
- 120
- förfrågningar / min Användningsgräns per API-nyckel
- 24
- månader Förval för lagringstiden, justerbar
- 0
- skrivoperationer Gränssnittet är endast läsande
Hur överförs DataPortias data till andra system?
Data kommer ut på tre sätt. REST API v1 svarar på förfrågningar och autentiseras med en API-nyckel. Webhookarna skickar händelsen till mottagaren så fort den inträffar, HMAC-signerad. Schemalagda rapporter producerar samma data som en färdig fil (PDF, CSV eller XLSX) i dygns-, vecko- eller månadsrytm. All trafik går över HTTPS med automatiskt skötta certifikat.
| Sätt | Riktning | Autentisering | Typisk användning |
|---|---|---|---|
| REST API v1 | mottagaren frågar | API-nyckel | BI-rapporter, MES-förfrågningar, ad hoc-sökningar |
| Webhook | DataPortia skickar | HMAC-signatur | vidarebefordran av larm, händelsebaserade integrationer |
| Rapportexport | schemalagd fil | — | PDF, CSV eller XLSX i dygns-, vecko- eller månadsrytm |
Vilka data returnerar REST API v1?
Ur gränssnittet läses mätdata, larm och systemstatus. Varje anrop autentiseras med en API-nyckel, och en enskild nyckel tillåts 120 förfrågningar per minut. Skrivoperationer finns inte alls: gränssnittet ändrar inga mätpunkter, kvitterar inga larm och rör inte automationens värden. Trafiken går över HTTPS, och svaren kommer ur samma TimescaleDB-databas som insamlingen skriver till.
Närmare: tidsstämplar och händelsernas ordning
Larmets ursprungliga tidsstämpel bevaras oavkortad med millisekunds noggrannhet, så händelsernas ordning förblir riktig även i det mottagande systemet. Hanteringen av larm beskrivs på sidan Larm och händelser.
Kan API:et skriva värden till automationen?
Nej. REST API v1 är endast läsande: det skriver inga värden till OPC UA-servern, kvitterar inga larm och ändrar inga inställningar. Börvärden och kvitteringar går fortfarande via automationssystemets egen väg. Avgränsningen är ett medvetet säkerhetsval: en läckt API-nyckel avslöjar mätdata, men ger ingen åtkomst till processtyrningen.
Endast läsning är en avgränsning, inte en brist. Den håller rapportsystemets angreppsyta liten: i värsta fall förloras data, inte styrrättigheter.
Närmare: åt vilket håll DataPortia trafikerar
I praktiken fungerar DataPortia som en enbart läsande klient i automationsnätet. Programvaran läser data och historik från OPC UA-servern men skriver ingenting dit. Om integrationsplanen har en pil tillbaka till processen går den pilen inte via det här gränssnittet. Insamlingssidan beskrivs på sidan OPC UA-datainsamling.
Får jag in data i Power BI?
Ja. Power BI och andra BI-verktyg läser gränssnittet som en vanlig HTTP-källa: API-nyckeln bifogas förfrågan och rapporten uppdateras schemalagt. Dimensionera uppdateringsrytmen efter användningsgränsen — en enskild nyckel tillåts 120 förfrågningar per minut. Gränsen räcker gott för en schemalagd rapport, men inte för en slinga som hämtar varje mätpunkt med ett eget anrop.
Närmare: dimensionering av uppdateringsrytmen och export till Excel
Begränsa uppdateringens tidsfönster till nya data och begär inte hela historiken på nytt vid varje körning. Så håller sig samma rapport inom användningsgränsen även när det tillkommer fler punkter.
Om mottagaren är Excel och inte en BI-server är en schemalagd rapportexport ofta enklare: DataPortia producerar en färdig XLSX- eller CSV-fil och ingen nyckel behöver underhållas. Se Rapportering.
Hur fungerar API-nycklar och användningsgränser?
Nyckeln identifierar det anropande systemet och bär också användningsgränsen: 120 förfrågningar per minut per nyckel. Ge varje integration en egen nyckel — då går belastningen att följa systemvis, och när en nyckel återkallas lämnas de övriga orörda. Gränsen räknas per nyckel, så MES:ets och BI:ets förfrågningar äter inte av varandras budget.
Närmare: nyckel, användningsgräns, endast läsning och webhook-hemlighet
- API-nyckel
- Identifierare som pekar ut det anropande systemet. En återkallad nyckel slutar fungera, och de övriga nycklarna störs inte av det.
- Användningsgräns
- 120 förfrågningar per minut per nyckel. Gränsen är nyckelspecifik, så separata nycklar håller MES:ets och BI:ets belastningar åtskilda.
- Endast läsning
- Gränssnittet har inga skrivoperationer. Med nyckeln går det att läsa data, inte att ändra något.
- Webhook-hemlighet
- Delad hemlighet som DataPortia signerar utgående leveranser med och som mottagaren kontrollerar dem med.
Hur säkerställer jag att en webhook kom från DataPortia?
Varje webhook-leverans är HMAC-signerad med en delad hemlighet. Mottagaren beräknar samma hash av den kropp den fått och jämför den med den medföljande signaturen. Om de inte stämmer överens ska förfrågan förkastas. Misslyckade leveranser görs om automatiskt, så en mottagare som varit nere en stund betyder inte en förlorad händelse. Kontrollen görs innan kroppen behandlas.
Närmare: kontroll av signaturen steg för steg
- Förvara den delade hemligheten hos mottagaren som ett lösenord — inte i versionshanteringen, inte i loggen.
- Beräkna HMAC på den inkomna förfrågans kropp som den är, innan du tolkar den. En omserialiserad kropp ger en annan hash.
- Jämför den beräknade och den mottagna signaturen med en jämförelse i konstant tid.
- Förkasta förfrågan om signaturerna inte stämmer överens. Behandla inte först och kontrollera i efterhand.
- Gör behandlingen idempotent: ett omtag kan leverera samma händelse en gång till, om ditt svar blev kvar på vägen.
När räcker gränssnittet inte till?
Gränssnittet passar inte för processtyrning och inte för en kontinuerlig realtidsström. Det returnerar inte heller data som inte längre finns: lagringstiden är justerbar och som förval 24 månader. Om det mottagande systemet behöver tusentals punkter med kort cykel, dimensionera förfrågningarna och tidsfönstren i förväg, innan integrationen tas i produktion.
Närmare: insamlingens genomströmning och beredskap för serverfel
Insamlingssidan och gränssnittssidan är värda att hålla isär. DataPortia tar emot över 2 000 värden per sekund och skriver dem till TimescaleDB-databasen, men REST API är avsett för strukturerade förfrågningar, inte för att skicka samma ström vidare. Om integrationen måste tåla ett serverfel, läs Hög tillgänglighet.
Vanliga frågor
Nedan integratörernas vanligaste frågor om gränssnittet: nätförbindelse, historikens längd, avbrott hos mottagaren, återkallande av nyckel och vidarebefordran av larm. Svaren håller sig till det som finns i produkten i dag, och det som är under utveckling är särskilt markerat. Helhetsbilden av produkten finns på sidan DataPortia.
Fungerar gränssnittet utan internetanslutning?
Ja. DataPortia är en on-premises-programvara och betjänar gränssnittet från sin egen Kestrel-server över HTTPS. Den som anropar måste finnas i samma nät eller på annat sätt nå servern — och webhookens mottagare i sin tur vara nåbar från servern. Någon molntjänst behövs inte i någondera riktningen.
Hur långt tillbaka i historiken når gränssnittet?
Så långt som lagringstiden räcker. Förvalet är 24 månader och värdet är justerbart efter anläggningens behov. Komprimeringen sparar diskutrymme; den begränsar inte vilket tidsintervall data går att hämta för. Lagring och komprimering beskrivs närmare på sidan OPC UA-datainsamling.
Vad händer om det mottagande systemet är nere en stund?
Webhook-leveranserna görs om automatiskt. På REST API-sidan förlorar ett avbrott ingenting: data finns i databasen, och den som anropar hämtar det uteblivna tidsintervallet när förbindelsen är tillbaka. På grund av omtagen måste mottagarens behandling tåla samma händelse två gånger.
Går det att återkalla en nyckel mitt i allt?
Ja. Nyckeln är en integrationsspecifik identifierare, och att återkalla den bryter bara de anrop som gjorts med den. Eftersom gräns och identitet är nyckelspecifika fortsätter de andra systemens anrop oförändrade. Det är det praktiska skälet att ge varje system en egen nyckel redan från början.
Går det att skicka larm som sms?
Under utveckling Sms-larm har inte kunnat testas, och funktionen är inte tillgänglig. Planera alltså inte utifrån den. För närvarande sköts vidarebefordran av larm utåt med en webhook till det mottagande systemet, som sköter sin egen kommunikation.
Hur kommer jag igång med att testa gränssnittet?
Testversionen är 30 dagar, alla funktioner utom HA-tillägget, och utan bindningstid. Installera den i din egen miljö, skapa en API-nyckel och kör den första förfrågan med ditt eget verktyg — om integrationen duger klarnar snabbare med riktiga data än genom att läsa dokumentation. Licenserna börjar på 4 000 € som permanent licens (engångsbetalning). Om det finns något i integrationen som den här sidan inte svarar på, fråga direkt.