blob: c32df32a56c1db6028833c225cea36d4f1208e37 [file] [log] [blame]
swagger: '2.0'
info:
title: topologische Ressourcen
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:
/power-system-resources:
get:
summary: Die Schnittstelle gibt die Ressourcen eines bestimmten Typs aus der Topologie zurück. Es können die Ressourceninstanzen eines bestimmten Typs aus der Topologie abgefragt werden. Dabei kann die Auswahl der Ressourcen durch Selektions- und Filterparameter eingeschränkt werden. Der Parameter 'power-system-resources' schränkt die Abfrage auf die Typen der zu suchenden Ressourcen ein. Diese können über die Schnittstelle <b>domain/electricity/dynamic-topology/power-system-resource-types</b> abgefragt werden. Die Selektion erfolgt über die Wahl eines Ausgangspunkts, der Angabe des Verknüpfungsstatus und einer Selektionsbereichsbegrenzung. Mithilfe des Parameters 'entry-point-id' können alle topologischen Elemente (z. B. Schalter, Transformatoren) oder Element-Container (z. B. Umspannwerke, Teilnetzgebiete) als Ausgangspunkt verwendet werden. Diese werden über die Angabe ihrer eindeutigen Kennungen gewählt. 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. Die Abrufmethode über den Parameter 'fetch-type' definiert, welche Ebenen bei der Abfrage eines Element-Containers berücksichtigt werden. Die Selektion ist optional. Wird sie weggelassen, wird die gesamte Topologie berücksichtigt.
description: |
Mit Hilfe dieser Schnittstelle können die Ressourceninstanzen eines bestimmten Typs aus der Topologie abgefragt werden. Dabei kann die Auswahl der Ressourcen durch Selektions- und Filterparameter eingeschränkt werden.
\
Die Selektion erfolgt über die Wahl eines Ausgangspunkts, der Angabe des Verknüpfungsstatus und einer Selektionsbereichsbegrenzung:
- Als Ausgangspunkt können alle topologischen Elemente (z. B. Schalter, Transformatoren) oder Element-Container (z. B. Umspannwerke, Teilnetzgebiete) verwendet werden. Diese werden über die Angabe ihrer eindeutigen Kennungen gewählt.
- Der Verknüpfungsstatus 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)
- Die Selektionsbereichsbegrenzung 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.
- Die Abrufmethode definiert, welche Ebenen bei der Abfrage eines Element-Containers berücksichtigt werden.
Die Selektion ist optional. Wird sie weggelassen, wird die gesamte Topologie berücksichtigt.
\
Zur Ressourcenfilterung müssen die gewünschten Ressourcentypen mit angegeben werden.
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: power-system-resource-types
in: query
description: Der Typ der zu suchenden Ressourcen. Diese können über die Schnittstelle <b>domain/electricity/dynamic-topology/power-system-resource-types</b> abgefragt werden.
required: true
type: string
- name: entry-point-id
in: query
description: Die eindeutige Kennung des Ausgangspunkts.
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: connection-state
in: query
description: >
Der Verknüpfungsstatus:
* `Active` - elektrisch verknüpfte Topologie unter Berücksichtigung der aktuellen Schalterstellung
* `Ignore (default)` - verknüpfte Topologie unter Vernachlässigung der Schalterstellungen
* `Normal` - elektrisch verknüpfte Topologie unter Berücksichtigung der Schalternormalstellung
* `NormalWithSwitchState` - elektrisch verknüpfte Topologie unter Berücksichtigung der Schalterstellung zum Zeitpunkt t
required: false
type: string
default: Ignore
enum: [Active, Ignore, Normal, NormalWithSwitchState]
- name: selector
in: query
description: >
Die Selektionsbereichsbegrenzung:
* `Above` - die Topologie auf der Primärseite des Transformators
* `All` - die gesamte Topologie
* `Behind` - die Topologie auf den Sekundärseiten des Transformators
* `Containing (default)` - die Topologie innerhalb des Element-Containers
* `ContainingAndAbove` - die Topologie innerhalb des Element-Containers und auf der Primärseite des Transformators
* `ContainingAndBehind` - die Topologie innerhalb des Element-Containers und auf den Sekundärseiten des Transformators
required: false
type: string
default: Containing
enum: [All, Above, ContainingAndAbove, Containing, ContainingAndBehind, Behind]
- name: fetch-type
in: query
description: >
Die Abrufmethode:
* `Eager` - alle Ressourcen aller untergeordneten Ebenen des angegebenen Element-Containers werden geladen. Beinhaltet der angegebene Element-Containers also selbst Element-Container, wird deren Inhalt mit berücksichtigt.
* `Lazy (default)` - alle Ressourcen der nächsten untergeordneten Ebene des angegebenen Element-Containers werden geladen. Beinhaltet der angegebene Element-Containers also selbst Element-Container, wird deren Inhalt nicht berücksichtigt.
required: false
type: string
default: Lazy
enum: [Eager, Lazy]
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:
PowerSystemResources:
$ref: '#/definitions/PowerSystemResources'
required:
- PowerSystemResources
PowerSystemResources:
description: Auflistung der Ressourcen
type: object
properties:
Substation:
description: optionale Auflistung der Stationen (falls abgefragt)
type: array
minItems: 0
items:
$ref: '#/definitions/Substation'
Substation:
description: Station
type: object
properties:
mRID:
description: Die eindeutige Kennung der Station.
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:
description: Der Name der Station.
type: string
minLength: 1
maxLength: 64
description:
description: Die Beschreibung der Station.
type: string
minLength: 1
maxLength: 2048
Names:
description: Referenzen auf alternative Namen.
type: array
minItems: 0
items:
$ref: '#/definitions/Name'
xml:
wrapped: true
PSRType:
$ref: '#/definitions/Substation.PSRType'
Equipments:
description: Referenz auf das elektrische leitende Equipment, das zur Station gehört.
type: array
minItems: 1
items:
$ref: '#/definitions/ConductingEquipment_Reference'
xml:
wrapped: true
VoltageLevels:
description: Referenz auf die Spannungsebenen, die zur Station gehören.
type: array
minItems: 0
items:
$ref: '#/definitions/VoltageLevel_Reference'
xml:
wrapped: true
Bays:
description: Referenz auf die Felder, die zur Station gehören.
type: array
minItems: 0
items:
$ref: '#/definitions/Bay_Reference'
xml:
wrapped: true
required:
- mRID
- Equipments
xml:
name: Substation
Substation.PSRType:
description: die Typ-Beschreibung
properties:
PSRType:
$ref: '#/definitions/PSRType_Reference'
required:
- PSRType
xml:
name: PSRType
### common definitions ########################################################
Bay_Reference:
description: Referenz auf das Feld
type: object
properties:
mRID:
description: eindeutige Kennung des Feldes
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: Bay
ConductingEquipment_Reference:
description: Referenz auf elektrisch leitendes Equipment
type: object
properties:
mRID:
description: eindeutige Kennung des elektrisch leitenden Equipments
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: ConductingEquipment
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
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 Namestyps
type: string
minLength: 1
maxLength: 256
description:
description: Beschreibung des Namestyps
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 Namestyps
type: object
properties:
name:
description: Name der Vergabestelle des Namestyps
type: string
minLength: 1
maxLength: 256
description:
description: Beschreibung des Namestyps
type: string
minLength: 1
maxLength: 2048
required:
- name
xml:
name: NameTypeAuthority
PSRType_Reference:
description: Referenz auf die Typ-Beschreibung
type: object
properties:
mRID:
description: eindeutige Kennung der Typ-Beschreibung
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: PSRType
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
VoltageLevel_Reference:
description: Referenz auf die Spannungsebene
type: object
properties:
mRID:
description: eindeutige Kennung der Spannungsebene
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: VoltageLevel