Différences

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

--- technique:adminserv:mattermost:hooks_commands [2021/01/05 11:12] – 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** et de **commandes slash**.
+Deux fonctionnalités méconnues de Mattermost sont la création de **hooks entrants** et de **commandes slash**.
-* Un **hook** est une URL spéciale qui permet de poster un message sur un canal particulier lorsque l'URL est requêtée.
+* 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** 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.
-Ces commandes slash (abréviées *commandes* dans la suite) sont à différencier des commandes de plugin (comme `/spoiler`), qui ne requêtent pas nécessairement une URL extérieure.
+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.
-<bootnote warning>Notez que l'on ne traite que les webhooks **entrants**. Les webhooks **sortants** sont une autre manière de déclencher l'appel à une URL externe lors de l'occurrence d'un mot clé spécifique. Ils fonctionnent comme les webhooks entrants, sur le principe.
-</bootnote>
 ## Administration et portée
-Les hooks et les commandes sont **circonscrits** à une équipe. Une commande mise en place sur une équipe ne fonctionnera que sur cette équipe.
+Les hooks et les commandes sont **circonscrits à une seule équipe**. Une commande mise en place sur une équipe ne fonctionnera que sur cette équipe.
 Les administrateurs d'équipes sont les seules personnes à pouvoir gérer les hooks et commandes. Ceci étant, c'est très pratique car il n'y a pas besoin d'un administrateur système pour créer ses propres commandes/hooks.
@@ Ligne 49: / Ligne 46: @@
 ```
-Ou depuis le menu (clic sur le burger à côté du nom de compte → Intégrations).
+{{ :technique:adminserv:mattermost:integ_mattermost.png |}}
+## Créer et tester un hook entrant
+<bootnote web>[Documentation officielles hooks entrants](https://docs.mattermost.com/developer/webhooks-incoming.html)</bootnote>
+Depuis les intégrations, ajouter un nouveau hook entrant. Voici un exemple de paramétrage :
+{{ :technique:adminserv:mattermost:webhook_incoming.png |}}
+Avec cette configuration, quiconque possède le lien du hook pourra poster dans le canal `Tests`, avec le nom d'utilisateur `webhook` et la photo de profil accessible à l'URL donnée.
+<bootnote warning>Il est **recommandé** de verrouiller le canal. En effet, le lien suffit pour poster des messages et est donc assez sensible. S'il permettait de poster n'importe où, on pourrait imaginer des situations d'usurpation assez problématiques.</bootnote>
+Une URL confidentielle est générée suite à l'enregistrement du hook.
+{{ :technique:adminserv:mattermost:webhook_success.png |}}
+Cette URL peut maintenant être utilisée par une application compatible Slack ou Mattermost. Mais elle peut aussi être utilisée "à la main" ou dans un script personnalisé.
+Pour ce faire, il suffit d'effectuer une requête `POST` sur l'URL, avec pour corps de la requête un objet `JSON` contenant a minima un champ `text` dont la valeur est le corps du message à poster sur le canal.
+En reprenant l'exemple précédent, la commande suivante postera un message sur le canal `Tests` :
+```bash
+$ curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "## Message formaté !!\nAvec retour à la ligne et mention @quentinduchemin :relaxed:"}' https://team.picasoft.net/hooks/sxdkzr7gotystkj5gmdmqt9ofy
+```
+Le message est en effet reçu, le formatage Markdown est interprété et les mentions envoient des notifications aux personnes concernées.
+{{ :technique:adminserv:mattermost:webhook_posted.png |}}
+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.
-## Exemple de hook entrant
+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.