blob: 8291a487e7ce411a2dff5367a32d4415a1f222a5 [file] [log] [blame]
swagger: '2.0'
info:
title: Topologie
description: Diese Schnittstelle ist Teil der [oK](http://www.openkonsequenz.de) Domänen API.
version: Revision 2 (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:
/topology:
get:
summary: Die Schnittstelle gibt (Teil-)Topologien zurück. Es kann die definierte Topologie abgefragt werden. Dabei kann der Ausschnitt der abgefragten Topologie durch Selektionsparameter eingeschränkt 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 eindeutige 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 kann die definierte Topologie abgefragt werden. Dabei kann der Ausschnitt der abgefragten Topologie durch Selektionsparameter 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 eindeutige 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.
parameters:
- name: revision
in: query
description: Version, die den Nachrichtenaustausch definiert. Dies ist nicht die CIM-Version.
required: true
type: integer
format: int32
minimum: 2
maximum: 2
- 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: 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:
### 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: 2
maximum: 2
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