Notifications Slack

Aperçu

• Source: https://slack.com/
• Prise en charge des images: Oui
• Prise en charge des pièces jointes: Oui
• Limites de caractères des messages:
  • Corps: 35000
• Créer votre URL Apprise

Configuration du compte

Slack est un peu plus complexe que certains autres services de notification. Voici donc un résumé rapide de ce que vous devez savoir et faire pour envoyer des notifications avec cet outil.

Méthode 1 : Webhook Entrant

Les notifications Slack exigent tout d’abord un incoming-webhook auquel se connecter.

1. Vous pouvez créer ce webhook ici. Suivez simplement l’assistant pour choisir à l’avance le ou les canaux où vos messages seront diffusés.
2. Vous pouvez aussi créer une Slack App ici et l’associer à l’un de vos espaces de travail Slack. Il suffit ensuite de quelques étapes supplémentaires, toutes effectuées depuis l’écran de configuration de l’application, pour récupérer votre URL webhook :
   • vous devez activer la fonctionnalité Incoming Webhook si ce n’est pas déjà fait ;
   • sur ce même écran de configuration, vous pouvez créer un webhook et l’associer à un canal ou à un utilisateur.

Quelle que soit l’option choisie ci-dessus, vous obtiendrez une URL webhook ressemblant à ceci :
https://hooks.slack.com/services/T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcOXrIdevi7F

Cette URL correspond en pratique à :
https://hooks.slack.com/services/{tokenA}/{tokenB}/{tokenC}

Remarque : Apprise prend en charge cette URL telle quelle (depuis la version 0.7.7). Vous n’avez donc plus besoin de la reparser, même s’il y a un léger gain interne à le faire.

Si vous voulez la convertir en URL Apprise, procédez comme suit : la dernière partie de l’URL qui vous est fournie contient les 3 jetons nécessaires à l’envoi des notifications. Dans l’exemple ci-dessus, ils sont les suivants :

1. TokenA est T1JJ3T3L2
2. TokenB est A1BRTD4JD
3. TokenC est TIiajkdnlazkcOXrIdevi7F8

Méthode 2 : Créer un Robot

Les bots offrent un peu plus de souplesse que les webhooks. La principale différence est que les Slack Bots prennent en charge les pièces jointes, ce qui permet à Apprise d’en tirer parti.

1. Commencez par créer votre Slack App ici.
2. Choisissez un nom d’application, par exemple Apprise, sélectionnez votre espace de travail, puis cliquez sur Create App.
3. Vous pourrez ensuite ouvrir la section Bots, ajouter un utilisateur robot, lui donner un nom, puis choisir *Add Bot User.
4. Vous devrez fournir les bonnes permissions OAuth :
   
5. Sélectionnez ensuite Install App, puis Install App to Workspace.
6. Vous devrez autoriser l’application lorsqu’on vous le demandera.
7. Enfin, vous obtiendrez des informations très importantes pour Apprise. À partir de là, vous pourrez utiliser soit le jeton d’accès OAuth, soit le jeton d’accès OAuth de l’utilisateur robot, avec une syntaxe de type slack://{OAuth Access Token}.

Votre URL Apprise Slack, pour accéder à votre bot, peut ressembler à ceci :

• slack://xoxp-1234-1234-1234-4ddbc191d40ee098cbaae6f3523ada2d
• slack://xoxb-1234-1234-4ddbc191d40ee098cbaae6f3523ada2d

Les deux jetons OAuth fournis permettent de publier du texte dans des canaux et de joindre des fichiers. Le choix de l’un ou de l’autre depend donc de votre preference.

Syntaxe

La syntaxe valide est la suivante :

• slack://{tokenA}/{tokenB}/{tokenC}
• https://hooks.slack.com/services/{tokenA}/{tokenB}/{tokenC}
• slack://{OAuthToken}/
  • Un robot n’a pas de canal par défaut configurable dans Slack comme c’est le cas avec les webhooks. Si aucun canal n’est précisé, c’est #general qui sera utilisé.

Si vous utilisez l’ancienne méthode par webhook, sans passer par l’application, vous disposez d’un peu plus de liberté. Les URL suivantes fonctionneront donc également avec Apprise :

• slack://{tokenA}/{tokenB}/{tokenC}/#{channel}
• slack://{tokenA}/{tokenB}/{tokenC}/#{channel1}/#{channel2}/#{channelN}
• slack://{OAuthToken}/#{channel}
• slack://{botname}@{OAuthToken}/#{channel1}/#{channel2}/#{channelN}

Si vous connaissez l’Encoded-ID du canal que vous souhaitez cibler, vous pouvez utiliser le symbole plus (+) pour le distinguer des canaux dans l’URL. La syntaxe valide est la suivante :

• slack://{botname}@{tokenA}/{tokenB}/{tokenC}/+{encoded_id}
• slack://{botname}@{tokenA}/{tokenB}/{tokenC}/+{encoded_id1}/+{encoded_id2}/+{encoded_id3}
• slack://{botname}@{OAuthToken}/+{encoded_id}
• slack://{botname}@{OAuthToken}/+{encoded_id1}/+{encoded_id2}/+{encoded_id3}

Si vous connaissez le user_id auquel vous souhaitez envoyer votre notification Slack, plutôt qu’un canal, utilisez le symbole arobase (@). La syntaxe valide est la suivante :

• slack://{botname}@{tokenA}/{tokenB}/{tokenC}/@{user_id}
• slack://{botname}@{tokenA}/{tokenB}/{tokenC}/@{user_id1}/@{user_id2}/@{user_id3}
• slack://{botname}@{OAuthToken}/@{user_id}
• slack://{botname}@{OAuthToken}/@{user_id1}/@{user_id2}/@{user_id3}

Vous pouvez également combiner librement toutes ces formes dans l’ordre de votre choix :

• slack://**{botname}@{tokenA}/{tokenB}/{tokenC}/@{user_id}/#{channel}/+{encoded_id}
• slack://{botname}@{OAuthToken}/@{user_id}/#{channel}/+{encoded_id}

Détail des Paramètres

Variable	Requis	Description
tokenA	Oui	La première partie des 3 jetons fournis après la création d’un incoming-webhook. OAuthToken n’est pas requis si vous utilisez le webhook Slack.
tokenB	Oui	La deuxième partie des 3 jetons fournis après la création d’un incoming-webhook. OAuthToken n’est pas requis si vous utilisez le webhook Slack.
tokenC	Oui	La dernière partie des 3 jetons fournis après la création d’un incoming-webhook. OAuthToken n’est pas requis si vous utilisez le webhook Slack.
OAuthToken	Oui	Jeton OAuth fourni par la Slack App lorsque vous utilisez un robot au lieu d’un webhook. Les jetons A, B et C ne sont alors pas utilisés.
channel	Non	Les canaux doivent être préfixés par #. Vous pouvez en préciser autant que vous voulez en les séparant par des slashs (/) dans l’URL.
encoded_id	Non	Slack permet aussi de désigner des canaux et canaux privés par un encoded_id. Si vous les connaissez, vous pouvez les utiliser à la place d’un nom de canal. Tous les encoded_id doivent être préfixés par +.
user_id	Non	Les utilisateurs doivent être préfixés par @. Vous pouvez en préciser autant que nécessaire en les séparant par des slashs (/) dans l’URL.
botname	Non	Nom du bot qui doit publier le message. Si rien n’est précisé, la valeur par défaut correspond à votre propre compte associé à l’incoming-webhook.
footer	Non	Détermine si l’icône de pied de page Apprise doit être affichée à chaque message. La valeur par défaut est yes.
image	Non	Détermine si l’image Apprise, reflétant la couleur d’état, doit être affichée avec chaque message. La valeur par défaut est yes.
mode	Non	Permet de forcer le mode de fonctionnement du plugin Slack. Il est détecté automatiquement par défaut, mais les valeurs possibles sont hook, gov-hook et bot, ce dernier utilisant l’API bot Slack.

Paramètres Globaux

Variable	Description
overflow	Ce paramètre peut être défini sur split, truncate ou upstream. Il détermine la manière dont Apprise remet le message que vous lui transmettez. Par défaut, il vaut upstream. 👉 upstream : ne fait aucune modification et transmet le message exactement tel qu’il a été reçu au service. 👉 truncate : veille à ce que le message tienne dans la limite amont documentée par le service. Si plus d’informations sont fournies que la limite définie, l’excédent est tronqué. 👉 split : similaire à truncate, sauf que si le message dépasse la limite amont documentée par le service, il est découpé en plusieurs morceaux plus petits puis envoyés séquentiellement.
format	Ce paramètre peut être défini sur text, html ou markdown. Certains services prennent en charge plusieurs formats de publication du contenu. La valeur par défaut varie selon le service choisi et peut correspondre à l’un de ces trois formats. Vous pouvez facultativement forcer cette option pour vous écarter du comportement par défaut. Si le service ne prend pas en charge plusieurs formats de transmission, ce champ est ignoré.
verify	Les requêtes externes vers des emplacements sécurisés, par exemple via https, utilisent des certificats. Par défaut, Apprise vérifie la validité de ces certificats ; si ce n’est pas le cas, aucune notification n’est envoyée à la source. Dans certains cas, un utilisateur ne dispose pas d’une autorité de certification pour valider la clé ou fait simplement confiance à la source ; dans ce cas, vous pouvez définir ce drapeau sur no. Par défaut, il vaut yes.
cto	Signifie Socket Connect Timeout. Il s’agit du nombre de secondes pendant lesquelles Requests attend que votre client établisse une connexion avec une machine distante, ce qui correspond à l’appel connect() sur la socket. La valeur par défaut est de 4.0 secondes.
rto	Signifie Socket Read Timeout. Il s’agit du nombre de secondes pendant lesquelles le client attend que le serveur envoie une réponse. La valeur par défaut est de 4.0 secondes.
emojis	Active la prise en charge des emojis, par exemple :+1: qui sera traduit en 👍. Par défaut, cette option vaut no. Remarque : selon la configuration côté serveur, l’administrateur peut désactiver globalement la prise en charge des emojis ; mais par défaut, ce n’est pas le cas.
tz	Identifie le fuseau horaire de la base IANA que vous souhaitez utiliser. Par défaut, celui-ci est détecté à partir de la configuration du serveur qui exécute Apprise. Vous pouvez le définir sur des valeurs comme America/Toronto, ou sur tout autre fuseau correctement formaté correspondant à votre région.

Exemples

Envoyer une notification Slack vers le canal #nuxref :

# Supposons que notre {tokenA} soit T1JJ3T3L2
# Supposons que notre {tokenB} soit A1BRTD4JD
# Supposons que notre {tokenC} soit TIiajkdnlazkcOXrIdevi7F
# Notre canal nuxref est represente par #nuxref
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   slack:///T1JJ3T3L2/A1BRTD4JD/TIiajkdnlazkcOXrIdevi7F/#nuxref

Autrement, si vous utilisez un bot, une notification Slack vers le canal #general pourrait ressembler à ceci :

# Supposons que notre {OAuthToken} soit xoxb-1234-1234-4ddbc191d40ee098cbaae6f3523ada2d
# Notre canal general est represente par #general
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   slack://xoxb-1234-1234-4ddbc191d40ee098cbaae6f3523ada2d/#general

Vous pouvez aussi désactiver le pied de page, par exemple ainsi :

# Supposons que notre {OAuthToken} soit xoxb-1234-1234-4ddbc191d40ee098cbaae6f3523ada2d
# Nous voulons l'envoyer vers notre canal #general ; %23 est la forme encodee du symbole #
# Nous definissons aussi footer sur no
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   slack://xoxb-1234-1234-4ddbc191d40ee098cbaae6f3523ada2d/%23general?footer=no