Processes

specdraftimplproposal

Beschreibungen von unterstützten Prozessen abrufen und diese ausführen.

Umfang

Processes ermöglicht die Beschreibung, den Abruf und die Ausführung von Prozessen.

Prozessbeschreibungen werden mithilfe der Anforderungsklasse OGC PROCESS DESCRIPTION definiert. Sie können global und pro API definiert werden.

Dieser Baustein unterstützt sowohl synchrone als auch asynchrone Ausführung von Prozessen. Über die Konfiguration kann die Unterstützung auf nur synchrone oder asynchrone Ausführung beschränkt oder beide Modi aktiviert werden.

Wichtig: Die asynchronen Operationen (/jobs/...) werden über den Hilfsbaustein Async zur Verfügung gestellt, der automatisch aktiviert wird. Lesen Sie dessen Dokumentation für weitere Informationen zu den asynchronen Operationen.

Es gelten einige Einschränkungen; siehe den Abschnitt Einschränkungen.

Limitierungen

Diese Implementierung deckt nicht alle Details ab und hat einige Einschränkungen:

• Alle Eingaben müssen direkt angegeben werden. Referenzen werden nicht unterstützt.
• Eingaben und Ausgaben können nicht mehrere Schemata haben.
• Von den JSON Schema Validation Formaten wird nur date-time unterstützt.
• Von den zusätzlichen OGC PROCESS DESCRIPTION Formaten wird nur ogc-bbox unterstützt.
• mediatype, encoding und schema werden bei der Ausgabeauswahl nicht berücksichtigt.
• Binärwerte werden nicht unterstützt.
• null wird als Eingabewert nicht unterstützt.
• Anforderung 50 ("0-th" result) wird nicht unterstützt.
• Eingabebeschreibungen unterstützen keine Data classes, Data access APIs oder Execution unit requirements.
• Ausgabebeschreibungen unterstützen keine Data classes oder Data access APIs.
• Das Verhalten des dismiss-Endpunkts weicht absichtlich vom Entwurf ab: Anstatt den Job zu entfernen, wenn sein Status successful, failed oder dismissed ist, wird nichts geändert.

Da diese API noch nicht gründlich getestet wurde, können weitere Einschränkungen und/oder unerwünschtes Verhalten auftreten.

Konformitätsklassen

Der Baustein basiert auf den Vorgaben der Konformitätsklassen "Core", "OGC Process Description", "JSON", "HTML", "OpenAPI Specification 3.0", "Callback" und "Dismiss" aus dem Entwurf von OGC API - Processes - Part 1: Core. Die Implementierung wird sich im Zuge der weiteren Standardisierung der Spezifikation noch ändern.

Operationen

Ressource	Pfad	Methoden	Formate	Beschreibung
Process List	processes	GET	HTML, JSON	Gibt eine Liste mit Zusammenfassungen einer Teilmenge aller von dieser API unterstützten Prozesse zurück. Unterstützt die Paginierung über Links (first, next, prev und last), um alle Teilmengen zu erkunden.
Process details	processes/{processId}	GET	HTML, JSON	Gibt die vollständigen Details eines Prozesses zurück.
Execute	processes/{processId}/execution	POST	Any, HTML, JSON	Löst die Ausführung eines Prozesses aus. Die Eingaben, die Ausgabeauswahl und mögliche Callback-Subscriber werden im Request-Body übermittelt. Wird der Prozess synchron ausgeführt, werden die Ergebnisse berechnet und direkt zurückgegeben, andernfalls werden die Statusinformationen des zugehörigen Jobs zurückgegeben.

Pfad-Parameter

Name	Ressourcen	Beschreibung
processId	processes/{processId}, processes/{processId}/execution	Der lokale Identifikator eines Prozesses, eindeutig innerhalb der API.

Query Parameter

Name	Ressourcen	Beschreibung
limit	processes	Die maximale Anzahl von Prozess-Zusammenfassungen, die im Antwortdokument zurückgegeben werden. Wenn mehr Prozess-Zusammenfassungen verfügbar sind, wird ein Link zur nächsten Seite mit der Antwort zurückgeliefert. Wird kein Wert für den Parameter angegeben, gilt der Standardwert, der für die API konfiguriert ist.
offset	processes	Der Index der ersten Prozesszusammenfassung im Gesamtergebnis, die in die Antwort aufgenommen wird. Dieser Parameter wird für das Paging verwendet.
f	processes/{processId}	Wählt das Ausgabeformat der Antwort. Wenn kein Wert angegeben wird, gelten die Standard-HTTP-Regeln, d.h. der "Accept"-Header wird zur Bestimmung des Formats verwendet.
f	processes	Wählt das Ausgabeformat der Antwort. Wenn kein Wert angegeben wird, gelten die Standard-HTTP-Regeln, d.h. der "Accept"-Header wird zur Bestimmung des Formats verwendet.
f	processes/{processId}/execution	Wählt das Ausgabeformat der Antwort. Wenn kein Wert angegeben wird, gelten die Standard-HTTP-Regeln, d.h. der "Accept"-Header wird zur Bestimmung des Formats verwendet.

Konfiguration

Optionen

Name	Default	Beschreibung	Typ	Seit
buildingBlock		Immer PROCESSES_CORE.	string	v2.0
async	false	Aktiviert die asynchrone Ausführung. Eine Anfrage mit Prefer: respond-async wird mit Status 202 angenommen und als Hintergrund-Job ausgeführt; Fortschritt und Ergebnis werden im Job festgehalten. Ist die Option inaktiv, werden Anfragen mit respond-async synchron ausgeführt.	boolean	v4.9
maxWait	60	Nur relevant, wenn async aktiviert ist. Obergrenze in Sekunden für die wait-Präferenz: Eine Anfrage mit Prefer: respond-async, wait=n wird als Hintergrund-Job ausgeführt, die Antwort aber bis zu min(n, maxWait) Sekunden zurückgehalten \u2014 ist der Job rechtzeitig fertig, wird die reguläre synchrone Antwort zurückgegeben und das gespeicherte Ergebnis gelöscht, andernfalls wird die Anfrage mit Status 202 beantwortet und der Job läuft weiter.	number	v4.9
jobTtl	1h	Nur relevant, wenn async aktiviert ist. Lebensdauer eines Jobs: Nachdem der Job abgeschlossen ist, werden dessen Status und Ergebnisse bis zu jobTtl aufbewahrt, danach werden sie gelöscht. Ein Job ist abgeschlossen, wenn er abgebrochen/verworfen, fehlgeschlagen oder erfolgreich abgeschlossen wurde. Dies ist eine weiche Grenze, die tatsächliche Löschung kann verzögert erfolgen.	string	v4.9
enabled	false	Soll der Baustein aktiviert werden?	boolean	4.9
defaultPageSize	10	Setzt den Defaultwert für den Parameter limit.	number	4.9
minimumPageSize	1	Setzt den Minimalwert für den Parameter limit.	number	4.9
maximumPageSize	10000	Setzt den Maximalwert für den Parameter limit.	number	4.9
callbackRetries	3	Gibt an, wie oft der Callback höchstens wiederholt werden soll, wenn der Subscriber nicht erreichbar ist oder mit einem Serverfehler (5xx), 408 oder 429 antwortet. Ein Client kann mit maxRetries im Subscriber der Ausführungsanfrage weniger Wiederholungen anfordern. Sollte auf 0 gesetzt werden, falls keine Wiederholungen erwünscht sind.	number	4.9
allowedCallbackUris	[]	Die URIs, an die die Callbacks einer asynchronen Ausführung gesendet werden dürfen. Eine Callback-URI eines Subscribers wird akzeptiert, wenn sie Schema, Host und Port eines Eintrags hat und ihr Pfad mit dem Pfad des Eintrags beginnt, z.B. akzeptiert https://example.com/callbacks/ die URI https://example.com/callbacks/job-done. Der Eintrag * akzeptiert jede HTTP(S)-URI; er sollte nur für Tests oder in einer abgeschlossenen Umgebung verwendet werden, da ein Client dann Anfragen des Servers an jeden Host richten kann, den der Server erreicht, auch an Dienste, die nur vom Server aus erreichbar sind. Ohne Eintrag werden Callbacks nicht unterstützt und eine asynchrone Ausführung mit einem Subscriber wird abgelehnt.	array	4.9
syncTimeout	5m	Maximale Dauer einer synchronen Prozessausführung. Ist der Prozess bis dahin nicht abgeschlossen, wird der Job abgebrochen und die Anfrage schlägt mit dem Statuscode 504 fehl.	string	4.9

Speicherung

Prozessbeschreibungen werden lokal als values im Store gespeichert. Globale Prozessbeschreibungen werden in values/processes abgelegt. API-spezifische Prozessbeschreibungen müssen in values/processes/{apiId} gespeichert werden, wobei {apiId} mit der Id der API ersetzt werden muss.

Zur Struktur von Prozessbeschreibungen und den Optionen des Jobs, der eine Ausführung durchführt, siehe Prozesse.

Beispiele

Beispielkonfiguration für eine API:

- buildingBlock: PROCESSES_CORE
   enabled: true
   defaultPageSize: 10
   minimumPageSize: 5
   maximumPageSize: 100
   callbackRetries: 2
   allowedCallbackUris:
     - https://example.com/callbacks/
   async: true
 

Beispiel für die Prozessbeschreibung eines einfachen Echo-Prozesses:

 id: "EchoProcess"
title: "Echo Process"
description: "This process simply echoes its input as an output."
version: "1.0.0"
jobControlOptions: [ SYNC_EXECUTE, ASYNC_EXECUTE ]
outputs:
 inputString:
   title: "Input String"
   description: "The echoed single string value."
   valuePassing: [ BY_VALUE ]
   schema:
     type: string
   maxOccurs: 1
   minOccurs: 0
inputs:
 inputString:
   title: "Input String"
   description: "A single string value to echo."
   valuePassing: [ BY_VALUE ]
   schema:
     type: string
   maxOccurs: 1
   minOccurs: 0
 

Wenn der Prozess global sein soll, muss die Beschreibung in values/processes gespeichert werden. Falls der Prozess für eine bestimmte API foo gelten soll, muss dieser in values/processes/foo liegen.

Weitere Informationen zur Beschreibung eines Prozesses finden Sie unter OGC PROCESS DESCRIPTION.