Bernhard Mallinger
94ae782b6c
* Exclude None from `get_processor` return type annotation An exception is raised in case of error, so it can't ever return None * Add support for OGC API Processes Subscriber The subscription URLs are passed to the manager, which then has to call them appropriately. By default, managers have the attribute `supports_subscribing` set to `False` in order to not break the API for these. The subscriptions are only passed to if this is set to `True` * Add ogc api callback class to conformance https://docs.ogc.org/is/18-062r2/18-062r2.html#toc67 * Make successUri mandatory in subscriber It's mandatory in the standard. Thx @ricardogsilva ! * Use snake case in python for fields which are camel case in the api Thx @ricardogsilva ! * Add subscriber to method docstring * Provide default value for subscriber for managers not supporting it Thanks @ricardogsilva ! * Factor out notification call into methods This increases reusability by other managers Thanks @ricardogsilva ! * Add an example call for a process subscriber * Change test urls to valid urls * Third party imports in own block
121 lines
4.4 KiB
ReStructuredText
121 lines
4.4 KiB
ReStructuredText
.. _ogcapi-processes:
|
|
|
|
Publishing processes via OGC API - Processes
|
|
============================================
|
|
|
|
`OGC API - Processes`_ provides geospatial data processing functionality in a standards-based
|
|
fashion (inputs, outputs).
|
|
|
|
pygeoapi implements OGC API - Processes functionality by providing a plugin architecture, thereby
|
|
allowing developers to implement custom processing workflows in Python.
|
|
|
|
A `sample`_ ``hello-world`` process is provided with the pygeoapi default configuration.
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
processes:
|
|
hello-world:
|
|
processor:
|
|
name: HelloWorld
|
|
|
|
Asynchronous support
|
|
--------------------
|
|
|
|
By default, pygeoapi implements process execution (jobs) as synchronous mode. That is, when
|
|
jobs are submitted, the process is executed and returned in real-time. Certain processes
|
|
that may take time to execute, or be delegated to a scheduler/queue, are better suited to
|
|
an asynchronous design pattern. This means that when a job is submitted in asynchronous
|
|
mode, the server responds immediately with a reference to the job, which allows the client
|
|
to periodically poll the server for the processing status of a given job.
|
|
|
|
pygeoapi provides asynchronous support by providing a 'manager' concept which, well,
|
|
manages job execution. The manager concept is implemented as part of the pygeoapi
|
|
:ref:`plugins` architecture. pygeoapi provides a default manager implementation
|
|
based on `TinyDB`_ for simplicity. Custom manager plugins can be developed for more
|
|
advanced job management capabilities (e.g. Kubernetes, databases, etc.).
|
|
|
|
In keeping with the OGC API - Processes specification, asynchronous process execution
|
|
can be requested by including the ``Prefer: respond-async`` HTTP header in the request
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
server:
|
|
manager:
|
|
name: TinyDB
|
|
connection: /tmp/pygeoapi-process-manager.db
|
|
output_dir: /tmp/
|
|
|
|
MongoDB
|
|
--------------------
|
|
As an alternative to the default a manager employing `MongoDB`_ can be used.
|
|
The connection to an installed `MongoDB`_ instance must be provided in the configuration.
|
|
`MongoDB`_ uses the localhost and port 27017 by default. Jobs are stored in a collection named
|
|
job_manager_pygeoapi.
|
|
|
|
.. code-block:: yaml
|
|
|
|
server:
|
|
manager:
|
|
name: MongoDB
|
|
connection: mongodb://host:port
|
|
output_dir: /tmp/
|
|
|
|
|
|
Putting it all together
|
|
-----------------------
|
|
|
|
To summarize how pygeoapi processes and managers work together::
|
|
|
|
* process plugins implement the core processing / workflow functionality
|
|
* manager plugins control and manage how processes are executed
|
|
|
|
Processing examples
|
|
-------------------
|
|
|
|
.. code-block:: sh
|
|
|
|
# list all processes
|
|
curl http://localhost:5000/processes
|
|
|
|
# describe the ``hello-world`` process
|
|
curl http://localhost:5000/processes/hello-world
|
|
|
|
# show all jobs
|
|
curl http://localhost:5000/jobs
|
|
|
|
# execute a job for the ``hello-world`` process
|
|
curl -X POST http://localhost:5000/processes/hello-world/execution \
|
|
-H "Content-Type: application/json" \
|
|
-d "{\"inputs\":{\"name\": \"hi there2\"}}"
|
|
|
|
# execute a job for the ``hello-world`` process with a raw response (default)
|
|
curl -X POST http://localhost:5000/processes/hello-world/execution \
|
|
-H "Content-Type: application/json" \
|
|
-d "{\"inputs\":{\"name\": \"hi there2\"}}"
|
|
|
|
# execute a job for the ``hello-world`` process with a response document
|
|
curl -X POST http://localhost:5000/processes/hello-world/execution \
|
|
-H "Content-Type: application/json" \
|
|
-d "{\"inputs\":{\"name\": \"hi there2\"},\"response\":\"document\"}"
|
|
|
|
# execute a job for the ``hello-world`` process in asynchronous mode
|
|
curl -X POST http://localhost:5000/processes/hello-world/execution \
|
|
-H "Content-Type: application/json" \
|
|
-H "Prefer: respond-async"
|
|
-d "{\"inputs\":{\"name\": \"hi there2\"}}"
|
|
|
|
# execute a job for the ``hello-world`` process with a success subscriber
|
|
curl -X POST http://localhost:5000/processes/hello-world/execution \
|
|
-H "Content-Type: application/json" \
|
|
-d "{\"inputs\":{\"name\": \"hi there2\"}, \
|
|
\"subscriber\": {\"successUri\": \"https://www.example.com/success\"}}"
|
|
|
|
|
|
.. _`OGC API - Processes`: https://ogcapi.ogc.org/processes
|
|
.. _`sample`: https://github.com/geopython/pygeoapi/blob/master/pygeoapi/process/hello_world.py
|
|
.. _`TinyDB`: https://tinydb.readthedocs.io/en/latest
|