CIM webservice interface (Getting started)

Kommuniker med DataHub 3:

1 1. Client secret
2 2. Bearer token
- 2.1 PREPROD
- 2.2 PROD
3 3. Kald DataHub
4 4. Postman collection
5 5. .NET eksempel
6 6. Logning
7 7. Samlet oversigt

1. Client secret

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

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.
Vælg fanen ‘B2B adgang’ og generer jeres Client ID og jeres Client Secret.
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

PREPROD

[POST] https://login.microsoftonline.com/20e7a6b4-86e0-4e7a-a34d-6dc5a75d1982/oauth2/v2.0/token

[Required Header]
Content-Type: application/x-www-form-urlencoded

[Body]
grant_type=client_credentials&client_id={{Client Id fra step 1}}&client_secret={{Client Secret fra step 1}}&scope=65877f1b-1aef-42b3-adc7-3009608f27a3/.default

PROD

[POST] https://login.microsoftonline.com/4b8c3f88-6cca-480c-af02-b2d2f220913f/oauth2/v2.0/token

[Required Header]
Content-Type: application/x-www-form-urlencoded

[Body]
grant_type=client_credentials&client_id={{Client Id fra step 1}}&client_secret={{Client Secret fra step 1}}&scope=336add08-dc41-44ba-abaa-bbd856c01390/.default

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

Find url på denne side: Dokumenttype og deres relation til kø’er og endpoint. - DataHub Docs & DX - Confluence

[Required Header]
Content-Type: application/json
Authorization: Bearer {{Bearer token fra step 2}}

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

Httpkoder	Beskrivelse

Httpkoder	Beskrivelse
200	OK - besked returneret.
204	OK - ingen beskeder.
415	Unsupported Media Type - Manglede/forkert angivet content-type.
503	DataHub 3 er i maintenance mode. Forsøg at kalde igen om 5 minutter.

Dequeue

Find url på denne side: Dokumenttype og deres relation til kø’er og endpoint. - DataHub Docs & DX - Confluence

[Required Header]
Authorization: Bearer {{Bearer token fra step 2}}

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

Httpkoder	Beskrivelse

Httpkoder	Beskrivelse
200	Besked kvitteret for, fjernet fra køen.
400	Besked kunne ikke kvitteres for.
503	DataHub 3 er i maintenance mode. Forsøg at kalde igen om 5 minutter.

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>

Httpkoder	Beskrivelse

Httpkoder	Beskrivelse
202	Accepted - DataHub har modtaget anmodningen.
400	Bad request - fejl i takt med synkron validering.
415	Unsupported Media Type - Manglede/forkert angivet content-type.
503	DataHub 3 er i maintenance mode. Forsøg at kalde igen om 5 minutter.

Krævet rolle (én af disse roller skal være udstillet fra token der benyttes)

Krævet rolle (én af disse roller skal være udstillet fra token der benyttes)
metereddataresponsible
energysupplier
balanceresponsibleparty
gridaccessprovider
delegated

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>

Httpkoder	Beskrivelse

Httpkoder	Beskrivelse
202	Accepted - DataHub har modtaget anmodningen.
400	Bad request - fejl i takt med synkron validering.
415	Unsupported Media Type - Manglede/forkert angivet content-type.
503	DataHub 3 er i maintenance mode. Forsøg at kalde igen om 5 minutter.

Krævet rolle (én af disse roller skal være udstillet fra token der benyttes)

Krævet rolle (én af disse roller skal være udstillet fra token der benyttes)
energysupplier
delegated
systemoperator
gridaccessprovider

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