Notifications Microsoft Power Automate / Workflows

Aperçu

Source: https://www.microsoft.com/power-platform/products/power-automate
Prise en charge des images: Oui
Prise en charge des pièces jointes: Non
Limites de caractères des messages:
- Corps: 1000
Format(s) de message pris en charge:
- ✓TEXT
Créer votre URL Apprise

Configuration du Compte

Selon l’endroit où vous souhaitez voir apparaître votre notification, vous devez créer un workflow adapté. Par exemple, un workflow MS Teams peut ressembler à ceci :

La documentation correspondante se trouve ici.

Une fois terminé, cela générera une URL ressemblant à ceci :

https://prod-NO.LOCATION.logic.azure.com:443/workflows/WFID/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=SIGNATURE
       |-------------------------------| |-|             |                                                                                                  |
                    |                     |          {workflow}                                                                                          {signature}
             host information {host}      |
                                         {port}

Oui, l’URL est effectivement aussi longue… mais au final elle correspond à :

workflows://{host}:{port}/{workflow}/{signature}

URLs Power Automate

Certains workflows (notamment ceux créés depuis MS Teams) génèrent plutôt une URL de type Power Automate, qui ressemble à ceci :

https://prod-NO.LOCATION.logic.azure.com:443/powerautomate/automations/direct/workflows/WFID/triggers/manual/paths/invoke?api-version=2022-03-01-preview&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=SIGNATURE

Plus récemment, Microsoft a également commencé à générer ces URLs avec un segment de routage supplémentaire (cu/{route}) placé juste avant /workflows/ :

https://prod-NO.LOCATION.logic.azure.com:443/powerautomate/automations/direct/cu/24/workflows/WFID/triggers/manual/paths/invoke?api-version=2022-03-01-preview&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=SIGNATURE

Apprise prend en charge ces deux URLs telles quelles, tout comme le webhook classique ci-dessus. Si vous préférez la forme raccourcie workflows://, ajoutez pa=yes et, si votre webhook comportait un segment cu/, route={route} :

workflows://{host}:{port}/{workflow}/{signature}?pa=yes
workflows://{host}:{port}/{workflow}/{signature}?pa=yes&route={route}

Syntaxe

La syntaxe valide est la suivante :

https://prod-site.logic.azure.com:443/workflows/{workflow}/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig={signature}
https://prod-site.logic.azure.com:443/powerautomate/automations/direct/workflows/{workflow}/triggers/manual/paths/invoke?api-version=2022-03-01-preview&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig={signature}
https://prod-site.logic.azure.com:443/powerautomate/automations/direct/cu/{route}/workflows/{workflow}/triggers/manual/paths/invoke?api-version=2022-03-01-preview&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig={signature}
workflows://{host}:{port}/{workflow}/{signature}
workflows://{host}:{port}/{workflow}/{signature}?pa=yes&route={route}

Détail des Paramètres

Variable	Requis	Description
workflow	Oui	L’identifiant de workflow fourni dans le lien webhook Azure.
signature	Oui	L’identifiant de signature fourni dans le lien webhook Azure, c’est-à-dire `sig=`.
wrap	Non	Enveloppe le texte du corps dans la réponse.
ver	Non	Version d’API Power Automate à utiliser ; la valeur par défaut est `2016-06-01`. Cette valeur peut aussi être lue via le mot-clé `api-version` présent dans le lien webhook Azure.
pa	Non	À définir sur `yes` si votre webhook utilise la nouvelle structure d’URL Power Automate (`/powerautomate/automations/direct/...`). Aussi accepté sous le nom `powerautomate`. La valeur par défaut est `no`.
route	Non	L’identifiant de routage Power Automate ; il s’agit de la valeur numérique trouvée après `cu/` dans les URLs webhook Power Automate récentes. Utilisé uniquement lorsque `pa=yes`. Aussi accepté sous le nom `routeid`.
template	Non	Permet d’indiquer le chemin vers un modèle que vous préférez utiliser à la place de la carte adaptative choisie par Apprise. Utilisez des doubles accolades `{{token}}` pour marquer les jetons à remplacer avant soumission au service amont, par exemple `{{app_body}}` ou `{{app_title}}`.

Paramètres Globaux

Variable	Description
overflow	Gère les messages qui dépassent la limite documentée d’un service. La valeur par défaut est `upstream`. 👉 `upstream` : envoie un seul message sans le découper ni le tronquer selon cette limite. 👉 `truncate` : conserve la partie qui tient dans la limite et supprime le reste. 👉 `split` : privilégie une coupure lisible, utilise une coupure stricte si nécessaire, puis envoie toutes les parties dans l’ordre. Le découpage d’un contenu non déclaré ou structuré reste une solution au mieux. Utilisez `upstream` si le corps doit rester intact.
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`.
redirect	Par défaut, Apprise suit les redirections HTTP (réponses 3xx) émises par le serveur distant, conformément au comportement de la bibliothèque requests sous-jacente. Si vous souhaitez empêcher la transmission des en-têtes personnalisés et des identifiants vers des destinations différentes de l’URL d’origine, définissez cette option sur `no`. Par défaut, elle 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.
retry	Nombre de tentatives de remise supplémentaires après le premier échec, avant d’abandonner. Accepte un entier compris entre `0` et `10`. La valeur par défaut est `0` (aucune nouvelle tentative — une seule tentative est effectuée). Lorsqu’il est combiné avec `wait`, Apprise marque une pause du nombre de secondes spécifié entre chaque tentative.
wait	Nombre de secondes à attendre entre les nouvelles tentatives. Accepte une valeur décimale comprise entre `0.0` et `20.0` ; les entiers sont automatiquement convertis en virgule flottante. La valeur par défaut est `0.5`. Ce paramètre n’est utile que si `retry` est supérieur à zéro — un service avec `retry=0` effectue exactement une tentative, quelle que soit la valeur de `wait`.
optional	Lorsqu’il est défini sur `yes`, un échec de remise pour ce service est silencieusement absorbé. Le résultat global de `notify()` est quand même considéré comme réussi même si ce point de terminaison était injoignable, à condition que tous les services requis (non optionnels) du même lot aient réussi. Ce drapeau ne saute pas la remise ni ne contourne la logique de nouvelles tentatives — toutes les tentatives configurées sont effectuées avant que l’échec soit absorbé. Par défaut, il vaut `no`, ce qui signifie que chaque échec est propagé à l’appelant.

Mentions MS Teams

Lorsque votre Workflow envoie des messages vers un canal Microsoft Teams, Apprise gère automatiquement les @mentions. Il suffit d’entourer l’adresse UPN (adresse e-mail) ou le nom d’affichage du destinataire avec des balises <at> directement dans le corps du message :

Bonjour <at>alice@example.com</at>, la compilation a échoué !

Apprise détecte chaque balise <at>...</at> dans le corps et injecte automatiquement la structure d’entité Teams requise dans la charge utile — aucune configuration supplémentaire n’est nécessaire. Les mentions multiples et la suppression des doublons sont toutes deux gérées :

<at>alice@example.com</at> et <at>bob@example.com</at>, merci de bien vouloir vérifier.

Modèles

L’Argument d’URL `template`

Définissez un argument ?template= pointant vers une charge utile JSON prédéfinie que vous souhaitez fournir au workflow. Dans l’idéal, vous pouvez rester sur le format AdaptiveCards.

Les Jetons de Modèle

Le template= que vous indiquez peut soit être entièrement rempli et prêt à être utilisé tel quel, soit être alimenté dynamiquement à chaque appel Apprise. Pour cela, utilisez des doubles accolades {{ et }} autour d’un mot-clé de votre choix, comme dans l’exemple ci-dessous :

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    {
      "type": "TextBlock",
      "text": "{{app_title}}",
      "weight": "Bolder",
      "separator": true
    },
    {
      "type": "TextBlock",
      "text": "{{app_body}}",
      "wrap": true
    }
  ]
}

Dans l’exemple ci-dessus, nous introduisons plusieurs jetons : app_id, app_title, target et whence. Certaines entrées seront TOUJOURS définies et ne peuvent pas être surchargées :

app_id : l’identifiant de l’application, généralement défini à Apprise, même si un développeur peut le surcharger.
app_desc : la description de l’application, souvent une variante un peu plus explicite de app_id. Elle vaut généralement Apprise Notification sauf surcharge.
app_color : un code hexadécimal représentant la couleur associée au message. Par exemple, les messages info sont souvent bleus, tandis que les messages warning sont orange.
app_color_hex : alias explicite de app_color ; même valeur hexadécimale, fourni pour que les modèles puissent utiliser un nom explicite pour la variante hexadécimale.
app_type : le type du message lui-même, comme info, warning, success, etc.
app_title : le titre réel transmis à la notification Apprise via --title ou -t.
app_body : le corps réel transmis à la notification Apprise via --body ou -b.
app_image_url : l’URL de l’image associée au type de message, par exemple info ou warning, si elle existe et n’a pas été désactivée dans l’URL via image=no.
app_url : l’URL associée à l’instance Apprise, trouvée dans l’objet AppriseAsset(). Sauf surcharge explicite, sa valeur est https://github.com/caronc/apprise.

Tout ce que vous inventez en dehors de cela vous appartient. Revenons donc à target et whence. Les jetons de modèle peuvent être définis dynamiquement en utilisant l’opérateur : devant les arguments d’URL de votre choix. Par exemple :

workflows://credentials/?template=/path/to/template.json&:target=Chris&:whence=this%20afternoon
workflows://credentials/?template=http://host/to/template.json&:target=Chris&:whence=this%20afternoon

Une notification comme celle-ci :

# En utilisant des deux-points, nous pouvons définir dynamiquement
# target et whence depuis la ligne de commande :
apprise -t "Mon Titre va dans app_title" -b "Ceci est placé dans app_body" \
   "workflows://credentials/?template=http://host/to/template.json&:target=Chris&:whence=this%20afternoon"

Publierait dans MS Teams en suivant le modèle ci-dessus :

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "{{app_title}}",
      "weight": "Bolder",
      "separator": true
    },
    {
      "type": "TextBlock",
      "text": "{{app_body}}",
      "wrap": true
    },
    {
      "type": "TextBlock",
      "text": "Hello {{ target }}, how are you {{ whence }}?",
      "wrap": true
    }
  ]
}

Remarques Supplémentaires sur les Modèles

Les jetons peuvent contenir des espaces autour d’eux pour améliorer la lisibilité. Ainsi, {{ token }} n’est pas différent de {{token}}.
Tous les jetons sont correctement échappés ; ne vous inquiétez donc pas si une valeur contient un guillemet double ("), il sera correctement échappé avant l’envoi en amont.
Les jetons sont sensibles à la casse. Ainsi, {{Token}} doit être alimenté par une valeur :Token= dans votre URL.
Les jetons qui ne correspondent à rien ne sont tout simplement pas remplacés, et {{keyword}} restera tel quel dans le message.
Apprise exige toujours au minimum un --body (-b), qui peut éventuellement être référencé sous {{app_body}} dans votre modèle. Même si vous ne l’utilisez pas, vous devez tout de même fournir une valeur pour satisfaire cette exigence et utiliser les modèles.

Exemples

Envoyer une notification Microsoft Teams :

# Supposons que notre {host} soit prod-site.logic.azure.com
# Supposons que notre {port} soit 443
# Supposons que notre {workflow} soit T1JJ3T3L2@DEFK543
# Supposons que notre {signature} soit TIiajkdnlazkcOXrIdevi7F
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   workflows:///prod-site.logic.azure.com:443/T1JJ3T3L2@DEFK543/TIiajkdnlazkcOXrIdevi7F/

Envoyer une notification Teams avec une @mention :

apprise -vv -t "Compilation échouée" \
   -b "Salut <at>alice@example.com</at>, la compilation nocturne nécessite votre attention." \
   workflows://prod-site.logic.azure.com:443/T1JJ3T3L2@DEFK543/TIiajkdnlazkcOXrIdevi7F/

Mentionner plusieurs personnes dans un seul message :

apprise -vv -t "Déploiement terminé" \
   -b "<at>alice@example.com</at> et <at>bob@example.com</at> -- déployé en production." \
   workflows://prod-site.logic.azure.com:443/T1JJ3T3L2@DEFK543/TIiajkdnlazkcOXrIdevi7F/

Envoyer une notification via un webhook Power Automate comportant un segment de routage cu/ :

apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "workflows://prod-site.logic.azure.com:443/T1JJ3T3L2@DEFK543/TIiajkdnlazkcOXrIdevi7F/?pa=yes&route=24"

Questions ou commentaires ?

Documentation

Vous avez repéré une faute de frappe ou une erreur ?

Problèmes Techniques

Vous rencontrez un problème avec le code ? Ouvrez un ticket sur GitHub :