Tietorajapinnan yleiset tekniset tiedot
Viestintä
Integraatio on REST-pohjainen verkkopalvelu, joka käyttää HTTP-protokollan POST-menetelmää.
GET-menetelmä ei ole enää käytössä versiosta 2.6 alkaen.
Rajapinta käyttää todennuksessa asiakasvarmenteita.
Seuraavassa taulukossa on lueteltu pakolliset määritteet, jotka tarvitaan liittymäyhteyden avaamiseen.
Nimi | Tyyppi | Velvoite | Arvo |
|---|---|---|---|
Yhteys: Asiakkaan varmenne | Varmenne | Pakollinen | Asiakkaan antama varmenne |
Yhteys: Protokolla | Merkkijono | Pakollinen | HTTPS (TLS 1.2 tai TLS 1.3) |
Yhteys: Portti | Merkkijono | Pakollinen | 443 |
Päätepiste
Rajapinnassa on vain yksi päätepiste, jota kutsutaan halutun toiminnon aktivoimiseksi. Päätepisteen URL-osoitteessa on seuraava rakenne:
https://{palvelin}/rest/FGR/{funktio}Parametrit
Otsikkoparametrit:
Nimi | Tyyppi | Velvoite | Arvo |
HTTP: Method | Merkkijono | Pakollinen | POST |
HTTP: Accept | Merkkijono | Pakollinen | application/json |
Polun parametrit:
Nimi | Tyyppi | Velvoite | Arvo |
{Funktio} | Merkkijono | Pakollinen | Katso osio DH-1000. |
Kyselymerkkijonon parametrit:
POST-menetelmässä ei parametrejä.
Vastaussanoma
Vain julkiset tiedot (organisaation tiedot) tai tiedot, joiden osalta toimijalla on sopimus (myynti/verkko/valtuutus), palautetaan. Kun käyttäjä antaa parametreja sellaisten tietojen valtuutussuodattimien kanssa, jotka eivät johda vastaustietoihin, palautetaan tyhjä JSON-objekti vahvistusvirheiden sijasta.
Tyhjien attribuuttien osalta datahub ei lähetä tyhjää elementtiä, mutta sen sijaan se ei lähetä elementtiä.
Esimerkki datahubista tulevasta JSON-vastaussanomasta:
{"GetAccountinPointDataResponse": {
"MeteringPoints": [{
"MeteringPointEAN": "640102010000532598",
"AccountingPointSubType": "AQ01"
},
{
"MeteringPointEAN": "640102010005902686",
"AccountingPointSubType ": "AQ02"
}]
}
}Tietojen kelpoisuus
Kaikki kelpoisuustarkistukset tehdään NäkymänPäivämäärä-kenttään pohjautuvien tietojen tilan perusteella. Toiminnoissa, joissa NäkymänPäivämäärä ei ole syöttökenttänä, käytetään nykyistä päivämäärää ja aikaa.
Tietojen valtuuttaminen
Datahub tarkistaa kaikkien tietopyyntöjen osalta, onko toimijalla asianmukainen valtuutus pyydettyihin tietoihin. Säännöt määritetään toimintokohtaisesti. Pääsy tietoihin, joiden osalta toimijalla ei ole aktiivista (vahvistettua) sopimusta tai valtuutusta, ei ole sallittu, ellei sitä ole nimenomaisesti mainittu prosessissa.
Vahvistettu sopimus tai valtuutus voi olla joku seuraavista sopimus- tai valtuutustyypeistä:
Koodi | Kuvaus |
AP01 | Energiaraportointi |
AP02 | Tarjouspyyntö |
AP03 | Tarjouskilpailu sopimuksesta palveluna |
AP04 | Tarjouspyyntö (ei pääsyä mittaustietoihin) |
AP05 | Tarjouskilpailu sopimuksesta palveluna (ei pääsyä mittaustietoihin) |
AP07 | Energiaraportointi ja sopimustiedot |
11 | Verkkosopimus |
12 | Myyntisopimus |
Tekniset tiedot
Tietorajapinta ei tue yleismerkkihakuja.
Tietorajapinta ei ole kielitietoinen. Se näyttää tiedot sellaisina kuin ne on tallennettu datahubiin.
Esimerkiksi toimialuekoodeja ei käännetä, vaan B2B-rajapinnan tavoin ne ilmoitetaan koodeina. Numeroiden ja päivämäärien osalta näkyy oletusarvoinen XML-/JSON-muoto.
Kaikki tietorajapinnan kellonajat näkyvät UTC-aikana. Esimerkiksi ”2019-05-14T12:30:00Z” on paikallinen Suomen aika ”2019-05-14T15:30:00”
Arvojen yksikkökoodeina käytetään SI-järjestelmään perustuvia tunnuksia: esimerkiksi kW, MW, kWh, MWh, kvar, Mvar, kvarh, mvarh ja Mvarh.
Sanomatunnuksina käytetään UUID-tunnuksia (Universally Unique Identifiers).
Suodattimien arvot voidaan syöttää tekstipohjaisiin tietokenttiin isoilla ja pienillä kirjaimilla. Haku ei erottele isoja ja pieniä kirjaimia.
Yleinen käyttömalli
Käyttöpaikkatunnuksella ja asiakastunnuksella saa haettua:
Prosessi | Kuvaus | Huomautus |
Käyttöpaikan tiedot | Käyttöpaikan tietojen noutaminen. GetAccountingPointDataPost | |
Sopimuksen tiedot (JVH tai myyjä) | Luettelon näyttäminen sopimuksista, joita asiakkaalla on tai oli sen osapuolen osalta, jonka portaalia asiakas käyttää. GetContractDataPost | |
Aikasarjatiedot | Asiakkaan aikasarjatietojen näyttäminen. Mieluiten osapuoli tallentaa tunnin / 15 minuutin raaka-arvot välimuistiin rajoittaakseen vuorovaikutusta datahubin kanssa ja välittääkseen kootut tiedot asiakkaalle. GetTimeSeriesDataPost | |
Valtuutustiedot (palveluntarjoaja tai myyjä) | Luettelon näyttäminen valtuutuksista, joita asiakkaalla on tai oli sen osapuolen osalta, jonka portaalia asiakas käyttää. GetAuthorisationDataPost | |
Asiakastiedot | Sisäänkirjautumisen jälkeen asiakastietojen sekä asiakassopimusten ja käyttöpaikkojen liitettyjen metatietojen noutaminen. GetCustomerDataPost |