technique:adminserv:mattermost:hooks_commands

Différences

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

Lien vers cette vue comparative

Les deux révisions précédentes Révision précédente
Prochaine révision		 Révision précédente
technique:adminserv:mattermost:hooks_commands [2021/01/05 11:14] – [Préambule] qduchemitechnique:adminserv:mattermost:hooks_commands [2022/04/25 09:59] (Version actuelle) – qduchemi
Ligne 1: Ligne 1:
 +{{indexmenu_n>20}}
  
 +# Gérer les intégrations
 +
 +Par intégration, on entend les interactions entre Mattermost et d'autres applications.
 +
 +## Préambule
 +
 +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 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é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
 +  * CPU au dessus de 80% sur une des machines virtuelles : une mention est envoyée à l'équipe technique.
 +</bootnote>
 +
 +<bootnote warning>Les hooks ne fonctionnent qu'avec des outils "compatibles" Slack ou Mattermost.</bootnote>
 +
 +<bootnote>
 +Les **commandes slash** sont utiles pour déclencher une action extérieure ou générer un message contenant une information dynamique. Exemples :
 +  * Obtenir les statistiques d'un service, les mettre en forme et les poster
 +  * Déclencher la génération d'un rapport journalier quelconque
 +  * Générer et poster une citation d'un personnage de Kaamelott
 +</bootnote>
 +
 +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
 +
 +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.
 +
 +La personne qui crée une équipe en est automatiquement administrateur, et peut ensuite étendre ce rôle aux autres membres depuis la gestion des membres de l'équipe. La plupart des personnes ne sont pas au courant de ce rôle, il ne faut pas hésiter à leur signaler si ça peut être utile. :)
 +
 +La gestion des intégrations se fait depuis l'URL suivante, construite à partir du nom de l'équipe :
 +
 +```
 +https://team.picasoft.net/<equipe>/integrations
 +```
 +
 +{{ :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.
 +
 +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.
 +
 +Ces paramètres sont traités dans la documentation officielle.