blob: ba0e5df3ff2f86c2fada47fd9c42e0dc7157c1fa [file] [log] [blame]
swagger: '2.0'
info:
title: Einspeiserstammdaten
description: Diese Schnittstelle ist Teil der [oK](http://www.openkonsequenz.de) Quellsystem-API.
version: Revision 1 (cim-profile openkonsequenz)
contact:
name: BTC AG
url: http://www.btc-ag.com
email: openk@btc-ag.com
license:
name: Eclipse Public License 1.0
url: https://www.eclipse.org/legal/epl-v10.html
host: api.openk.de
schemes:
- http
basePath: /source-system/electricity/asset-data
produces:
- application/xml
paths:
/energy-sources:
get:
summary: Die Schnittstelle gibt die Stammdaten aller Einspeiser im gesamten Netzgebiet der Topologie zurück. Die Stammdaten enthalten neben den elektrischen Eigenschaften des Einspeisers ebenfalls Informationen über Kommunikationseigenschaften, Absenkprioritäten, den geografischen Standort sowie die Referenz auf den/die Betreiber des Einspeisers. Weiterhin geben die zurückgegebenen Daten Aufschluss über den Standort der Anlage im elektrischen Netz.
parameters:
- name: revision
in: query
description: Version, die den Nachrichtenaustausch definiert. Dies ist nicht die CIM-Version.
required: true
type: integer
format: int32
minimum: 1
maximum: 1
- name: timestamp
in: query
description: Zeitpunkt, an dem die Nachricht versendet wurde (in UTC gemäß ISO-8601-Format YYYY-MM-DDTHH:mm:ss.SSSZ).
required: false
type: string
format: date-time
pattern: '^([0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|30|31)T(([0-1][0-9])|(2[0-3]))(:[0-5][0-9]){2}\.[0-9]{3}Z)$'
- name: source
in: query
description: Eindeutige Bezeichnung des Senders der Nachricht.
required: false
type: string
- name: user-id
in: query
description: Eindeutige Kennung des angemeldeten Nutzers (Sender).
required: false
type: string
- name: message-id
in: query
description: Eindeutige Kennung dieser Nachricht. Generiert vom Sender der Nachricht.
required: false
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
responses:
200:
description: Die CIM-Antwortnachricht.
schema:
$ref: '#/definitions/ResponseMessage'
400:
description: Die Schnittstelle wurde mit ungültigen Parametern aufgerufen.
500:
description: Es trat ein allgemeiner Fehler bei der Verarbeitung der Anfrage auf.
definitions:
### specific definitions ######################################################
oK:EnergySource:
description: Einspeiser
type: object
properties:
oK:mRID:
description: Eindeutige Kennung des Einspeisers.
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
oK:name:
description: Name des Einspeisers.
type: string
minLength: 1
maxLength: 64
oK:description:
description: Beschreibung des Einspeisers.
type: string
minLength: 1
maxLength: 2048
Names:
description: Referenzen auf alternative Namen.
type: array
minItems: 0
items:
$ref: '#/definitions/Name'
xml:
wrapped: true
oK:commissioningDate:
description: Datum der Inbetriebnahme des Einspeisers.
type: string
format: date-time
pattern: '^([0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|30|31)T(([0-1][0-9])|(2[0-3]))(:[0-5][0-9]){2}\.[0-9]{3}Z)$'
oK:communicationGroup:
description: Kommunikationsgruppe des Einspeisers.
type: string
minLength: 1
maxLength: 64
oK:communicationType:
description: Kommunikationstyp des Einspeisers.
type: string
enum:
- RadioTeleswitch
- RemoteTerminalUnit
oK:energySourceType:
description: Der Typ des Einspeisers.
type: string
enum:
- Biogas
- MicroCogeneration
- Photovoltaic
- Wind
oK:installedActivePower:
$ref: '#/definitions/oK:EnergySource.installedActivePower'
oK:Location:
$ref: '#/definitions/oK:EnergySource.Location'
oK:nominalVoltage:
$ref: '#/definitions/oK:EnergySource.nominalVoltage'
oK:Operator:
$ref: '#/definitions/oK:EnergySource.Operator'
oK:referenceEnergySource:
description: Referenz auf einen Einspeiser mit den gleichen oder ähnlichen Eigenschaften.
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
oK:regulatingActivePower:
$ref: '#/definitions/oK:EnergySource.regulatingActivePower'
oK:regulatingPriority:
description: Benutzerspezifische Absenkpriorität des Einspeisers.
type: integer
format: int32
minimum: 1
maximum: 5
oK:regulatingRanking:
description: Absenkpriorität des Einspeisers nach BDEW.
type: integer
format: int32
minimum: 1
maximum: 17
oK:regulatingSteps:
description: Die Regelstufen der Einspeiser in Prozent. Die Wert werden ganzzahlig und ohne Prozentzeichen angegeben. Mehrere Werte können mit Hilfe des Zeichens '|' getrennt werden. Z. B. '10|30|60|100'
type: string
pattern: '^(([1-9][0-9]{0,2})([|]([1-9][0-9]{0,2}))*)$'
oK:TopologicalResource:
$ref: '#/definitions/oK:EnergySource.TopologicalResource'
required:
- oK:mRID
- oK:TopologicalResource
xml:
name: EnergySource
prefix: 'oK'
oK:EnergySource.installedActivePower:
description: Installierte Leistung des Einspeisers.
type: object
allOf:
- $ref: '#/definitions/ActivePower'
oK:EnergySource.Location:
description: Der Standort bzw. die Position des Einspeisers.
type: object
properties:
Location:
$ref: '#/definitions/Location_Reference'
required:
- Location
oK:EnergySource.nominalVoltage:
description: Nennspannung des Einspeisers.
type: object
allOf:
- $ref: '#/definitions/Voltage'
oK:EnergySource.Operator:
description: Der Betreiber des Einspeisers.
type: object
properties:
Operator:
$ref: '#/definitions/Organisation_Reference'
required:
- Operator
oK:EnergySource.regulatingActivePower:
description: Regelbare Leistung des Einspeisers.
type: object
allOf:
- $ref: '#/definitions/ActivePower'
oK:EnergySource.TopologicalResource:
description: Referenz auf die topologische Resource. Dies ist die Anlage in der statischen Topologie.
type: object
properties:
oK:TopologicalResource:
$ref: '#/definitions/TopologicalResource_Reference'
required:
- oK:TopologicalResource
EnergySources:
description: Die Auflistung der Einspeiserstammdaten.
type: array
items:
$ref: '#/definitions/oK:EnergySource'
xml:
wrapped: true
Payload:
description: Der Inhalt der CIM-Antwortnachricht.
type: object
properties:
EnergySources:
$ref: '#/definitions/EnergySources'
required:
- EnergySources
### common definitions ########################################################
ActivePower:
description: Wirkleistung.
type: object
properties:
multiplier:
description: Multiplikator der Wirkleistung (CIM UnitMultiplier)
type: string
enum:
- a
- c
- d
- da
- E
- f
- G
- h
- k
- m
- M
- micro
- n
- none
- p
- P
- T
- y
- Y
- z
- Z
unit:
description: Einheit der Wirkleistung (CIM UnitSymbol)
type: string
default: W
enum:
- W
value:
description: Wert der Wirkleistung
type: number
format: float
minimum: 0
required:
- multiplier
- unit
- value
Header_Reply:
description: Der Kopf der CIM-Nachricht.
type: object
properties:
Verb:
description: Hinweis, um welche Art von Nachricht es sich handelt.
type: string
default: reply
Noun:
description: Hinweis auf den Nachrichteninhalt.
type: string
Revision:
description: Version, die den Nachrichtenaustausch definiert. Dies ist nicht die CIM-Version.
type: integer
format: int32
minimum: 3
maximum: 3
Timestamp:
description: Zeitpunkt, an dem die Nachricht versendet wurde (in UTC gemäß ISO-8601-Format YYYY-MM-DDThh:mm:ss.sssZ).
type: string
format: date-time
pattern: '^([0-9]{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|30|31)T(([0-1][0-9])|(2[0-3]))(:[0-5][0-9]){2}\.[0-9]{3}Z)$'
Source:
description: Eindeutige Bezeichnung des Senders der Nachricht.
type: string
User:
$ref: '#/definitions/User'
MessageID:
description: Eindeutige Kennung dieser Nachricht. Generiert vom Sender der Nachricht.
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
required:
- Verb
- Noun
- Revision
- Timestamp
- Source
- MessageID
xml:
name: Header
Location_Reference:
description: Referenz auf den Standort bzw. die Position.
type: object
properties:
mRID:
description: eindeutige Kennung des Standorts bzw. der Position
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
required:
- mRID
xml:
name: Location
Name:
description: alternativer Name
type: object
properties:
name:
description: ein alternativer Name (z. B. Kennung aus dem Quellsystem)
type: string
minLength: 1
maxLength: 256
NameType:
$ref: '#/definitions/Name.NameType'
required:
- name
- NameType
xml:
name: Name
Name.NameType:
properties:
NameType:
$ref: '#/definitions/NameType'
xml:
name: NameType
NameType:
description: Namenstyp.
type: object
properties:
name:
description: Name des Namentyps.
type: string
minLength: 1
maxLength: 256
description:
description: Beschreibung des Namentyps.
type: string
minLength: 1
maxLength: 2048
NameTypeAuthority:
$ref: '#/definitions/NameType.NameTypeAuthority'
required:
- name
- NameTypeAuthority
xml:
name: NameType
NameType.NameTypeAuthority:
properties:
NameTypeAuthority:
$ref: '#/definitions/NameTypeAuthority'
xml:
name: NameTypeAuthority
NameTypeAuthority:
description: Vergabestelle des Namentyps.
type: object
properties:
name:
description: Name der Vergabestelle des Namentyps.
type: string
minLength: 1
maxLength: 256
description:
description: Beschreibung des Namentyps.
type: string
minLength: 1
maxLength: 2048
required:
- name
xml:
name: NameTypeAuthority
Organisation_Reference:
description: Referenz auf das Unternehmen
type: object
properties:
mRID:
description: eindeutige Kennung des Unternehmens
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
required:
- mRID
xml:
name: Organisation
Reply_OK:
description: Die Antwort der CIM-Nachricht.
type: object
properties:
Result:
description: Antworttext
type: string
default: OK
required:
- Result
xml:
name: Reply
ResponseMessage:
description: Die CIM-Antwortnachricht.
type: object
properties:
Header:
$ref: '#/definitions/Header_Reply'
Reply:
$ref: '#/definitions/Reply_OK'
Payload:
$ref: '#/definitions/Payload'
required:
- Header
- Reply
- Payload
TopologicalResource_Reference:
description: Referenz auf die topologische Ressource
type: object
properties:
oK:mRID:
description: eindeutige Kennung der topologischen Ressource
type: string
format: uuid
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
required:
- oK:mRID
xml:
name: oK:TopologicalResource
User:
properties:
userId:
description: Eindeutige Kennung des angemeldeten Nutzers (Empfänger).
type: string
xml:
name: UserID
required:
- UserID
Voltage:
description: Spannung
type: object
properties:
multiplier:
description: Multiplikator der Spannung (CIM UnitMultiplier)
type: string
enum:
- a
- c
- d
- da
- E
- f
- G
- h
- k
- m
- M
- micro
- n
- none
- p
- P
- T
- y
- Y
- z
- Z
unit:
description: Einheit der Spannung (CIM UnitSymbol)
type: string
default: V
enum:
- V
value:
description: Wert der Spannung
type: number
format: float
minimum: 0
required:
- multiplier
- unit
- value