Différences

Ci-dessous, les différences entre deux révisions de la page.

--- technique:adminserv:mattermost:hooks_commands [2021/01/05 15:47] – [Exemple de hook entrant] qduchemi
+++ technique:adminserv:mattermost:hooks_commands [2022/04/25 09:59] (Version actuelle) – qduchemi
@@ Ligne 7: / Ligne 7: @@
 ## Préambule
-Deux fonctionnalités méconnues de Mattermost mais néanmoins utiles sont la création de **hooks entrants** et de **commandes slash**.
+Deux fonctionnalités méconnues de Mattermost sont la création de **hooks entrants** et de **commandes slash**.
 * Un **hook entrant** (abrévié hook par la suite) est une URL spéciale qui permet de poster un message sur un canal particulier lorsque l'URL est requêtée.
-* Une **commande slash** (abrévié commande par la suite) est un mot clé précédé d'un symbole `/` qui déclenche l'appel à une URL externe et remplace le message par la réponse.
+* Une **commande slash** (abrévié commande par la suite) est un mot clé précédé d'un symbole `/` qui déclenche l'appel à une URL externe et remplace le commande par la réponse de l'URL.
 Les commandes sont à différencier des commandes de plugin (comme `/spoiler`), qui ne requêtent pas nécessairement une URL extérieure.
 <bootnote>
-Les **hooks** sont très pratiques pour réagir à un événement extérieur et poster un message suite à cet événements. Voici quelques exemples :
+Les **hooks** sont très pratiques pour réagir à un événement extérieur et poster un message suite à cet événement. Voici quelques exemples :
   * Ajout d'une nouvelle tâche sur un kanban : un message est posté sur le canal concerné
   * Ouverture d'une nouvelle issue sur Gitlab : une mention est envoyée aux membres du dépôt
@@ Ligne 30: / Ligne 30: @@
 </bootnote>
-Pour résumer, les hooks permettent d'être informés d'un événements, les commandes permettent de déclencher un événement ou de générer des informations dynamiques.
+Pour résumer, les hooks permettent d'être informés d'un événement, les commandes permettent de déclencher un événement ou de générer des informations dynamiques.
 ## Administration et portée
@@ Ligne 45: / Ligne 45: @@
 https://team.picasoft.net/<equipe>/integrations
 ```
-Ou depuis le menu (clic sur le burger à côté du nom de compte → Intégrations).
 {{ :technique:adminserv:mattermost:integ_mattermost.png |}}
@@ Ligne 80: / Ligne 78: @@
 Côté console, on reçoit un `200 OK` pour indiquer que tout s'est bien passé.
+## Créer et tester une commande slash
+<bootnote web>[Documentation officielle des commandes slash](https://docs.mattermost.com/developer/slash-commands.html)</bootnote>
+L'idée est de montrer le fonctionnement basique d'une commande.
+On se rend dans les intégrations, onglet commandes slash, et on crée une commande, par exemple :
+{{ :technique:adminserv:mattermost:mattermost_commande.png |}}
+Les paramètres sont similaires au webhook entrant. En revanche, deux choix sont importants :
+* L'URL qui sera appelée lors du déclenchement de la commande,
+* La méthode (`GET` ou `POST`).
+Le reste est de la responsabilité du serveur, qui reçoit toutes les informations de la commande et formate une réponse.
+{{ :technique:adminserv:mattermost:mattermost_commande_ok.png |}}
+<bootnote web>
+On pourra consulter :
+  * Les [paramètres de la requête envoyée par Mattermost](https://developers.mattermost.com/integrate/slash-commands/#basic-usage)
+  * Les [paramètres supportés dans la réponse](https://developers.mattermost.com/integrate/slash-commands/#parameters)
+</bootnote>
+Dans tous les cas, le serveur distant doit répondre avec un objet `JSON` qui contient au moins l'attribut `text`, valeur du message à écrire en réponse à la commande.
+Voici un exemple simplissime qui répond à toutes les requêtes `POST` en ajoutant dans la réponse les paramètres passés à la commande :
+```python
+from flask import Flask, request
+app = Flask(__name__)
+@app.route('/', methods=['POST'])
+def result():
+    return {
+        "text": f"## Commande reçue!\nPayload : {request.form['text']}"
+    }
+```
+Pour le tester, il suffit de l'enregistrer (par exemple `simple_server.py`), puis de lancer :
+```bash
+$ pip install flask
+$ FLASK_APP=simple_server.py flask run -h 0.0.0.0
+```
+L'application est accessible à l'URL de votre serveur sur le port 5000.
+<bootnote critical>Ne jamais utiliser ce genre d'exemples en production! Le serveur de développement de Flask n'est à utiliser que pour des tests. De plus, HTTPS n'est pas activé, ce qui rend possible l'interception du jeton utilisé pour valider la réponse.</bootnote>
+<bootnote critical>Dans un exemple réel, le serveur doit valider que le jeton reçu en paramètre de la requête (`token`) est le même que le jeton généré après l'ajout de la commande dans Mattermost. Cette vérification permet de valider que la requête vient bien de Mattermost, et pas d'un usurpateur qui pourrait vouloir récupérer des informations sensibles ou déclencher un processus non-souhaité.</bootnote>
+Pour tester, il suffit de déclencher la commande dans n'importe quel canal de l'équipe :
+```
+/test_commande Voici les paramètres!
+```
+La commande est envoyée, et Mattermost affiche en réponse :
+{{ :technique:adminserv:mattermost:mattermost_command_done.png |}}
+<bootnote>
+Par défaut, le message n'est visible que par la personne qui écrit la commande. Il est possible de changer ce comportement en assignant `in_channel` à l'attribut `response_type` dans l'objet JSON de la réponse.
+</bootnote>
+## Conclusion
+Les commandes et les hooks sont très puissants. Dans leur forme basique, ils permettent de poster un message en réponse à un événement extérieur ou une commande depuis Mattermost.
+En plus des exemples basiques vus ici (seul l'attribut `text` de la réponse est utilisé), il existe des options avancées de formatage, de redirection, de réponse délayée, de remplacement du nom d'utilisateur, etc.
-## Exemple de commande slash
+Ces paramètres sont traités dans la documentation officielle.