blob: 4a507051c1cd1e453d1cf4e36d2495e1ccfaa9ad [file] [log] [blame]
swagger: '2.0'
info:
title: verbundene topologische Verbindungselemente
description: Diese Schnittstelle ist Teil der [oK](http://www.openkonsequenz.de) Domänen API.
version: Revision 1 (CIM 17v07)
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: /domain/electricity/dynamic-topology
produces:
- application/xml
paths:
/connected-connecting-equipments:
get:
summary: Die Schnittstelle gibt, die mit einem Wandler verbundenen topologische Verbindungselemente zurück. Es können die topologischen Verbindungselemente aus der Topologie, die mit einem Wandler verbunden sind, abgefragt werden. Als Wandler wir in diesem Context eine topologische Ressource bezeichnet, die bestimmte Größen innerhalb der Topologie transformieren kann. In elektrischen Netzen sind dies beispielsweise Transformatoren, in Gasnetzen sind dies Druckminderungs- oder Druckerhöhungsanlagen. Die Auswahl der zurückgegebenen topologischen Verbindungselemente kann durch Filterparameter eingeschränkt werden. Mithilfe des Parameters 'converter-id' kann die Abfrage auf die eindeutige Kennung eines Wandlers eingeschränkt werden. Unbekannte Kennungen werden ignoriert. Der Parameter 'topological-resource-types' schränkt die benutzerspezifischen Typen von topologischen Ressourcen ein, die zurückgegeben werden sollen. Verschiedene Kennungen können mit Hilfe des Zeichens '|' getrennt werden. Wird ein benutzerspezifischer Typ angegeben, werden alle topologischen Ressourcen dieses Typs zurückgegeben. Wird keine Kennung angegeben, werden alle topologischen Ressourcen zurückgegeben. Unbekannte Kennungen werden ignoriert. Der Parameter 'connection-state' gibt an, wie die Ressourcen, die Teil der Selektion sein sollen, mit dem Ausgangspunkt verknüpft sein sollen (z. B. unter Schalternormalstellung, unter aktueller Schalterstellung). Der Parameter 'selector' gibt an, welche Ressourcen vom Ausgangspunkt aus bei der Selektion mit berücksichtigt werden sollen (z. B. alle Ressourcen innerhalb des gewählten Umspannwerks). Die Grenzen sind in der Regel Netzbereiche mit anderen Nennspannungen.
description: |
Mit Hilfe dieser Schnittstelle können die topologischen Verbindungselemente aus der Topologie, die mit einem Wandler verbunden sind, abgefragt werden. Als Wandler wir in diesem Context eine topologische Ressource bezeichnet, die bestimmte Größen innerhalb der Topologie transformieren kann. In elektrischen Netzen sind dies beispielsweise Transformatoren, in Gasnetzen sind dies Druckminderungs- oder Druckerhöhungsanlagen. Die Auswahl der zurückgegebenen topologischen Verbindungselemente kann durch Filterparameter eingeschränkt werden.
\
Mit dieser Schnittstelle zum Beispiel folgende Abfragen realisert werden:
- alle Einspeiser unterhalb (auf der Sekundärseite) eines Transformators
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}$'
- name: topology-id
in: query
description: Eindeutige Kennung der Topologie, für die der aktuelle Aufruf erfolgt. Wird der Parameter nicht angegeben, bezieht sich die Abfrage auf die aktuelle Topologie.
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}$'
- name: converter-id
in: query
description: Eindeutige Kennung des Wandlers. Unbekannte Kennungen werden ignoriert.
required: true
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}$'
- name: topological-resource-types
in: query
description: Die Typen der zu suchenden topologischen Ressourcen. Verschiedene Typen können mit Hilfe des Zeichens '|' getrennt werden. Diese Typen können über die Schnittstelle <b>domain/electricity/dynamic-topology/power-system-resource-types</b> abgefragt werden. Unbekannte Typen werden ignoriert. Wird keine Kennung angegeben, werden alle Typen berücksichtigt.
required: false
type: string
- name: connection-state
in: query
description: >
Der Verknüpfungsstatus:
* `Active` - verknüpfte topologische Ressourcen unter Berücksichtigung der aktuellen Unterbrecherstellung (z. B. Schalterstellung, Schieberstellung)
* `Ignore (default)` - verknüpfte topologische Ressourcen unter Vernachlässigung der Unterbrecherstellung (z. B. Schalterstellung, Schieberstellung)
* `Normal` - verknüpfte topologische Ressourcen unter Berücksichtigung der Unterbrechernormalstellung (z. B. Schalterstellung, Schieberstellung)
required: false
type: string
default: Ignore
enum: [Active, Ignore, Normal]
- name: selector
in: query
description: >
Die Selektionsbereichsbegrenzung:
* `Above` - die topologischen Ressourcen auf der höherwertigen Seite des Wandlers (z. B. Primärseite des Transformators, höhere Druckebene)
* `Behind` - die topologischen Ressourcen auf den niederwertigen Seite des Wandlers (z. B. Sekundärseiten des Transformators, niedrigere Druckebene)
required: false
type: string
default: Behind
enum: [Above, Behind]
responses:
200:
description: Die CIM-Antwortnachricht.
schema:
$ref: '#/definitions/ResponseMessage'
400:
description: Die Schnittstelle wurde mit ungültigen Parametern aufgerufen.
410:
description: Die Topologie mit der angegebenen Kennung ist nicht mehr gültig.
500:
description: Es trat ein allgemeiner Fehler bei der Verarbeitung der Anfrage auf.
definitions:
### specific definitions ######################################################
Payload:
description: Der Inhalt der CIM-Antwortnachricht.
type: object
properties:
TopologicalResources:
$ref: '#/definitions/PowerSystemResources'
required:
- PowerSystemResources
PowerSystemResources:
description: Auflistung der topologischen Ressourcen
type: object
properties:
ACLineSegment:
description: optionale Auflistung der Leitungsabschnitte (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.ac-line-segments_GET_3_de.open-api.yaml#/definitions/ACLineSegment'
BaseVoltages:
description: optionale Auflistung der Nennspannungen (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.base-voltages_GET_3_de.open-api.yaml#/definitions/BaseVoltage'
Bays:
description: optionale Auflistung der Felder (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.bays_GET_2_de.open-api.yaml#/definitions/Bay'
Breakers:
description: optionale Auflistung der Leistungsschalter (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.breakers_GET_3_de.open-api.yaml#/definitions/Breaker'
BusbarSection:
description: optionale Auflistung der Sammelschienen (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.busbar-sections_GET_3_de.open-api.yaml#/definitions/BusbarSection'
Disconnectors:
description: optionale Auflistung der Trennschalter (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.disconnectors_GET_3_de.open-api.yaml#/definitions/Disconnector'
EarthFaultCompensators:
description: optionale Auflistung der Erdungswiderstände (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.earth-fault-compensators_GET_1_de.open-api.yaml#/definitions/EarthFaultCompensator'
EnergyConsumer:
description: optionale Auflistung der Verbraucher (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.energy-consumers_GET_3_de.open-api.yaml#/definitions/EnergyConsumer'
EnergySources:
description: optionale Auflistung der Einspeiser (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.energy-sources_GET_3_de.open-api.yaml#/definitions/EnergySource'
GeographicalRegions:
description: optionale Auflistung der Netzgebiete (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.geographical-regions_GET_3_de.open-api.yaml#/definitions/GeographicalRegion'
GroundingImpedances:
description: optionale Auflistung der Erdschlussdrossel (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.grounding-impedances_GET_1_de.open-api.yaml#/definitions/GroundingImpedance'
Grounds:
description: optionale Auflistung der Erdung (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.grounds_GET_1_de.open-api.yaml#/definitions/Ground'
Junctions:
description: optionale Auflistung der Muffen (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.junctions_GET_3_de.open-api.yaml#/definitions/Junction'
Lines:
description: optionale Auflistung der Leitungen (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.lines_GET_3_de.open-api.yaml#/definitions/Line'
LineTypes:
description: optionale Auflistung der Leitungsarten (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.line-types_GET_2_de.open-api.yaml#/definitions/PSRType'
LoadBreakSwitches:
description: optionale Auflistung der Lastgangschalter (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.load-break-switches_GET_3_de.open-api.yaml#/definitions/LoadBreakSwitch'
PetersenCoils:
description: optionale Auflistung der Petersenspulen (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.petersen-coils_GET_1_de.open-api.yaml#/definitions/PetersenCoil'
Plants:
description: optionale Auflistung der Kraftwerke (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.plants_GET_2_de.open-api.yaml#/definitions/Plant'
PowerTransformers:
description: optionale Auflistung der Transformatoren (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.power-transformers_GET_3_de.open-api.yaml#/definitions/PowerTransformer'
SubGeographicalRegions:
description: optionale Auflistung der Teilnetzgebiete (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.sub-geographical-regions_GET_2_de.open-api.yaml#/definitions/SubGeographicalRegion'
Substations:
description: optionale Auflistung der Stationen (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.substations_GET_3_de.open-api.yaml#/definitions/Substation'
SubstationTypes:
description: optionale Auflistung der Stationsarten (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.substation-types_GET_3_de.open-api.yaml#/definitions/PSRType'
Switches:
description: optionale Auflistung der Schalter (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.switches_GET_2_de.open-api.yaml#/definitions/Switch'
VoltageLevels:
description: optionale Auflistung der Spannungsebenen (falls abgefragt)
type: array
minItems: 0
items:
$ref: '../../../source-system/electricity/static-topology/source-system.electricity.static-topology.voltage-levels_GET_3_de.open-api.yaml#/definitions/VoltageLevel'
### common definitions ########################################################
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: 1
maximum: 1
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
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}$'
User:
$ref: '#/definitions/UserID'
required:
- Verb
- Noun
- Revision
- Timestamp
- Source
- MessageID
- User
xml:
name: Header
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
UserID:
properties:
id:
description: Eindeutige Kennung des angemeldeten Nutzers (Empfänger).
type: string
xml:
name: UserID