Dieser Service bietet Zugriff auf die URL der Marktpartner, d.h. er gibt die jeweils aktuelle URL eines Marktpartners auf Anfrage aus oder aktualisiert diese. Dafür besitzt der Service eine REST Schnittstelle. Ist die Mandant-URL inaktiv, wird keine Marktpartner Adresse an den AS4 Outbound Market Message Service übergeben und somit keine ausgehende AS4 Kommunikation durchgeführt.
Aktualisierungen der Adressen erfolgt gemäß dem AS4 Adresswechsel Workflows, im hiesigen Kontext als Pathswitch bezeichnet, über den Message Broker. Mithilfe des Pathswitches können Marktparnter und Mandant ihre Adresse aktualisieren.
Features & Nutzung
Der AS4-Address-Service erfüllt folgende Aufgaben:
- Administration der AS4 Adressen (sowohl Mandanten Adressen als auch Partner Adressen)
- REST API zur Administration, genutzt durch die Frontends
- inkl. AS4 Aktivierung / Deaktivierung je Mandant
- asynchrone Benachrichtigung der Backends über Statusänderungen der AS4-Beziehungen
- REST API zur Administration, genutzt durch die Frontends
- Pathswitch Verarbeitung
- Pathswitch Request Erzeugen / Behandeln
- Pathswitch Confirmation Erzeugen / Behandeln
- Pathswitch Nachrichten monitoren über REST API
Der AS4-Adress-Service kann auch über folgende Frontends angesprochen werden:
Mandantenpflege
Jeder Mandant muss zunächst per REST-API angelegt werden. Ein Beispiel-Script zum Erstellen von Mandanten per API-Aufruf ist hier (intern) verfügbar. Beispiel:
curl -X 'POST' "http://localhost:8080/aep-as4-address-service/as4-address/tenants" \
-H 'accept: */*' \
-H 'Content-Type: application/json' \
-d '{"tenantCodes": [99123456]}'
Jede Mandanten-MPID ist im AS4-Address-Service zu hinterlegen. Die zugehörige AS4 Adresse ist zu pflegen und der Mandant muss aktiviert werden.
Ein deaktivierter Mandant verschickt niemals Nachrichten per AS4.
Beim Aktivieren werden Pathswitch-Nachrichten an alle bekannten Partneradressen geschickt, sofern die Partner in Beziehung zum Mandanten stehen.
Falls ein Mandant deaktiviert und reaktiviert wird, werden erneut Pathswitch Nachrichten an alle bekannten Partneradressen, die in Beziehung zum Mandanten stehen, verschickt, auch wenn der Pathswitch vor der Deaktivierung bereits erfolgreich durchgeführt worden ist.
Partnerbeziehungspflege
Jede Partner-ILN kann dem AS4-Address-Service bekannt gemacht werden. Ein Partner muss mit mind. einem Mandanten in Beziehung gesetzt werden.
Für Partner können optional die AS4-Adressen gepflegt werden. Dies ermöglicht das Versenden von Pathswitch Requests. Alternativ könnte auch ein Pathswitch vom Partner verschickt werden.
Ein Beispiel-Script zum Erstellen von Partnerbeziehungen per API-Aufruf ist hier (intern) verfügbar. Beispiel:
curl -X 'POST' "http://localhost:8080/aep-as4-address-service/as4-address/partner-addresses" \
-H 'accept: */*' \
-H 'Content-Type: application/json' \
-d '{"tenantCode": "99123456", "partnerCode": "99765432", "address": "https://blue-energy.de/99765432/as4"}'
Alternativ zur REST-API kann die Partnerbeziehungspflege auch per Frontend erfolgen.
Falls ausgehende AS4 Kommunikation gezielt für einzelne Partner deaktiviert werden soll, sind die zugehörigen Partnerbeziehungen zu löschen.
Pathswitch Monitoring
Über die REST API können Informationen über alle verarbeiteten Pathswitch Requests & Confirmations eingesehen werden. Die Daten enthalten auch Referenzen auf die zugehörigen AS4 Nachrichten, welche über die API des AS4-Message-Service abgerufen werden können.
Hardware Anforderungen
Eine Service-Instanz erfordert mindestens 512 MB RAM.
Wir empfehlen 0,4 CPU-Kerne je Instanz.
Logs werden auf die Festplatte geschrieben, entsprechend muss genügend Speicherplatz vorhanden sein.
Abhängigkeiten
Der Service greift auf einen Message-Broker zu, um Nachrichten zu empfangen und zu versenden.
Der Service greift auf eine SQL Datenbank zu, um Adressen zu speichern. Der Speicherverbrauch ist gering.
REST API Dokumentation
Die API wird durch das Frontend und durch den AS4 Outbound Market Message Service genutzt.
Darüber hinaus bietet die API Server-Health Informationen an.
Die Beschreibung der REST API lässt sich, im Fall einer Docker Installation, unter http://host.docker.internal:8085/aep-as4-address-service/swagger-ui/index.html oder unter http://localhost:8080/aep-as4-address-service/swagger-ui/index.html finden.
Ein KontextPath Präfix kann über folgende Property konfiguriert werden: server.servlet.contextPath.
Der Port lässt sich über folgende Property konfigurieren: server.port=8080.
Für produktive Systeme wird ein Loadbalancer benötigt, um die Anfragen auf mehrere Instanzen zu verteilen.
Konfiguration
Einfache Konfiguration der as4-address-service.properties
SQL Datenbank Anbindung
Der Einsatz des Microservice erfordert Zugriff auf eine SQL-Datenbank. Im Vorfeld muss ein Schema angelegt worden sein. Die Tabellen werden automatisch vom Microservice angelegt (via flyway).
Diese speziellen Datenbankparameter können je nach Bedarf verändert werden. Das Passwort wird als Environment Variable mit übergeben. Momentan werden die Datenbanksysteme MSSQL, Oracle und Postgresql unterstützt.
datasource.url=jdbc:postgresql://as4-database:5432/as4_address?currentSchema=as4_address
datasource.username=postgres
datasource.password=${DB_PASSWORD}
datasource.type=postgres
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true
Im Fall einer Oracle-DB kann sich an den nachfolgenden Parametern orientiert werden.
datasource.url=jdbc:oracle:thin:@//as4-database-oracle:1521/orclas4
datasource.username=as4_address
datasource.password=${DB_PASSWORD}
datasource.type=oracle
Message Broker Anbindung
Die Kommunikation zwischen den verschiedene AS4 Services erfolgt über einen Message-Broker.
rabbitmq.host=rabbitmq3
rabbitmq.port=5672
rabbitmq.username=guest
rabbitmq.password=guest
Routing Konfiguration der as4-address-service.properties
Falls Sie das Standard Routing nutzen, muss das Routing nicht weiter konfiguriert werden. Wenn Sie Ihr Routing anpassen möchten, lesen Sie die folgende Dokumentation.
Für die Aktivierung des Routings müssen der headerName und die headerValues gesetzt werden. Den headerName kann man sich als Filterkategorie vorstellen, während die headerValues den zu filternden Werten entsprechen. Nachrichten mit Werten, die nicht explizit als headerValues aufgelistet sind, laufen weiterhin über die default Route.
Als headerName werden folgende Parameter angeboten:
- tenant: ILN Nummer des Senders
- partner: ILN Nummer des Empfängers.
- sector: GAS, ELECTRICITY
Es können mehrere Werte kommasepariert angegeben werden.
pathswitchExchangeName=as4.outbound.request.pathswitch
pathswitchHeaderName=partner
pathswitchHeaderValues=
Wird der Producer für das Routing konfiguriert muss natürlich auch die Gegenstelle dafür eingerichtet werden. Dem Consumer wird über die Gruppe der Wert (Value) aus der HeaderValues Liste zugewiesen nach welchem gefiltert werden soll. Bitte den Default Wert nur ändern, wenn Routing verwendet werden soll.
pathswitchOutboundExchangeName=as4.outbound.pathswitch
pathswitchOutboundGroup=default
Externes Pathswitch-Ereignis AS4-Address-Service erstellt ein externes API-Pathswitch-Ereignis (AMQP), nachdem es ein internes AS4-Ereignis empfangen hat.
externalEventPathswitchExchangeName=as4.pathswitch.delivery
externalEventPathswitchHeaderName=tenant
externalEventPathswitchHeaderValues=
Eingehender Pathswitch
Die Queue as4.inbound.pathswitch enthält die Pathswitch Message vom AS4 Message Service basierend auf dem routing key der serviceId für pathswitch Nachrichten https://www.bdew.de/as4/communication/services/pathSwitch. Das Objekt enthält alle notwendigen Informationen über die Business Message und das Receipt.
pathswitchInboundExchangeName=as4.inbound
pathswitchInboundGroup=pathswitch
pathswitchInboundRoutingKey=https://www.bdew.de/as4/communication/services/pathSwitch
Wenn das Receipt positiv ist und erfoglreich zugestellt wurde, liest der Adress Service die Adresse aus der eingehenden Pathswitch-Nachricht aus und speichert sie in der Datenbank. Konnten die Informationen nicht in der Datenbank gespeichert werden, so werden sie in eine Error Queue geroutet. Bei Interesse kann die Error Queue nach Routing Keys gefultert werden, z. B. nach Partner oder Mandant
inboundErrorPathswitchExchangeName=as4.inbound.pathswitch.error
inboundErrorPathswitchHeaderName=partner
inboundErrorPathswitchHeaderValues=
Ausgehender Pathswitch
Die Queue as4.outbound.pathswitch.default ist die Bestätigung des Marktpartners, dass dieser die Adressänderung angenommen hat, und wird vom AS4 Receipt Server ausgelöst.
pathswitchOutboundExchangeName=as4.outbound.pathswitch
Die Queue as4.outbound.request.pathswitch.default startet die Bekanntmachung der eigenen Adressänderung.
pathswitchExchangeName=as4.outbound.request.pathswitch
Zeitzone
Es wird empfohlen, die Server-Zeitzone auf die gewünschte Zeitzone einzustellen. Alle Server müssen die gleiche Zeitzone nutzen. Die Server-Zeitzone darf nachträglich nicht mehr geändert werden.
Anhang: Gesamtkonfiguration
Folgende Konfiguration reicht in einem Standard-System aus:
application.properties:
#--------------------- DB Connection ------------------
datasource.url=jdbc:postgresql://as4-database:5432/as4_address?currentSchema=as4_address
datasource.username=postgres
datasource.password=${DB_PASSWORD}
datasource.type=postgres
#==== RabbitMQ
rabbitmq.host=rabbitmq3
rabbitmq.port=5672
rabbitmq.username=guest
rabbitmq.password=${RABBITMQ_PASSWORD}
Allgemeine Hinweise zur Konfiguration finden Sie hier.
View Me Edit Me