Tietorajapinnan yleiset tekniset tiedot
Viestintä
Integraatio on REST-pohjainen verkkopalvelu, joka käyttää HTTP-protokollan POST-menetelmää.
GET-menetelmä poistuu käytöstä Datahub-version 2.6 käyttöönoton yhteydessä.
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
Päätepiste POST-menetelmällä
Rajapinnassa on vain yksi päätepiste, jota kutsutaan halutun toiminnon aktivoimiseksi. Päätepisteen URL-osoitteessa on seuraava rakenne:
https://{palvelin}/rest/FGR/{funktio}Päätepiste GET-menetelmällä
Rajapinnassa on vain yksi päätepiste, jota kutsutaan halutun toiminnon aktivoimiseksi. Päätepisteen URL-osoitteessa on seuraava rakenne:
https://{palvelin}/rest/FGR/{funktio}?organisationUser={OrganisaationKäyttäjä}&suodatin01={suodatin01}&suodatin02={suodatin02}&…Parametrit
Parametrit POST-menetelmässä
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ä.
Parametrit GET-menetelmässä
Otsikkoparametrit:
Nimi | Tyyppi | Velvoite | Arvo |
HTTP: Method | Merkkijono | Pakollinen | GET |
HTTP: Accept | Merkkijono | Pakollinen | application/json |
Polun parametrit:
Nimi | Tyyppi | Velvoite | Arvo |
{Funktio} | Merkkijono | Pakollinen | Katso osio DH-1000. |
Kyselymerkkijonon parametrit:
Nimi | Tyyppi | Velvoite | Arvo |
{OrganisaationKäyttäjä} | Merkkijono | Pakollinen | Organisaatiokohtainen. Määrittää, että Fingridin luomalla rekisteröidyllä Datahubin B2B-käyttäjällä on tiettyjä käyttäjärooleja B2B-viestinnässä. |
{Suodattimet} | {Vaihtelee} | {Vaihtelee} | Tarvittaessa toiminnoissa voi olla useita et-merkillä erotettuja suodattimia. Esimerkki: customerIdentification=1234&meteringPointEAN=12345&ViewDate=2019-10-14T21:00:00ZKäytettävä suodatin määräytyy toiminnon mukaan. Lisätietoja löytyy osiosta DH-1000. Huomaa, että suodattimissa isot ja pienet kirjaimet ovat merkitseviä: (meteringPointEAN vs. MeteringpointEAN). Väärä kirjainkoko aiheuttaa HTTP 400 Bad Request -virheen. |
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. GetAccountingPointDataPosttai GetAccountingPointData | |
Sopimuksen tiedot (JVH tai myyjä) | Luettelon näyttäminen sopimuksista, joita asiakkaalla on tai oli sen osapuolen osalta, jonka portaalia asiakas käyttää. GetContractDataPosttai GetContractData | |
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. GetTimeSeriesDataPosttai GetTimeSeriesData | |
Valtuutustiedot (palveluntarjoaja tai myyjä) | Luettelon näyttäminen valtuutuksista, joita asiakkaalla on tai oli sen osapuolen osalta, jonka portaalia asiakas käyttää. GetAuthorisationDataPosttai GetAuthorisationData | |
Asiakastiedot | Sisäänkirjautumisen jälkeen asiakastietojen sekä asiakassopimusten ja käyttöpaikkojen liitettyjen metatietojen noutaminen. GetCustomerDataPosttai GetCustomerData |