Important

La traduction est le fruit d’un effort communautaire auquel vous pouvez vous joindre. Cette page est actuellement traduite à 94.12%.

20. QGIS Server et Python

20.1. Introduction

Pour en savoir plus sur QGIS Server, lisez le Guide/manuel de QGIS Server.

QGIS Server, c’est trois choses différentes :

1. Bibliothèque QGIS Server : une bibliothèque qui fournit une API pour la création de services web OGC

2. QGIS Server FCGI : une application binaire FCGI qgis_mapserv.fcgi qui, avec un serveur web, implémente un ensemble de services OGC (WMS, WFS, WCS etc.) et d’API OGC (WFS3/OAPIF)

3. Developpement QGIS Server : une application binaire de serveur de développement qgis_mapserver qui implémente un ensemble de services OGC (WMS, WFS, WCS etc.) et des API OGC (WFS3/OAPIF)

Ce chapitre du livre de cuisine se concentre sur le premier sujet et, en expliquant l’utilisation de l’API QGIS Server, il montre comment il est possible d’utiliser Python pour étendre, améliorer ou personnaliser le comportement du serveur ou comment utiliser l’API QGIS Server pour intégrer QGIS Server dans une autre application.

Il existe plusieurs façons de modifier le comportement de QGIS Server ou d’étendre ses capacités pour offrir de nouveaux services ou API personnalisés, voici les principaux scénarios auxquels vous pouvez être confrontés :

• EMBEDDING → Utiliser l’API QGIS Server depuis une autre application Python

• STANDALONE → Exécuter QGIS Server comme un service WSGI/HTTP autonome

• FILTRES → Améliorer/personnaliser QGIS Server avec des plugins de filtrage

• SERVICES → Ajouter un nouveau SERVICE

• OGC APIs → Ajouter une nouvelle API OGC

Les applications intégrées ou autonomes nécessitent l’utilisation de l’API Python de QGIS Server directement à partir d’un autre script ou application Python. Les autres options sont mieux adaptées lorsque vous souhaitez ajouter des fonctionnalités personnalisées à une application binaire standard de QGIS Server (FCGI ou serveur de développement) : dans ce cas, vous devrez écrire un plugin Python pour l’application serveur et enregistrer vos filtres, services ou API personnalisés.

20.2. Principes de base de l’API du serveur

Les classes fondamentales impliquées dans une application typique de QGIS Server sont les suivantes :

• QgsServer l’instance du serveur (typiquement une seule instance pour toute la durée de vie de l’application)

• QgsServerRequest l’objet de la requête (généralement recréé sur chaque requête)

• QgsServer.handleRequest(request, response) traite la requête et remplit la réponse

Le flux de travail QGIS Server FCGI ou serveur de développement peut être résumé comme suit :

initialize the QgsApplication
create the QgsServer
the main server loop waits forever for client requests:
    for each incoming request:
        create a QgsServerRequest request
        create a QgsServerResponse response
        call QgsServer.handleRequest(request, response)
            filter plugins may be executed
        send the output to the client

Dans la méthode QgsServer.handleRequest(request, response) les callbacks des plugins de filtre sont appelés et QgsServerRequest et QgsServerResponse sont mis à la disposition des plugins par le biais de la QgsServerInterface.

Avertissement

Les classes QGIS Server ne sont pas sûres pour les threads, vous devez toujours utiliser un modèle de multitraitement ou des conteneurs lorsque vous construisez des applications évolutives basées sur l’API du serveur QGIS.

20.3. Autonome ou intégré

Pour les applications serveur autonomes ou integre, vous devrez utiliser directement les classes de serveur mentionnées ci-dessus, en les intégrant dans une implémentation de serveur web qui gère toutes les interactions du protocole HTTP avec le client.

Voici un exemple minimal d’utilisation de l’API QGIS Server (sans la partie HTTP) :

from qgis.core import QgsApplication
from qgis.server import *
app = QgsApplication([], False)

# Create the server instance, it may be a single one that
# is reused on multiple requests
server = QgsServer()

# Create the request by specifying the full URL and an optional body
# (for example for POST requests)
request = QgsBufferServerRequest(
    'http://localhost:8081/?MAP=/qgis-server/projects/helloworld.qgs' +
    '&SERVICE=WMS&REQUEST=GetCapabilities')

# Create a response objects
response = QgsBufferServerResponse()

# Handle the request
server.handleRequest(request, response)

print(response.headers())
print(response.body().data().decode('utf8'))

app.exitQgis()

Here is a complete standalone application example developed for the continuous integrations testing on QGIS source code repository, it showcases a wide set of different plugin filters and authentication schemes (not mean for production because they were developed for testing purposes only but still interesting for learning): qgis_wrapped_server.py

20.4. Plugins de serveur

Les plugins python du serveur sont chargés une fois lorsque l’application QGIS Server démarre et peuvent être utilisés pour enregistrer des filtres, des services ou des API.

La structure d’un plugin serveur est très similaire à son homologue de bureau, un objet QgsServerInterface est mis à la disposition des plugins et ceux-ci peuvent enregistrer un ou plusieurs filtres, services ou API personnalisés dans le registre correspondant en utilisant une des méthodes exposées par l’interface serveur.

20.4.1. Plugins pour filtres de serveur

Les filtres existent en trois possibilite différentes et peuvent être instanciés en sous-classant l’une des classes ci-dessous et en appelant la méthode correspondante de QgsServerInterface :

Type de filtre	Classe de base	Enregistrement de QgsServerInterface
I/O	QgsServerFilter	registerFilter()
Contrôle d’accès	QgsAccessControlFilter	registerAccessControl()
Cache	QgsServerCacheFilter	registerServerCache()

20.4.1.1. Filtres I/O

Les filtres I/O peuvent modifier l’entrée et la sortie du serveur (la demande et la réponse) des services de base (WMS, WFS, etc.), ce qui permet d’effectuer tout type de manipulation du flux de travail des services. Il est possible, par exemple, de restreindre l’accès à des couches sélectionnées, d’injecter une feuille de style XSL dans la réponse XML, d’ajouter un filigrane à une image WMS générée, etc.

A partir de là, il vous sera peut-être utile de jeter un coup d’oeil rapide à l’API des plugins server.

Chaque filtre doit mettre en œuvre au moins un des trois rappels :

• onRequestReady()

• onResponseComplete()

• onSendResponse()

Tous les filtres ont accès à l’objet requête/réponse (QgsRequestHandler) et peuvent manipuler toutes ses propriétés (entrée/sortie) et lever des exceptions (mais d’une manière assez particulière comme nous le verrons plus loin).

All these methods return a boolean value indicating if the call should be propagated to the subsequent filters. If one of these method returns False then the chain stop, otherwise the call will propagate to the next filter.

Voici le pseudo-code montrant comment le serveur traite une requête typique et quand les rappels du filtre sont appelés :

for each incoming request:
    create GET/POST request handler
    pass request to an instance of QgsServerInterface
    call onRequestReady filters

    if there is not a response:
        if SERVICE is WMS/WFS/WCS:
            create WMS/WFS/WCS service
            call service’s executeRequest
                possibly call onSendResponse for each chunk of bytes
                sent to the client by a streaming services (WFS)
        call onResponseComplete
    request handler sends the response to the client

Les paragraphes qui suivent décrivent les fonctions de rappel disponibles en détails.

20.4.1.1.1. onRequestReady

Cette fonction est appelée lorsque la requête est prêt: l’URL entrante et ses données ont été analysées et juste avant de passer la main aux services principaux (WMS, WFS, etc.), c’est le point où vous pouvez manipuler l’entrée et dérouler des actions telles que:

• l’authentification/l’autorisation

• les redirections

• l’ajout/suppression de certains paramètres (les noms de type par exemple)

• le déclenchement d’exceptions

Vous pouvez également substituer l’intégralité d’un service principal en modifiant le paramètre SERVICE et complètement outrepasser le service (ce qui n’a pas beaucoup d’intérêt).

20.4.1.1.2. onSendResponse

This is called whenever any partial output is flushed from response buffer (i.e to FCGI stdout if the fcgi server is used) and from there, to the client. This occurs when huge content is streamed (like WFS GetFeature). In this case onSendResponse() may be called multiple times.

Note that if the response is not streamed, then onSendResponse() will not be called at all.

In all case, the last (or unique) chunk will be sent to client after a call to onResponseComplete().

Returning False will prevent flushing of data to the client. This is desirable when a plugin wants to collect all chunks from a response and examine or change the response in onResponseComplete().

20.4.1.1.3. onResponseComplete

This is called once when core services (if hit) finish their process and the request is ready to be sent to the client. As discussed above, this method will be called before the last (or unique) chunk of data is sent to the client. For streaming services, multiple calls to onSendResponse() might have been called.

onResponseComplete() est l’endroit idéal pour fournir l’implémentation de nouveaux services (WPS ou services personnalisés) et pour effectuer une manipulation directe de la sortie provenant des services de base (par exemple pour ajouter un filigrane sur une image WMS).

Note that returning False will prevent the next plugins to execute onResponseComplete() but, in any case, prevent response to be sent to the client.

20.4.1.1.4. Lever les exceptions d’un plugin

Un certain travail reste à faire sur ce sujet : l’implémentation actuelle peut distinguer les exceptions gérées et non gérées en définissant une propriété QgsRequestHandler à une instance de QgsMapServiceException, de cette façon le code C++ principal peut attraper les exceptions python gérées et ignorer les exceptions non gérées (ou mieux : les enregistrer).

Cette approche fonctionne globalement mais elle n’est pas très « pythonesque »: une meilleure approche consisterait à déclencher des exceptions depuis le code Python et les faire remonter dans la boucle principale C++ pour y être traitées.

20.4.1.1.5. Écriture d’une extension serveur

Un plugin serveur est un plugin Python QGIS standard tel que décrit dans Développer des extensions Python, qui fournit juste une interface supplémentaire (ou alternative) : un plugin de bureau QGIS typique a accès à l’application QGIS par le biais de la QgisInterface, un plugin serveur a seulement accès à une QgsServerInterface lorsqu’il est exécuté dans le contexte de l’application QGIS Server.

Pour que QGIS Server sache qu’un plugin a une interface serveur, une entrée spéciale de métadonnées est nécessaire (dans metadata.txt) :

server=True

Important

Seuls les plugins qui ont le jeu de métadonnées server=True seront chargés et exécutés par QGIS Server.

The qgis3-server-vagrant example plugin discussed here (with many more) is available on github, a few server plugins are also published in the official QGIS plugins repository.

20.4.1.1.5.1. Fichiers de l’extension

Vous pouvez voir ici la structure du répertoire de notre exemple d’extension pour serveur.

PYTHON_PLUGINS_PATH/
  HelloServer/
    __init__.py    --> *required*
    HelloServer.py  --> *required*
    metadata.txt   --> *required*

20.4.1.1.5.1.1. __init__.py

Ce fichier est requis par le système d’importation de Python. De plus, QGIS Server exige que ce fichier contienne une fonction serverClassFactory(), qui est appelée lorsque le plugin est chargé dans QGIS Server au démarrage du serveur. Elle reçoit une référence à l’instance de QgsServerInterface et doit retourner une instance de la classe de votre plugin. Voici à quoi ressemble le plugin d’exemple __init__.py :

def serverClassFactory(serverIface):
    from .HelloServer import HelloServerServer
    return HelloServerServer(serverIface)

20.4.1.1.5.1.2. HelloServer.py

C’est l’endroit où tout se passe et voici à quoi il devrait ressembler : (ex. HelloServer.py)

Un plugin serveur consiste généralement en un ou plusieurs callbacks regroupés dans les instances d’un QgsServerFilter.

Chaque QgsServerFilter implémente un ou plusieurs des callbacks suivants :

• onRequestReady()

• onResponseComplete()

• onSendResponse()

L’exemple qui suit implémente un filtre minimaliste qui affiche HelloServer! pour le cas où le paramètre SERVICE vaut “HELLO” :

class HelloFilter(QgsServerFilter):

    def __init__(self, serverIface):
        super().__init__(serverIface)

    def onRequestReady(self) -> bool:
        QgsMessageLog.logMessage("HelloFilter.onRequestReady")
        return True

    def onSendResponse(self) -> bool:
        QgsMessageLog.logMessage("HelloFilter.onSendResponse")
        return True

    def onResponseComplete(self) -> bool:
        QgsMessageLog.logMessage("HelloFilter.onResponseComplete")
        request = self.serverInterface().requestHandler()
        params = request.parameterMap()
        if params.get('SERVICE', '').upper() == 'HELLO':
            request.clear()
            request.setResponseHeader('Content-type', 'text/plain')
            # Note that the content is of type "bytes"
            request.appendBody(b'HelloServer!')
        return True

Les filtres doivent être enregistrés dans la serverIface comme dans l’exemple suivant :

class HelloServerServer:
    def __init__(self, serverIface):
        serverIface.registerFilter(HelloFilter(serverIface), 100)

Le second paramètre de registerFilter() fixe une priorité qui définit l’ordre des rappels ayant le même nom (la priorité la plus basse est invoquée en premier).

En utilisant les trois rappels, les plugins peuvent manipuler l’entrée et/ou la sortie du serveur de nombreuses manières différentes. À chaque instant, l’instance du plugin a accès à la QgsRequestHandler par le biais de la QgsServerInterface. La classe QgsRequestHandler a de nombreuses méthodes qui peuvent être utilisées pour modifier les paramètres d’entrée avant d’entrer dans le traitement de base du serveur (en utilisant requestReady()) ou après que la requête ait été traitée par les services de base (en utilisant sendResponse()).

Les exemples suivants montrent quelques cas d’utilisation courants :

20.4.1.1.5.2. Modifier la couche en entrée

L’exemple de plugin contient un exemple de test qui modifie les paramètres d’entrée provenant de la chaîne de requête, dans cet exemple un nouveau paramètre est injecté dans le « parameterMap » (déjà analysé), ce paramètre est ensuite visible par les services centraux (WMS etc.), à la fin du traitement des services centraux nous vérifions que le paramètre est toujours là :

class ParamsFilter(QgsServerFilter):

    def __init__(self, serverIface):
        super(ParamsFilter, self).__init__(serverIface)

    def onRequestReady(self) -> bool:
        request = self.serverInterface().requestHandler()
        params = request.parameterMap( )
        request.setParameter('TEST_NEW_PARAM', 'ParamsFilter')
        return True

    def onResponseComplete(self) -> bool:
        request = self.serverInterface().requestHandler()
        params = request.parameterMap( )
        if params.get('TEST_NEW_PARAM') == 'ParamsFilter':
            QgsMessageLog.logMessage("SUCCESS - ParamsFilter.onResponseComplete")
        else:
            QgsMessageLog.logMessage("FAIL    - ParamsFilter.onResponseComplete")
        return True

Ceci est un extrait de ce que vous pouvez voir dans le fichier log:

src/core/qgsmessagelog.cpp: 45: (logMessage) [0ms] 2014-12-12T12:39:29 plugin[0] HelloServerServer - loading filter ParamsFilter
src/core/qgsmessagelog.cpp: 45: (logMessage) [1ms] 2014-12-12T12:39:29 Server[0] Server plugin HelloServer loaded!
src/core/qgsmessagelog.cpp: 45: (logMessage) [0ms] 2014-12-12T12:39:29 Server[0] Server python plugins loaded
src/mapserver/qgshttprequesthandler.cpp: 547: (requestStringToParameterMap) [1ms] inserting pair SERVICE // HELLO into the parameter map
src/mapserver/qgsserverfilter.cpp: 42: (onRequestReady) [0ms] QgsServerFilter plugin default onRequestReady called
src/core/qgsmessagelog.cpp: 45: (logMessage) [0ms] 2014-12-12T12:39:29 plugin[0] SUCCESS - ParamsFilter.onResponseComplete

Sur la ligne en surbrillance, la chaîne « SUCCESS » indique que le plugin a réussi le test.

La même technique peut être employée pour utiliser un service personnalisé à la place d’un service principal : vous pouvez par exemple sauter une requête WFS SERVICE ou n’importe quelle requête principale en modifiant le paramètre SERVICE par quelque-chose de différent et le service principal ne serait alors pas lancé. Vous pourrez ensuite injecter vos résultats personnalisés dans la sortie et les renvoyer au client (ceci est expliqué ci-dessous).

Astuce

Si vous voulez vraiment implémenter un service personnalisé, il est recommandé de sous-classer QgsService et d’enregistrer votre service sur registerFilter() en appelant son registerService(service)

20.4.1.1.5.3. Modifier ou remplacer la couche en sortie

L’exemple du filtre de filigrane montre comment remplacer la sortie WMS avec une nouvelle image obtenue par l’ajout d’un filigrane plaqué sur l’image WMS générée par le service principal WMS:

from qgis.server import *
from qgis.PyQt.QtCore import *
from qgis.PyQt.QtGui import *

class WatermarkFilter(QgsServerFilter):

    def __init__(self, serverIface):
        super().__init__(serverIface)

    def onResponseComplete(self) -> bool:
        request = self.serverInterface().requestHandler()
        params = request.parameterMap( )
        # Do some checks
        if (params.get('SERVICE').upper() == 'WMS' \
                and params.get('REQUEST').upper() == 'GETMAP' \
                and not request.exceptionRaised() ):
            QgsMessageLog.logMessage("WatermarkFilter.onResponseComplete: image ready %s" % request.parameter("FORMAT"))
            # Get the image
            img = QImage()
            img.loadFromData(request.body())
            # Adds the watermark
            watermark = QImage(os.path.join(os.path.dirname(__file__), 'media/watermark.png'))
            p = QPainter(img)
            p.drawImage(QRect( 20, 20, 40, 40), watermark)
            p.end()
            ba = QByteArray()
            buffer = QBuffer(ba)
            buffer.open(QIODevice.WriteOnly)
            img.save(buffer, "PNG" if "png" in request.parameter("FORMAT") else "JPG")
            # Set the body
            request.clearBody()
            request.appendBody(ba)
        return True

Dans cet exemple, la valeur du paramètre SERVICE est vérifiée et si la demande entrante est un WMS GETMAP et qu’aucune exception n’a été définie par un plugin exécuté précédemment ou par le service central (WMS dans ce cas), l’image générée par le WMS est récupérée dans le tampon de sortie et l’image en filigrane est ajoutée. L’étape finale consiste à effacer le tampon de sortie et à le remplacer par l’image nouvellement générée. Veuillez noter que dans une situation réelle, nous devons également vérifier le type d’image demandé au lieu de supporter uniquement les PNG ou JPG.

20.4.1.2. Filtres de contrôle d’accès

Les filtres de contrôle d’accès donnent au développeur un contrôle fin sur les couches, les entités et les attributs auxquels il peut accéder, les rappels suivants peuvent être mis en œuvre dans un filtre de contrôle d’accès :

• layerFilterExpression(layer)

• layerFilterSubsetString(layer)

• layerPermissions(layer)

• authorizedLayerAttributes(layer, attributes)

• allowToEdit(layer, feature)

• cacheKey()

20.4.1.2.1. Fichiers de l’extension

Voici la structure des répertoires de notre exemple de plugin :

PYTHON_PLUGINS_PATH/
  MyAccessControl/
    __init__.py    --> *required*
    AccessControl.py  --> *required*
    metadata.txt   --> *required*

20.4.1.2.1.1. __init__.py

Ce fichier est requis par le système d’importation de Python. Comme pour tous les plugins QGIS Server , ce fichier contient une fonction serverClassFactory(), qui est appelée lorsque le plugin est chargé dans QGIS Server au démarrage. Elle reçoit une référence à une instance de QgsServerInterface et doit retourner une instance de la classe de votre plugin. Voici à quoi ressemble le plugin d’exemple __init__.py :

def serverClassFactory(serverIface):
    from MyAccessControl.AccessControl import AccessControlServer
    return AccessControlServer(serverIface)

20.4.1.2.1.2. AccessControl.py

class AccessControlFilter(QgsAccessControlFilter):

    def __init__(self, server_iface):
        super().__init__(server_iface)

    def layerFilterExpression(self, layer):
        """ Return an additional expression filter """
        return super().layerFilterExpression(layer)

    def layerFilterSubsetString(self, layer):
        """ Return an additional subset string (typically SQL) filter """
        return super().layerFilterSubsetString(layer)

    def layerPermissions(self, layer):
        """ Return the layer rights """
        return super().layerPermissions(layer)

    def authorizedLayerAttributes(self, layer, attributes):
        """ Return the authorised layer attributes """
        return super().authorizedLayerAttributes(layer, attributes)

    def allowToEdit(self, layer, feature):
        """ Are we authorised to modify the following geometry """
        return super().allowToEdit(layer, feature)

    def cacheKey(self):
        return super().cacheKey()

class AccessControlServer:

   def __init__(self, serverIface):
      """ Register AccessControlFilter """
      serverIface.registerAccessControl(AccessControlFilter(serverIface), 100)

Cet exemple donne un accès total à tout le monde.

C’est le rôle de l’extension de connaître qui est connecté dessus.

Pour toutes ces méthodes nous avons la couche passée en argument afin de personnaliser la restriction par couche.

20.4.1.2.2. layerFilterExpression

Utilisé pour ajouter une expression pour limiter les résultats.

Pour limiter aux entités dont l’attribut role vaut user.

def layerFilterExpression(self, layer):
    return "$role = 'user'"

20.4.1.2.3. layerFilterSubsetString

Comme le point précédent mais utilise SubsetString (exécuté au niveau de la base de données).

Pour limiter aux entités dont l’attribut role vaut user.

def layerFilterSubsetString(self, layer):
    return "role = 'user'"

20.4.1.2.4. layerPermissions

Limiter l’accès à la couche.

Retourne un objet de type LayerPermissions(), qui a les propriétés :

• canRead voir dans le GetCapabilities et acces lecture seule.

• canInsert pour pouvoir insérer une nouvelle entité .

• canUpdate pour pouvoir mettre à jour une entité.

• canDelete pour pouvoir supprimer une entité.

Par exemple, pour tout limiter à un accès en lecture seule.

def layerPermissions(self, layer):
    rights = QgsAccessControlFilter.LayerPermissions()
    rights.canRead = True
    rights.canInsert = rights.canUpdate = rights.canDelete = False
    return rights

20.4.1.2.5. authorizedLayerAttributes

Utilisé pour limiter la visibilité d’un sous-groupe d’attribut spécifique.

L’argument attributes renvoie la liste des attributs réellement visibles.

Par exemple, pour cacher l’attribut role :

def authorizedLayerAttributes(self, layer, attributes):
    return [a for a in attributes if a != "role"]

20.4.1.2.6. allowToEdit

Il permet de limiter l’édition à un sous-ensemble d’entités.

Il est utilisé dans le protocole WFS-Transaction.

Par exemple, pour limiter l’édition aux entités dont l’attribut role contient la valeur user :

def allowToEdit(self, layer, feature):
    return feature.attribute('role') == 'user'

20.4.1.2.7. cacheKey

QGIS Server conserve un cache des capabilités donc pour avoir un cache par rôle vous pouvez retourner le rôle dans cette méthode. Ou retourner None pour complètement désactiver le cache.

20.4.2. Services personnalisés

Dans QGIS Server, les services de base tels que WMS, WFS et WCS sont implémentés en tant que sous-classes de QgsService.

Pour implémenter un nouveau service qui sera exécuté lorsque le paramètre de la chaîne de requête SERVICE correspondra au nom du service, vous pouvez implémenter votre propre QgsService et enregistrer votre service sur le serviceRegistry() en appelant son registerService(service).

Voici un exemple d’un service personnalisé appelé CUSTOM :

from qgis.server import QgsService
from qgis.core import QgsMessageLog

class CustomServiceService(QgsService):

    def __init__(self):
        QgsService.__init__(self)

    def name(self):
        return "CUSTOM"

    def version(self):
        return "1.0.0"

    def executeRequest(self, request, response, project):
        response.setStatusCode(200)
        QgsMessageLog.logMessage('Custom service executeRequest')
        response.write("Custom service executeRequest")


class CustomService():

    def __init__(self, serverIface):
        serverIface.serviceRegistry().registerService(CustomServiceService())

20.4.3. API personnalisées

Dans QGIS Server, les API OGC de base telles que OAPIF (alias WFS3) sont implémentées sous forme de collections de QgsServerOgcApiHandler sous-classes qui sont enregistrées dans une instance de QgsServerOgcApi (ou sa classe parente QgsServerApi).

Pour implémenter une nouvelle API qui sera exécutée lorsque le chemin de l’URL correspondra à une certaine URL, vous pouvez implémenter vos propres instances QgsServerOgcApiHandler, les ajouter à une instance QgsServerOgcApi et enregistrer l’API sur le serviceRegistry() en appelant son registerApi(api).

Voici un exemple d’API personnalisée qui sera exécutée lorsque l’URL contient « /customapi » :

import json
import os

from qgis.PyQt.QtCore import QBuffer, QIODevice, QTextStream, QRegularExpression
from qgis.server import (
    QgsServiceRegistry,
    QgsService,
    QgsServerFilter,
    QgsServerOgcApi,
    QgsServerQueryStringParameter,
    QgsServerOgcApiHandler,
)

from qgis.core import (
    QgsMessageLog,
    QgsJsonExporter,
    QgsCircle,
    QgsFeature,
    QgsPoint,
    QgsGeometry,
)


class CustomApiHandler(QgsServerOgcApiHandler):

    def __init__(self):
        super(CustomApiHandler, self).__init__()
        self.setContentTypes([QgsServerOgcApi.HTML, QgsServerOgcApi.JSON])

    def path(self):
        return QRegularExpression("/customapi")

    def operationId(self):
        return "CustomApiXYCircle"

    def summary(self):
        return "Creates a circle around a point"

    def description(self):
        return "Creates a circle around a point"

    def linkTitle(self):
        return "Custom Api XY Circle"

    def linkType(self):
        return QgsServerOgcApi.data

    def handleRequest(self, context):
        """Simple Circle"""

        values = self.values(context)
        x = values['x']
        y = values['y']
        r = values['r']
        f = QgsFeature()
        f.setAttributes([x, y, r])
        f.setGeometry(QgsCircle(QgsPoint(x, y), r).toCircularString())
        exporter = QgsJsonExporter()
        self.write(json.loads(exporter.exportFeature(f)), context)

    def templatePath(self, context):
        # The template path is used to serve HTML content
        return os.path.join(os.path.dirname(__file__), 'circle.html')

    def parameters(self, context):
        return [QgsServerQueryStringParameter('x', True, QgsServerQueryStringParameter.Type.Double, 'X coordinate'),
                QgsServerQueryStringParameter(
                    'y', True, QgsServerQueryStringParameter.Type.Double, 'Y coordinate'),
                QgsServerQueryStringParameter('r', True, QgsServerQueryStringParameter.Type.Double, 'radius')]


class CustomApi():

    def __init__(self, serverIface):
        api = QgsServerOgcApi(serverIface, '/customapi',
                            'custom api', 'a custom api', '1.1')
        handler = CustomApiHandler()
        api.registerHandler(handler)
        serverIface.serviceRegistry().registerApi(api)