L'AMBSS fournit un ensemble de services Web REST permettant de gérer des souscripteurs Adélia via les quatre opérations de base CRUD : Create, Read, Update, Delete.
Ces services se divisent en deux groupes :
Les services pour gérer les objets configurations : c'est le pendant de la section configurations du fichier de configuration subscribersConf.yml,
les services pour gérer les objets souscripteurs : c'est le pendant de la section subscribers du fichier de configuration subscribersConf.yml.
Il est possible d'accéder à la documentation Swagger via l'URL :
L'ensemble de ces services Web manipulent des données au format JSON.
Remarque :
Par défaut, ces services gèrent des configurations et des souscripteurs stockés en mémoire. La propriété "ambss.subscribers.writer" permet d'activer la sauvegarde des créations et modifications des souscripteurs par les services web REST dans le fichier de configuration des souscripteurs Adélia (la valeur par défaut est "false"). Si aucun fichier de configuration des souscripteurs n'est spécifié au lancement de l'AMBSS alors un fichier subscribersConf.yml est créé dans le répertoire racine de l'AMBSS (le répertoire parent du sous-répertoire config ou se trouve le fichier application-dev.yml).
Services REST configurations
Ils sont accessibles via l'URL :
http://<hostname>:<port_number>/ambss/v1/configurations , où "hostname" est le nom de la machine hébergeant l'application Sprint Boot AMBSS, "port_number" est le numéro de port TCP d'écoute configuré pour l'AMBSS (dans le fichier application.yml ou application-dev.yml).
write : Entier (0 ou 1). Permet pour cette requête d'outrepasser la valeur de la propriété 'ambss.subscribers.writer' et d'imposer la sauvegarde ou la non sauvegarde de la configuration créée (valeur 0 pour ne pas sauvegarder ; 1 pour sauvegarder).
Corps de la requête
Message au format JSON décrivant la configuration à ajouter. En se basant sur cet exemple, cela donne :
USER (propriété 'ambss.security.role-names.user-role') et ADMIN (propriété 'ambss.security.role-names.admin-role')
Code de la réponse
200 (OK) : L'opération a réussi.
404 (Not Found) : La configuration d'identifiant <id_config> n'existe pas.
500 (Internal server error) : Une erreur interne s'est produite.
Corps de la réponse
En cas de succès (code 200), configuration d'identifiant <id_config> au format JSON ; objet JSON détaillant l'erreur sinon
Liste des configurations
Cette méthode permet de récupérer l'ensemble des configurations créées, en appliquant optionnellement des filtres de recherche.
Méthode HTTP
GET
URL
http://<port_number>/ambss/v1/configurations
Rôles
USER (propriété 'ambss.security.role-names.user-role') et ADMIN (propriété 'ambss.security.role-names.admin-role')
Paramètres dans l'URL
id : Pattern (expression régulière) d'identifiant de configuration,
adeliaPoolName : Pattern (expression régulière) de nom de pool de connections Adélia,
factory.id : Pattern (expression régulière) d'identifiant de fabrique contenue dans la configuration,
adeliaPgm.objectFileName : Pattern (expression régulière) du nom de fichier objet issu de la génération L3G du programme EADELIA contenu dans la configuration,
adeliaPgm.javaPackage : Pattern (expression régulière) du nom du package Java défini pour la génération L3G du programme EADELIA associé contenu dans la configuration,
adeliaPgm.customObjectMapper : Pattern (expression régulière) de l'identifiant du Java Bean définit dans le fichier beans-context.xml permettant de configurer les propriétés de transformation d'objet JSON en instance de classe Adélia contenu dans la configuration.
404 (Not Found) : La configuration d'identifiant <id_config> n'existe pas.
500 (Internal server error) : Une erreur interne s'est produite.
Corps de la réponse
En cas de succès (code 200), liste au format JSON des configurations satisfaisant les critères des filtres appliqués ; objet JSON détaillant l'erreur sinon.
Liste des souscripteurs associés à une configuration
USER (propriété 'ambss.security.role-names.user-role') et ADMIN (propriété 'ambss.security.role-names.admin-role')
Code de la réponse
200 (OK) : L'opération a réussi.
404 (Not Found) : La configuration d'identifiant <id_config> n'existe pas.
500 (Internal server error) : Une erreur interne s'est produite.
Corps de la réponse
En cas de succès (code 200), liste au format JSON des souscripteurs ayant dans leur description une référence à la configuration d'identifiant <id_config> ; objet JSON détaillant l'erreur sinon.
Remarque : Chaque souscripteur retourné l'est dans la version non déduite (c'est-à-dire sans remplacer toutes les références utilisées par les objets référencés).
write : Entier (0 ou 1). Permet pour cette requête d'outrepasser la valeur de la propriété 'ambss.subscribers.writer' et d'imposer la sauvegarde ou la non sauvegarde de la configuration créée (valeur 0 pour ne pas sauvegarder ; 1 pour sauvegarder).
Code de la réponse
204 (No Content) : L'opération a réussi.
400 (Bad Request) : La syntaxe de la configuration au format JSON est incorrecte ou la syntaxe déduite du souscripteur qui référence cette configuration est non valide (en appliquant la nouvelle configuration).
404 (Not Found) : La configuration d'identifiant <id_config> n'existe pas.
405 (Method Not Allowed) : La configuration d'identifiant <id_config> n'a pas pu être mise à jour car elle est référencée par au moins un souscripteur à l'état "démarré".
500 (Internal server error) : Une erreur interne s'est produite.
Corps de la réponse
Aucune réponse en cas de succès (code 204) ; objet JSON détaillant l'erreur sinon.
write : Entier (0 ou 1). Permet pour cette requête d'outrepasser la valeur de la propriété 'ambss.subscribers.writer' et d'imposer la sauvegarde ou la non sauvegarde de la configuration créée (valeur 0 pour ne pas sauvegarder ; 1 pour sauvegarder).
Code de la réponse
204 (No Content) : L'opération a réussi.
404 (Not Found) : La configuration d'identifiant <id_config> n'existe pas.
405 (Method Not Allowed) : La configuration d'identifiant <id_config> n'a pas pu être supprimée car elle est référencée par au moins un souscripteur.
500 (Internal server error) : Une erreur interne s'est produite.
Corps de la réponse
Aucune réponse en cas de succès (code 204) ; objet JSON détaillant l'erreur sinon.
http://<hostname>:<port_number>/ambss/v1/subscribers , où "hostname" est le nom de la machine hébergeant l'application Sprint Boot AMBSS, "port_number" est le numéro de port TCP d'écoute configuré pour l'AMBSS (dans fichier application.yml ou application-dev.yml).
write : Entier (0 ou 1). Permet pour cette requête d'outrepasser la valeur de la propriété 'ambss.subscribers.writer' et d'imposer la sauvegarde ou la non sauvegarde de la configuration créée (valeur 0 pour ne pas sauvegarder ; 1 pour sauvegarder).
Corps de la requête
Message au format JSON décrivant le souscripteur à ajouter. En se basant sur cet exemple cela donne :
La description au format JSON du souscripteur peut être avec ou sans référence à une ou plusieurs configurations. La création est autorisée seulement si la description déduite (c'est-à-dire en remplaçant toutes les références utilisées par les objets référencés) est complète et valide.
L'attribut "id" n'est pas obligatoire. S'il n'est pas renseigné, l'AMBSS lui affecte une valeur alphanumérique aléatoire et unique.
Code de la réponse
201 (Created) : L'opération a réussi.
400 (Bad request) : La syntaxe de la description du souscripteur au format JSON est incorrecte ou le souscripteur fait référence à une configuration inconnue.
409 (Conflict) : Un souscripteur d'identifiant <id_subscriber> existe déjà.
500 (Internal server error) : Une erreur interne s'est produite.
Corps de la réponse
Aucune réponse en cas de succès (code 201) ; objet JSON détaillant l'erreur sinon :
{
"timestamp": 1648479612407,
"status": 400,
"error": "Bad Request",
"message": "Subscriber with id 'subTemperature' is not valid. Validation failed for subscriber 'subTemperature'. Config object must only contains valid reference(s) to existing configuration(s)",
"path": "/ambss/v1/subscribers"
}
En cas de succès, l'en-tête de la réponse contient un attribut "Location" dont la valeur est l'URL d'accès en lecture au souscripteur créé (avec l'exemple ci-dessus, l'en-tête contiendra Location: http://localhost:8080/ambss/v1/subscribers/subUsingTwoPartialConfigAndComplete)
USER (propriété 'ambss.security.role-names.user-role') et ADMIN (propriété 'ambss.security.role-names.admin-role')
Code de la réponse
200 (OK) : L'opération a réussi.
404 (Not Found) : Le souscripteur d'identifiant <id_subscriber> n'existe pas.
405 (Method Not Allowed) : Le souscripteur d'identifiant <id_subscriber> n'a pas pu être démarré car il n'est pas dans le bon état (état "arrêté").
500 (Internal server error) : Une erreur interne s'est produite.
Corps de la réponse
En cas de succès (code 200), description du souscripteur d'identifiant <id_subscriber> dans sa forme déduite au format JSON ; objet JSON détaillant l'erreur sinon.
USER (propriété 'ambss.security.role-names.user-role') et ADMIN (propriété 'ambss.security.role-names.admin-role')
Corps de la requête
Message au format JSON décrivant les paramètres d'arrêt du souscripteur. Ces paramètres dépendent de la fabrique et du courtier associés au souscripteur.
Kafka
Aucun paramètres (objet JSON vide). Voir la propriété 'config/brokerConfig/subscribeTopic/stopImmediate' pour le comportement d'arrêt du souscripteur natif.
404 (Not Found) : Le souscripteur d'identifiant <id_subscriber> n'existe pas.
405 (Method Not Allowed) : Le souscripteur d'identifiant <id_subscriber> n'a pas pu être démarré car il n'est pas dans le bon état (état "démarré").
500 (Internal server error) : Une erreur interne s'est produite.
Corps de la réponse
En cas de succès (code 200), description du souscripteur d'identifiant <id_subscriber> dans sa forme déduite au format JSON ; objet JSON détaillant l'erreur sinon.
Lecture
Plusieurs opérations de lecture permettent de récupérer de l'information sur les souscripteurs.
USER (propriété 'ambss.security.role-names.user-role') et ADMIN (propriété 'ambss.security.role-names.admin-role')
Code de la réponse
200 (OK) : L'opération a réussi.
404 (Not Found) : Le souscripteur d'identifiant <id_subscriber> n'existe pas.
500 (Internal server error) : Une erreur interne s'est produite.
Corps de la réponse
En cas de succès (code 200), description du souscripteur d'identifiant <id_subscriber> dans sa forme déduite au format JSON ; objet JSON détaillant l'erreur sinon.
Liste des souscripteurs
Cette méthode permet de récupérer l'ensemble des souscripteurs créés, en appliquant optionnellement des filtres de recherche.
Méthode HTTP
GET
URL
http://<port_number>/ambss/v1/subscribers
Rôles
USER (propriété 'ambss.security.role-names.user-role') et ADMIN (propriété 'ambss.security.role-names.admin-role')
Paramètres dans l'URL
id : Pattern (expression régulière) d'identifiant de souscripteur,
adeliaPoolName : Pattern (expression régulière) de nom de pool de connections Adélia,
factory.id : Pattern (expression régulière) d'identifiant de fabrique contenue dans la description du souscripteur,
adeliaPgm.objectFileName : Pattern (expression régulière) du nom de fichier objet issu de la génération L3G du programme EADELIA contenu dans la description du souscripteur,
adeliaPgm.javaPackage : Pattern (expression régulière) du nom du package Java défini pour la génération L3G du programme EADELIA associé contenu dans la description du souscripteur,
adeliaPgm.customObjectMapper : Pattern (expression régulière) de l'identifiant du Java Bean définit dans le fichier beans-context.xml permettant de configurer les propriétés de transformation d'objet JSON en instance de classe Adélia contenu dans la description du souscripteur,
404 (Not Found) : Le souscripteur d'identifiant <id_subscriber> n'existe pas.
500 (Internal server error) : Une erreur interne s'est produite.
Corps de la réponse
En cas de succès (code 200), liste au format JSON des descriptions des souscripteurs (dans leur forme déduite) satisfaisant les critères des filtres appliqués ; objet JSON détaillant l'erreur sinon.
Liste des configurations associées à un souscripteur
USER (propriété 'ambss.security.role-names.user-role') et ADMIN (propriété 'ambss.security.role-names.admin-role')
Code de la réponse
200 (OK) : L'opération a réussi.
404 (Not Found) : Le souscripteur d'identifiant <id_subscriber> n'existe pas.
500 (Internal server error) : Une erreur interne s'est produite.
Corps de la réponse
En cas de succès (code 200), liste au format JSON des configurations référencées par le souscripteur d'identifiant <id_subscriber> ; objet JSON détaillant l'erreur sinon.
Etat d'un souscripteur
Lorsqu'un souscripteur est créé, l'AMBSS lui associe, dans sa description, un état (objet de nom "state"). Il apparait lors de l'utilisation des API de lecture des souscripteurs. L'état est constitué des informations suivantes :
Nom
Type
Description
code
Entier parmi 1, 2 ou 3
Etat du souscripteur :
STOP (1) : Le souscripteur est à l'arrêt.
START (2) : Le souscripteur est démarré.
DELETE (3) : Le souscripteur est supprimé.
internalCode
Entier allant de 21 à 26
Etat interne du souscripteur :
init (21) : Etat initial à la création du souscripteur
idle (22) : Etat d'inaction du souscripteur
on_start (23) : Etat lors du traitement de l'événement on_start
on_message (24) : Etat lors du traitement de l'événement on_message
on_error (25) : Etat lors du traitement de l'événement on_error
on_stop (26) : Etat lors du traitement de l'événement on_stop
errorCode
Entier
Code d'erreur lorsque le souscripteur est dans l'état interne on_error (25)
errorMessage
Alphanumérique
Libellé du code d'erreur (errorCode)
Ci-après la liste des codes d'erreur possibles pour un souscripteur :
Numéro d'erreur
Libellé d'erreur
Arrêt immédiat
-101
La classe Java de la fabrique est introuvable.
Oui
-102
La classe Java de la fabrique n'implémente pas la bonne interface ni n'hérite de la bonne classe.
Oui
-103
Erreur lors de l'obtention du constructeur de la fabrique.
Oui
-104
Erreur lors de la création de l'instance de la fabrique.
Oui
-105
La méthode statique 'getFactory' est introuvable dans la classe de la fabrique.
Oui
-106
Erreur lors de l'appel à la méthode 'getFactory' de la classe de la fabrique.
Oui
-107
La méthode statique 'getFactory' doit retourner une instance du bon type.
Oui
-108
La propriété customObjectMapper ne correspond pas a un identificateur de bean existant.
Oui
Numéro d'erreur
Libellé d'erreur
Arrêt immédiat
-301
Erreur lors de la validation de la configuration de la connexion au courtier.
Oui
-302
Erreur lors de la validation de la configuration d'abonnement aux sujets.
Oui
-401
Erreur lors de la création du pattern de topics.
Oui
-402
Erreur lors du lancement du programme EADELIA.
Oui
-403
Erreur lors du traitement de l'événement ON_START : accusé de réception négatif renvoyé.
Oui
-404
Erreur lors de la création de la configuration du consumer Kafka à partir de la configuration de la connexion du courtier.
Oui
-501
Erreur lors de la conversion d'un pojo Avro en pojo Adélia.
Non
Numéro d'erreur
Libellé d'erreur
Arrêt immédiat
-301
Erreur lors de la validation de la configuration de la connexion au courtier.
Oui
-302
Erreur lors de la validation de la configuration d'abonnement aux sujets du courtier.
Oui
-401
Erreur lors de la création des options de connexion Paho MQTTv3 à partir de la configuration de la connexion du courtier.
Oui
-402
Erreur lors de la création du client Paho MQTTv3 à l'aide des options.
Oui
-403
Erreur lors de la connexion du client Paho MQTTv3 au courtier.
Oui
-404
Erreur lors de l'abonnement du client Paho MQTTv3 aux rubriques.
Oui
-405
Erreur lors du lancement du programme EADELIA.
Oui
-406
Erreur lors du traitement de l'événement ON_START : accusé de réception négatif renvoyé.
Oui
-501
Connexion au courtier perdue.
Oui / Non
-502
Erreur lors de la déconnexion forcée du client Paho MQTTv3.
Oui
-503
Erreur lors de la fermeture du client Paho MQTTv3.
Oui
Numéro d'erreur
Libellé d'erreur
Arrêt immédiat
-301
Erreur lors de la validation de la configuration de la connexion au courtier.
Oui
-302
Erreur lors de la validation de la configuration d'abonnement aux sujets du courtier.
Oui
-401
Erreur lors de la création des options de connexion Paho MQTTv5 à partir de la configuration de la connexion du courtier.
Oui
-402
Erreur lors de la création du client Paho MQTTv5 à l'aide des options.
Oui
-403
Erreur lors de la connexion du client Paho MQTTv5 au courtier.
Oui
-404
Erreur lors de l'abonnement du client Paho MQTTv5 aux rubriques.
Oui
-405
Erreur lors du lancement du programme EADELIA.
Oui
-406
Erreur lors du traitement de l'événement ON_START : accusé de réception négatif renvoyé.
Oui
-501
Connexion au courtier perdue.
Oui / Non
-502
Erreur lors de la déconnexion forcée du client Paho MQTTv5.
Oui
-503
Erreur lors de la fermeture du client Paho MQTTv5.
Oui
Numéro d'erreur
Libellé d'erreur
Arrêt immédiat
-301
Erreur lors de la validation de la configuration de la connexion au courtier.
Oui
-302
Erreur lors de la validation de la configuration d'abonnement aux sujets.
Oui
-401
Erreur lors de la création des options de connexion Nats à partir de la configuration de la connexion du courtier.
Oui
-402
Erreur lors de la création de la connexion Nats à l'aide des options de connexion.
Oui
-403
Erreur lors de la création des options de souscription JetStream à partir de la configuration de souscription aux rubriques.
Oui
-404
Erreur lors de la création du contexte JetStream.
Oui
-405
Erreur lors de la création des options de contexte JetStream à partir de la configuration de connexion du courtier.
Oui
-406
Erreur lors de la souscription aux rubriques du courtier JetStream.
Oui
-407
Erreur lors du lancement du programme EADELIA.
Oui
-408
Erreur lors du traitement de l'événement ON_START : accusé de réception négatif renvoyé.
Oui
-501
Erreur lors du désabonnement à la souscription aux rubriques du courtier JetStream.
Oui
-502
Erreur lors de la fermeture de la connexion Nats au courtier.
Oui
Numéro d'erreur
Libellé d'erreur
Arrêt immédiat
-301
Erreur lors de la validation de la configuration de la connexion au courtier.
Oui
-302
Erreur lors de la validation de la configuration d'abonnement aux sujets.
Oui
-401
Erreur lors de la création des options de connexion Stan à partir de la configuration de la connexion du courtier.
Oui
-402
Erreur lors de la création de la connexion Stan à l'aide de StreamingConnectionFactory.
Oui
-403
Erreur lors de la création des options d'abonnement Stan à partir de la configuration de souscription aux rubriques.
Oui
-404
Erreur lors du lancement du programme EADELIA.
Oui
-405
Erreur lors du traitement de l'événement ON_START : accusé de réception négatif renvoyé.
Oui
-501
La connexion au courtier Stan a été perdue.
Oui
-502
Erreur lors de la fermeture de la souscription aux rubriques du courtier.
Oui
-503
Erreur lors de la fermeture de la connexion au courtier.
Oui
Numéro d'erreur
Libellé d'erreur
Arrêt immédiat
-301
Erreur lors de la validation de la configuration de la connexion au courtier.
Oui
-302
Erreur lors de la validation de la configuration d'abonnement aux sujets du courtier.
Oui
-401
Erreur lors de la configuration de la connexion SSL : exception de gestion des clés pour toutes les opérations traitant de la gestion des clés.
Oui
-402
Erreur lors de la création de la connexion AMQP.
Oui
-403
Erreur lors de la création du canal AMQP.
Oui
-404
Erreur lors de la déclaration passive de la file d'attente.
Oui
-405
Erreur lors de la déclaration de la file d'attente.
Oui
-406
Erreur lors de la consommation de base dans la file d'attente.
Oui
-407
Erreur lors de l'appel channel.basicQos.
Oui
-408
Erreur lors de la déclaration passive de l'échangeur.
Oui
-409
Erreur lors de la déclaration de l'échangeur.
Oui
-410
Erreur lors Erreur lors de la liaison de la file d'attente.
Oui
-411
Erreur lors du lancement du programme EADELIA.
Oui
-412
Erreur lors du traitement de l'événement ON_START : accusé de réception négatif renvoyé.
Oui
-413
Erreur lors de la création des options de connexion RabbitMQ à partir de la configuration de la connexion du courtier.
Oui
-501
Erreur lors de la fermeture du canal.
Oui
-502
Erreur lors de la fermeture de la connexion.
Oui
-503
Fermeture de la connexion non déclenchée par l'application.
Oui
-504
Le souscripteur a été annulé par le courtier.
Oui
Numéro d'erreur
Libellé d'erreur
Arrêt immédiat
-301
Erreur lors de la validation de la configuration de la connexion au courtier.
Oui
-302
Erreur lors de la validation de la configuration d'abonnement aux rubriques.
Oui
-401
Erreur lors de la création de l'URI Redis à partir de la configuration de connexion au courtier.
Oui
-402
Erreur lors de la création de l'objet options ClientOptions / ClusterClientOptions à partir de la configuration de connexion au courtier.
Oui
-403
Erreur lors de la création de la connexion Pub / Sub au courtier Redis.
Oui
-404
Erreur lors de l'abonnement aux canaux et modèles du courtier.
Oui
-405
Erreur lors du lancement du programme EADELIA.
Oui
-406
Erreur lors du traitement de l'événement ON_START : accusé de réception négatif renvoyé.
Oui
-501
Erreur lors de la fermeture de la connexion au courtier Redis.
Oui
-502
Erreur lors de la fermeture du client Redis.
Oui
-503
Fermeture du client Redis Lettuce due à une perte de la connexion au courtier.
Oui
-504
Fermeture du client Redis Lettuce due à une erreur dans la communication avec le courtier.
write : Entier (0 ou 1). Permet pour cette requête d'outrepasser la valeur de la propriété 'ambss.subscribers.writer' et d'imposer la sauvegarde ou la non sauvegarde de la configuration créée (valeur 0 pour ne pas sauvegarder ; 1 pour sauvegarder).
Code de la réponse
204 (No Content) : L'opération a réussi.
400 (Bad Request) : La syntaxe de la description du souscripteur au format JSON est incorrecte ou le souscripteur fait référence à une configuration inconnue.
404 (Not Found) : Le souscripteur d'identifiant <id_subscriber> n'existe pas.
405 (Method Not Allowed) : La description du souscripteur d'identifiant <id_subscriber> n'a pas pu être mise à jour car celui-ci n'est pas dans le bon état (état "arrêté").
500 (Internal server error) : Une erreur interne s'est produite.
Corps de la réponse
Aucune réponse en cas de succès (code 204) ; objet JSON détaillant l'erreur sinon.
write : Entier (0 ou 1). Permet pour cette requête d'outrepasser la valeur de la propriété 'ambss.subscribers.writer' et d'imposer la sauvegarde ou la non sauvegarde de la configuration créée (valeur 0 pour ne pas sauvegarder ; 1 pour sauvegarder).
Code de la réponse
204 (No Content) : L'opération a réussi.
404 (Not Found) : Le souscripteur d'identifiant <id_subscriber> n'existe pas.
405 (Method Not Allowed) : Le souscripteur d'identifiant <id_subscriber> n'a pas pu être supprimé car il n'est pas dans le bon état (état "arrêté").
500 (Internal server error) : Une erreur interne s'est produite.
Corps de la réponse
Aucune réponse en cas de succès (code 204) ; objet JSON détaillant l'erreur sinon.
Lors de l'utilisation de l'AMBSS en développement (via les scripts ambss-dev.<bat/sh>), l'authentification est désactivée.
Lors de l'utilisation de l'AMBSS en production (via les scripts ambss.<bat/sh>), l'authentification est activée par défaut. Pour la désactiver, il faut fixer la propriété 'ambss.security.enabled' à "false" dans le fichier de configuration application.yml.
Une section indique comment configurer l'authentification d'accès. Elle se fait via l'utilisation d'un jeton JWT. Celui-ci doit définir un des deux rôles possibles pour exécuter les services REST (rôle utilisateur ou rôle administrateur).
Jeu d'exemples
L'AMBSS offre un support de test des API dans le cadre d'exemples d'utilisation (courtier MQTT). Il est nécessaire d'avoir des connaissances dans l'utilisation d'un client REST, comme Insomnia ou Postman par exemple.
