Notifications API Apprise

Aperçu

• Source: https://github.com/caronc/apprise-api
• Prise en charge des images: Non
• Prise en charge des pièces jointes: Oui
• Limites de caractères des messages:
  • Corps: 32768
• Format(s) de message pris en charge:
  • ✓TEXT
  • HTML
  • MARKDOWN
• Créer votre URL Apprise

Configuration du Compte

Installez une instance Apprise API auto-hébergée, puis utilisez ce service pour lui envoyer des notifications.

Syntaxe

La syntaxe valide est la suivante :

• apprise://{host}/{token}
• apprise://{host}:{port}/{token}
• apprise://:{password}@{host}:{port}/{token}
• apprise://{user}@{host}:{port}/{token}
• apprise://{user}:{password}@{host}:{port}/{token}

Pour une connexion sécurisée, utilisez plutôt apprises.

• apprises://{host}/{token}
• apprises://{host}:{port}/{token}
• apprises://:{password}@{host}:{port}/{token}
• apprises://{user}@{host}:{port}/{token}
• apprises://{user}:{password}@{host}:{port}/{token}

Détail des Paramètres

Variable	Obligatoire	Description
hostname	Oui	Nom d’hôte du serveur Web.
port	Non	Port du serveur Web. La valeur par défaut est 80 pour apprise:// et 443 pour apprises://.
user	Non	Nom d’utilisateur employé lorsque le serveur exige HTTP Basic Auth.
password	Non	Mot de passe employé lorsque le serveur exige HTTP Basic Auth.
tags	Non	Tags facultatifs envoyés avec la requête.
version	Non	La version 2 envoie le jeton dans X-Apprise-Config-ID et est utilisée par défaut. La version 1 le conserve dans le chemin HTTP, pour les anciens serveurs.

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.

Exemples

La version 2 est utilisée sauf si v=1 est indiqué. Le jeton reste dans l’URL du plugin apprise://, mais la version 2 l’envoie au serveur dans un en-tête plutôt que dans le chemin HTTP. Utilisez la version 1 avec un ancien serveur Apprise API :

apprise --body="Message de Test" \
   "apprise://apprise.server.local/token?v=1"

Sans Authentification

Envoyez une notification à un serveur API Apprise à l’écoute sur le port 80 :

# Supposons que notre {hostname} soit apprise.server.local
# Supposons que notre {token} soit token
apprise -vv --body="Message de Test" \
   "apprise://apprise.server.local/token"

Avec Authentification

Placez le nom d’utilisateur et le mot de passe enregistrés avant le nom d’hôte. Une connexion administrateur avec mot de passe uniquement commence par deux-points. La version 2 envoie automatiquement la clé de configuration dans X-Apprise-Config-ID.

# Connexion de configuration avec nom d'utilisateur et mot de passe
apprise -vv --body="Message de Test" \
   "apprises://user:password@apprise.server.local/token"

# Connexion administrateur avec mot de passe uniquement
apprise -vv --body="Message de Test" \
   "apprises://:password@apprise.server.local/token"

Vous pouvez aussi sélectionner les services par tag :

# Supposons que notre {hostname} soit apprise.server.local
# Supposons que notre {token} soit token
# Envoyer aux services associés au {tag} email
apprise -vv --body="Message de Test" \
   "apprise://apprise.server.local/token?tags=email"

Les tags prennent en charge les expressions ET et OU :

Valeur tags=	Services sélectionnés
TagA	Possède TagA
TagA TagB	Possède TagA ET TagB
TagA+TagB	Possède TagA ET TagB
TagA&TagB	Possède TagA ET TagB
TagA,TagB	Possède TagA OU TagB
TagA|TagB	Possède TagA OU TagB
TagA TagC,TagB	Possède (TagA ET TagC) OU TagB

# Exemple OU
apprise -vv --body="Message de Test" \
   "apprise://apprise.server.local/token?tags=devops,finance"

# Exemple ET
apprise -vv --body="Message de Test" \
   "apprise://apprise.server.local/token?tags=devops alerts"

# Exemple mixte : (comment ET create) OU admin
apprise -vv --body="Message de Test" \
   "apprise://apprise.server.local/token?tags=comment create,admin"

Formats des Messages

Ce service transmet votre message à un autre serveur Apprise, qui le met ensuite en forme pour ses propres services. Pour éviter de modifier votre message deux fois, le titre et le corps sont toujours transmis exactement tels que vous les avez écrits. Aucune conversion n’est faite en chemin.

• Lorsque vous indiquez à Apprise le format de votre message, ce format est transmis au serveur avec le message. L’outil en ligne de commande apprise le fait toujours : il utilise text, sauf si vous en choisissez un autre avec --input-format (ou -i).
• Lorsque le message n’a pas de format propre (par exemple un appel Python à notify() sans body_format), vous pouvez ajouter ?format= à l’URL (text, html ou markdown) pour indiquer au serveur dans quel format votre message est écrit. Le message lui-même est toujours envoyé sans modification.
• Si aucun des deux n’est défini, aucun format n’est transmis et le serveur utilise son propre format par défaut.

# Notre message est écrit en Markdown ; on l'indique au serveur
apprise -vv --input-format=markdown --body="**Le serveur** est de nouveau en ligne" \
   "apprise://apprise.server.local/token"

Manipulation des En-Têtes

Ajoutez un signe plus (+) devant un paramètre d’URL pour l’envoyer comme en-tête HTTP.

# L'exemple ci-dessous définit l'en-tête :
#    X-Token: abcdefg
#
# Supposons que notre {hostname} soit localhost
# Supposons que notre {port} soit 8080
# Supposons que notre {token} soit apprise
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "apprise://localhost:8080/apprise/?+X-Token=abcdefg"

# Pour plusieurs en-têtes, ajoutez plusieurs paramètres :
# L'exemple ci-dessous définit les en-têtes :
#    X-Token: abcdefg
#    X-Apprise: is great
#
# Supposons que notre {hostname} soit localhost
# Supposons que notre {port} soit 8080
# Supposons que notre {token} soit apprise
# Cet exemple utilise un chemin URL personnalisé pour l'API Apprise.
apprise -vv -t "Titre du Message de Test" -b "Corps du Message de Test" \
   "apprise://localhost:8080/path/apprise/?+X-Token=abcdefg&+X-Apprise=is%20great"

Remarque : l’option --config de la CLI et la classe AppriseConfig() peuvent aussi charger la configuration depuis un serveur API Apprise.

# Exemple de la CLI chargeant une configuration déjà enregistrée :
# Supposons que notre {hostname} soit localhost
# Supposons que notre {port} soit 8080
# Supposons que notre {token} soit apprise
apprise --body="test message" --config=http://localhost:8080/get/apprise

# Configuration distante authentifiée
apprise --body="test message" \
   --config="http://user:password@localhost:8080/get/apprise"