Page Comparison

1.       CIM XML og CIM JSON webservice interface

Begge dokumentformater afleveres via den samme kanal til DataHub. Kaldet til DataHub for- tæller hvilken type data der bliver sendt og vil blive valideret på baggrund af dette.

2.       Kommunikation

Kommunikationskanalen til CIM er baseret på http protokollen. Der gøres brug af standard http verber, http-headers og status koder når der sendes et datasæt til DataHub. 

2.1       HTTP kommunikation

De forskellige http-verber benyttes til at udtrykke hvad man ønsker at udfører i DataHub. 

2.1.1      HTTP POST

Hvis man vil aflevere et datasæt til DataHub dannes forespørgslen som en POST. Selve doku- mentet skrives i body på HTTP forespørgslen. Ved hjælp af http header værdier beskrives ind- holdet. For at sende i CIM XML sættes Content-Type til application/xml, ved CIM JSON er vær- dien application/json.

For at indikere hvilket format man ønsker svaret leveret i sættes Accept. Her kan man vælge imellem application/xml og application/json. Undlades værdien bliver der som default sendt et svar via application/json.

 Hvis indholdet overholder de gældende regler, vil der blive returneret 202 Accepted fra Data- Hub. Når dette returneres, vil der ikke være noget indhold med i svaret. Ved eventuelle sup- port henvendelser kan man referere til værdien der findes i http-headeren CorrelationId, denne kan bruges til at spore forespørgslen i DataHub.

POST /v1.0/cim/RequestEndOfSupply HTTP/1.1

Host: api.itlev.datahub.dk

Authorization: Bearer <bearer-token>

Accept: application/json

Content-Type: application/xml

Content-Length: <content-length-of-request>

<? xml version=”1.0” encoding=”UTF-8” ?>

...

HTTP/1.1 202 Accepted

CorrelationId: c3105ac6-7a60-48e1-8c15-8df11dcc4ee4

2.1.2      HTTP GET

Når man vil hente data ud fra DataHub dannes der en GET-forespørgsel. For at indikere det for- mat man ønsker svaret returneret i sættes Accept headeren. DataHub vil forsøge at leve op til den ønskede værdi. Der understøttes umiddelbart to værdier application/xml og applica- tion/json. DataHub vil i svaret indikere det faktiske indholds format ved at sætte Content-Type til enten application/xml eller application/json.

Serveren vil svare tilbage med det indhold der er fundet på forespørgslen. Hvis der er et doku- ment, vil statuskoden være 200 OK, hvis der ikke er fundet noget indhold, vil statuskoden være 204 No Content.

GET /v1.0/cim/timeseries HTTP/1.1

Host: api.itlev.datahub.dk Authorization: Bearer <bearer-token>

Accept: application/xml

Svar uden indhold:

HTTP/1.1 204 No Content

CorrelationId: c3105ac6-7a60-48e1-8c15-8df11dcc4ee4

Svar med indhold:

HTTP/1.1 200 OK

Content-Type: application/xml

Content-Length: <content-length-of-response>

CorrelationId: c3105ac6-7a60-48e1-8c15-8df11dcc4ee4

MessageId: <id-of-message>

<? Xml version=”1.0” encoding=”UTF-8” ?>

...

2.1.3      HTTP DELETE

Skal der fjernes noget indhold fra DataHub benyttes en DELETE-forespørgsel. Serveren kan svare tilbage med to forskellige statuskoder, 200 OK hvis det lykkedes at gennemføre fore- spørgslen. Ved fejl se fejlbeskeder i sektion 2.3. Ved at sætte Accept kan man indikere hvilket format man ønsker svaret returneret i.

DELETE /v1.0/cim/deqeueue/<id-of-message> HTTP/1.1

Host: api.itlev.datahub.dk

Authorization: Bearer <bearer-token>

Accept: application/json

Positiv tilbagemelding:

HTTP/1.1 200 OK

CorrelationId: c3105ac6-7a60-48e1-8c15-8df11dcc4ee4

Negativ tilbagemelding:

HTTP/1.1 400 Bad Request

Content-Type: application/json

Content-Length: <content-length-of-response>

CorrelationId: c3105ac6-7a60-48e1-8c15-8df11dcc4ee4

{

   ”error”: {

      ”code”: ”BadArgument”,
      ”message”: ”Unknown message-id”,
      ”target”: ”message-id”,
      ”innererror”: {

         ”code”: ”MessageIdNotKnown”,
         ”message-id”: ”<id-of-message>”
      }
   }

}

2.2       Sikkerhed

For at kommunikere med CIM kanalen er en krypteret forbindelse påkrævet. DataHub udstiller en HTTPS-adresse hvor alt kommunikation skal foregå.

Udover den krypterede forbindelse gør DataHub brug af OAuth til at sikre identiteten af aktø- ren. Dette sker ved at aktøren medsender et bearer token for hvert kald. For at hente et token – se afsnit 2.5.

Bearer token skrives i et http-header, Authorization, hvor det prefixes med Bearer.

POST /v1.0/cim/RequestEndOfSupply

HTTP/1.1 Host: api.itlev.datahub.dk

Authorization: Bearer <bearer-token>

Content-Type: application/xml

Content-Length: <content-length-of-request>

<?xml version=”1.0” encoding=”UTF-8”?>

<RequestEndOfSupply_MarketDocument>

...

</RequestEndOfSupply_MarketDocument>

2.3       Validering af forespørgsler

Der bliver foretager flere valideringer når en forespørgsel håndteres af DataHub. Hver af disse valideringer kan resultere i forskellige fejl koder.

Hvis der er en fejl ved forespørgslen, bliver fejlen beskrevet ved hjælp af en ”fejl” datastruktur.

Se nedenstående tabeller. Strukturen kan returneres enten som XML eller JSON alt efter hvad klienten har indikeret i Accept header feltet. Hvis feltet ikke er medsendt, vil der som standard blive svaret i JSON.

ErrorResponse : object

Error : object

InnerError : object

2.4       HTTP endpoints

Der udstilles en adresse til hvert af de dokumenttyper man kan udveksle med DataHub.

2.5       Identifikation af besked type

For at hente et dokument fra DataHub sker det via en GET-kanal. Hver kanal kan returnere én eller flere dokumenttyper. Den pågældende dokumenttype kan læses fra http-headeren MessageType. For en komplet liste af dokumenttyper der kan modtages, kan dette ses i appendix –

2.6       Azure B2C – Oauth

OAuth 2.0 [RFC 6749] er et rammeværk, der muliggør tredjeparts adgang til beskyttet HTTP endpoints. Den OAuth metode der benyttes i DataHub 3 er Client Credentials Grant, som er en metode der oftest benyttes til server-til-server kommunikation.

Nedenstående diagram viser forløbet, når en aktør trækker en JWT token og benytter denne til at kalde DataHubs API i forbindelse med aktørtesten, der påbegyndes i februar 2022. Nedenstående kald tager udgangspunkt i ping-endpoint'et i ovenstående tabel.

Bearer token trækkes via et POST:

Path: 20e7a6b4-86e0-4e7a-a34d-6dc5a75d1982/oauth2/v2.0/token HTTP/1.1

Host: login.microsoftonline.com/

Content-Type: application/x-www-form-urlencoded

Content-Length: 185

grant_type=client_credentials&client_id=client_id_provided_by_energinet&scope=54ff4628-ddb1-41ad-9fb0-60286da90d87%2F.default&client_secret=client_secret_provided_by_energinet

HTTP-kaldets body skal bestå af følgende key-value pairs.

Positiv tilbagemelding:

{

   "token_type": "Bearer",

   "expires_in": 3599,

   "ext_expires_in": 3599,

   "access_token": " <bearer-token>"

}

Negativ tilbagemelding

{

  "error": <Fejlkode til at klassifisere fejltyper og reagere på dem>,

  "error_description": <Fejlmeddelelse til at identificere root cause>,

  "error_codes": [<Liste af STS-specifikke fejlkoder>],

  "timestamp": <Tidspunktet for hvornår fejlen opstod>,

  "trace_id": <Unikt ID for forespørgslen til fejlfinding>,

  "correlation_id": <Unikt ID for forespørgslen>,

  "error_uri": <link til hvor information om fejltypen findes>

}Kommuniker med DataHub 3:

1. Client secret

Hvis I kender jeres "Client Id/Client secret" så spring dette step over!

1. PREPROD:
   Naviger til DataHub 3 https://preprod.datahub3.dk/market-participant/actors og naviger til Aktør-fanen.
   
   PROD:
   Naviger til DataHub 3 https://datahub3.dk/market-participant/actors og naviger til Aktør-fanen.

2. Vælg fanen ‘B2B adgang’ og generer jeres Client ID og jeres Client Secret.

3. Gem jeres Client Id og Client Secret, da i ikke vil kunne se jeres Client Secret igen senere.

Note: En Client Secret har en løbetid på 12 mdr. og derfor skal denne proces gentages årligt. Udløbsdatoen er angivet i DataHub 3 skærmbilledet ‘Aktører → <egen aktør> → B2B adgang’.

❗ Vær opmærksom på, at forskellige roller kræver særskilte client secrets. F.eks. har man et client secret for en elleverandør, så kan dette client secret IKKE benyttes til handlinger hvor elleverandør rollen ikke må foretage disse handlinger. Hver rolle kræver altså deres eget client secret.

2. Bearer token

Kald endpoint for at få udleveret bearer token

Så returneres bearer token i jeres svar.

Vær opmærksom på, at bearer token har en kort levetid på 1 time.

3. Kald DataHub

NotifyAggregated MeasureData RSM-014 og Notifywholesaleservices RSM-019

Header Content-Type kan enten være application/json eller application/xml

Dequeue

Message ID på den besked der skal dequeues findes i svaret på Peek request’et

Request aggregated measure data RSM-016

Header Content-Type kan enten være application/json eller application/xml

Body skal indeholde en skema valid RSM-016 enten i XML eller JSON. Her et et eksempel på XML:

<?xml version="1.0" encoding="UTF-8"?>
<cim:RequestAggregatedMeasureData_MarketDocument xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cim="urn:ediel.org:measure:requestaggregatedmeasuredata:0:1" xsi:schemaLocation="urn:ediel.org:measure:requestaggregatedmeasuredata:0:1 urn-ediel-org-measure-requestaggregatedmeasuredata-0-1.xsd">
  <cim:mRID></cim:mRID>
  <cim:type>E74</cim:type>
  <cim:process.processType>D03</cim:process.processType>
  <cim:businessSector.type>23</cim:businessSector.type>
  <cim:sender_MarketParticipant.mRID codingScheme="A10"></cim:sender_MarketParticipant.mRID>
  <cim:sender_MarketParticipant.marketRole.type></cim:sender_MarketParticipant.marketRole.type>
  <cim:receiver_MarketParticipant.mRID codingScheme="A10">5790001330552</cim:receiver_MarketParticipant.mRID>
  <cim:receiver_MarketParticipant.marketRole.type>DGL</cim:receiver_MarketParticipant.marketRole.type>
  <cim:createdDateTime>2022-12-17T09:30:47Z</cim:createdDateTime>
  <cim:Series>
    <cim:mRID></cim:mRID>
    <!-- <cim:settlement_Series.version>D01</cim:settlement_Series.version> -->
    <cim:marketEvaluationPoint.type>E17</cim:marketEvaluationPoint.type>
    <cim:marketEvaluationPoint.settlementMethod>D01</cim:marketEvaluationPoint.settlementMethod>
    <cim:start_DateAndOrTime.dateTime>2023-01-01T23:00:00Z</cim:start_DateAndOrTime.dateTime>
    <cim:end_DateAndOrTime.dateTime>2022-01-22T23:00:00Z</cim:end_DateAndOrTime.dateTime>
    <cim:meteringGridArea_Domain.mRID codingScheme="NDK">804</cim:meteringGridArea_Domain.mRID>
    <!--<cim:energySupplier_MarketParticipant.mRID codingScheme="A10"></cim:energySupplier_MarketParticipant.mRID>-->
    <cim:balanceResponsibleParty_MarketParticipant.mRID codingScheme="A10"></cim:balanceResponsibleParty_MarketParticipant.mRID>
  </cim:Series>
</cim:RequestAggregatedMeasureData_MarketDocument>

Request wholesale settlementdata RSM-017

Header Content-Type kan enten være application/json eller application/xml

Body skal indeholde en skema valid RSM-017 enten i XML eller JSON. Her et et eksempel på XML:

<?xml version="1.0" encoding="UTF-8"?>
<!--Sample XML file generated by XMLSpy v2021 rel. 3 (x64) (http://www.altova.com)-->
<cim:RequestWholesaleSettlement_MarketDocument xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cim="urn:ediel.org:measure:requestwholesalesettlement:0:1" xsi:schemaLocation="urn:ediel.org:measure:requestwholesalesettlement:0:1 urn-ediel-org-measure-requestwholesalesettlement-0-1.xsd">
	<cim:mRID></cim:mRID>
	<cim:type>D21</cim:type>
	<cim:process.processType>D05</cim:process.processType>
	<cim:businessSector.type>23</cim:businessSector.type>
	<cim:sender_MarketParticipant.mRID codingScheme="A10">5799999933318</cim:sender_MarketParticipant.mRID>
	<cim:sender_MarketParticipant.marketRole.type>DDQ</cim:sender_MarketParticipant.marketRole.type>
	<cim:receiver_MarketParticipant.mRID codingScheme="A10">5790001330552</cim:receiver_MarketParticipant.mRID>
	<cim:receiver_MarketParticipant.marketRole.type>DDZ</cim:receiver_MarketParticipant.marketRole.type> <!--ROLE uklar -->
	<cim:createdDateTime>2022-12-17T09:30:47Z</cim:createdDateTime>
	<cim:Series>
		<cim:mRID></cim:mRID>
		<cim:settlement_Series.version>D01</cim:settlement_Series.version>
		<cim:start_DateAndOrTime.dateTime>2023-02-01T23:00:00Z</cim:start_DateAndOrTime.dateTime>
		<cim:end_DateAndOrTime.dateTime>2022-02-28T23:00:00Z</cim:end_DateAndOrTime.dateTime>
		<cim:meteringGridArea_Domain.mRID codingScheme="NDK">244</cim:meteringGridArea_Domain.mRID>
		<cim:energySupplier_MarketParticipant.mRID codingScheme="A10">5799999933318</cim:energySupplier_MarketParticipant.mRID>
		<cim:chargeTypeOwner_MarketParticipant.mRID codingScheme="A10">570001110111</cim:chargeTypeOwner_MarketParticipant.mRID> 
		<cim:aggregationSeries_Period.resolution>PT1M</cim:aggregationSeries_Period.resolution> <!-- kun i forbindelse med BRS-030 -->
		<cim:ChargeType>
			<cim:type>D03</cim:type>
			<cim:mRID>EA-001</cim:mRID>
		</cim:ChargeType>
	</cim:Series>
</cim:RequestWholesaleSettlement_MarketDocument>

4. Postman collection

Vi har lavet en postman collection der tager udgangspunkt i ovenstående, som kan hjælpe dig med at komme hurtigt igang.

Postman collection’en kan hentes her, og den indeholder en beskrivelse af hvordan man skal bruge den.

5. .NET eksempel

Du kan finde inspiration i vores acceptance test til hvordan du kan oprette en C# http client, som kan kommuniker med DataHub 3 ud fra ovenstående. Repositoriet kan findes her: https://github.com/Energinet-DataHub/opengeh-edi/tree/main/source/AcceptanceTests/Tests.

Selve kommunikationen med DataHub 3 sker her: https://github.com/Energinet-DataHub/opengeh-edi/blob/main/source/AcceptanceTests/Drivers/EdiDriver.cs

6. Logning

Alle Http svar fra DataHub vil have en header som hedder ‘correlationId’ som man ville kunne referer til ved kald som fejler, det kunne være til en stor hjælp at hvis der opstod fejl i takt med kommunikation med DataHub, at man loggede ‘correlationId’ sammen med en tilhørende fejlbesked for at vi nemmere kan supporter henvendelser.

7. Samlet oversigt

Der findes en samlet oversigt over