Formatage

Apprise peut envoyer du texte brut, du Markdown et du HTML, puis adapter ce que vous transmettez à ce que chaque service peut réellement accepter. Par exemple, un service qui ne prend en charge que du texte recevra tout de même votre notification, mais tout format enrichi sera réduit de manière appropriée.

Formats de Message

Apprise ne devine pas automatiquement votre type de contenu. À la place, vous lui indiquez le type de contenu fourni, et Apprise utilise cette information pour prendre des décisions intelligentes, service par service.

Apprise reconnaît quatre états de format d’entrée :

État	Description
(implicite) none	Aucun format source déclaré. La conversion automatique est ignorée.
text	Entrée en texte brut. Apprise peut simplifier le contenu pour les services texte uniquement.
markdown	Entrée en Markdown. Apprise peut convertir ou simplifier selon le besoin.
html	Entrée en HTML. Apprise peut supprimer ou convertir le balisage si nécessaire.

En bref : Apprise préserve votre contenu autant que possible et ne l’adapte que lorsqu’une destination ne peut pas prendre en charge ce que vous avez fourni.

Déclarer l’Entrée vs Transformer la Sortie

Lorsque vous spécifiez un format (comme text, markdown ou html), vous décrivez votre entrée, vous ne forcez pas un format de sortie particulier.

Apprise utilise cette information pour déterminer si une transformation est nécessaire pour une destination donnée.

Si le service de destination prend nativement en charge le format déclaré, le contenu est transmis tel quel
Si la destination ne peut pas prendre en charge le format déclaré, Apprise effectue la conversion minimale nécessaire
Si aucune conversion n’est requise, aucune transformation n’a lieu

Autrement dit, Apprise n’intervient que lorsqu’il existe un décalage entre le format d’entrée déclaré et ce que le fournisseur amont peut gérer. Cela n’est possible que si vous avez fourni un format d’entrée à exploiter.

Par exemple :

Un message HTML envoyé par email peut être remis sous forme de HTML enrichi
Le même HTML envoyé par SMS sera converti en texte brut lisible
Un message Markdown envoyé à un service de discussion peut conserver sa mise en forme
Ce même Markdown envoyé à un service texte uniquement sera automatiquement simplifié

Cela rend les destinations plus compatibles sans vous obliger à adapter manuellement le contenu pour chaque service.

Que se Passe-t-il si Vous ne Précisez Aucun Format ?

Si vous ne précisez pas de format, Apprise suppose des états légèrement différents selon le composant utilisé :

Interface	Format d’entrée par défaut
CLI	`text`
Python API	`none` - aucune conversion automatique sauf si `body_format` est fourni dans `notify()` ou défini dans `AppriseAsset()`
Apprise-API	`none` - aucune conversion automatique sauf si la requête fournit `format`, ou si l’opérateur du serveur définit `APPRISE_DEFAULT_FORMAT`

Le formatage sur l’Apprise-API est entièrement optionnel, requête par requête. Si vous gérez votre propre serveur Apprise-API et souhaitez que chaque requête omettant format en suppose un automatiquement, définissez la variable d’environnement APPRISE_DEFAULT_FORMAT (par exemple APPRISE_DEFAULT_FORMAT=text) — consultez la référence des variables d’environnement pour plus de détails. Les appelants peuvent toujours passer outre requête par requête : fournir une vraie valeur format l’emporte toujours, tout comme le fait de l’envoyer volontairement vide ou null — ce qui est interprété comme une demande explicite de ne rien formater, même si vous avez défini une valeur par défaut à l’échelle du serveur.

À l’exception du CLI, si aucun format d’entrée n’est précisé, Apprise ignore la conversion automatique et la réparation du balisage. La destination décide encore comment afficher le contenu. Par exemple, ?format=html indique à un service compatible HTML que le corps est déjà prêt à l’emploi.

Les limites de message, la gestion du dépassement, l’encodage, l’échappement, l’emballage JSON et le chiffrement peuvent toujours modifier la charge utile finale. Le mode pass-through signifie donc « ne pas interpréter mon format source », et non « envoyer exactement ces octets ».

Pass-Through et Dépassement

Le réglage overflow de l’URL s’applique même si aucun format d’entrée n’est déclaré :

upstream envoie un seul message sans le découper ni le tronquer selon la limite documentée du service ;
truncate conserve la partie qui tient dans la limite et supprime le reste ;
split privilégie les coupures lisibles comme les retours à la ligne ou les espaces, puis utilise une coupure stricte si nécessaire et envoie toutes les parties dans l’ordre.

Avec un format source inconnu, le découpage reste une solution au mieux. Apprise ne peut pas réparer de manière fiable du HTML, du Markdown, du JSON, du texte chiffré, une signature ou un autre contenu structuré qu’il ne doit pas interpréter. Utilisez overflow=upstream si le message doit rester intact, ou déclarez son format pour obtenir un traitement adapté.

Déclarer le bon format d’entrée est facultatif, mais cela permet à Apprise d’aider plus efficacement sur des destinations mixtes.

Exemples CLI

Utilisez --input-format pour indiquer à Apprise comment interpréter le contenu du corps du message.

# Corps en Markdown
apprise -t "Publication" -b "**v1.2.3** est maintenant en ligne" \
  --input-format=markdown \
  "discord://..."

# Corps en HTML
apprise -t "Rapport de build" -b "<b>Succès</b> : artefacts téléversés" \
  --input-format=html \
  "mailto://user:pass@example.com"

Exemples pour la Bibliothèque Python

Utilisez body_format pour préciser le format du message que vous fournissez.

from apprise import Apprise
from apprise import NotifyFormat

apobj = Apprise()
apobj.add("discord://...")

# Entrée Markdown
apobj.notify(
    title="Statut",
    body="**Tous les contrôles sont passés**",
    body_format=NotifyFormat.MARKDOWN,
)

# Entrée HTML
apobj.notify(
    title="Rapport de build",
    body="<b>Succès</b> : artefacts téléversés",
    body_format=NotifyFormat.HTML,
)

Exemples Apprise-API

Pour les charges utiles JSON, utilisez le champ format :

# Exemple sans état
curl -X POST http://localhost:8000/notify/ \
  -d 'urls=["discord://..."]' \
  -d 'title=Statut' \
  -d 'body=**Tous les contrôles sont passés**' \
  -d 'format=markdown'

# Exemple avec état
curl -X POST http://localhost:8000/notify/team-alerts/\
  -d 'tags=outage' \
  -d 'type=failure' \
  -d 'title=Rapport d''incident' \
  -d 'body=<strong>Le serveur de fichiers ne répond plus</strong>' \
  -d 'format=html'

Si vous utilisez déjà Apprise, envisagez simplement d’utiliser le service API Apprise pour simplifier les requêtes avec état :

# --config= vous permet de pointer vers une API Apprise amont pour votre
# configuration.
apprise --config=http://localhost:8000/cfg/team-alerts/ \
  --tag=outage \
  --input-format=html \
  --notification-type=failure \
  --title "Rapport d'incident" \
  --body "<strong>Le serveur de fichiers ne répond plus</strong>"

Vous pouvez placer l’URL de configuration de votre API Apprise dans l’un des emplacements par défaut utilisés par la CLI Apprise. Un serveur avec APPRISE_CONFIG_LOCK=yes exige les identifiants de l’administrateur global :

include http://localhost:8000/cfg/team-alerts/

Votre commande CLI devient alors beaucoup plus simple :

apprise --tag=outage --input-format=html --notification-type=failure \
  --title "Rapport d'incident" \
  --body "<strong>Le serveur de fichiers ne répond plus</strong>"

Sélectionner un Format de Sortie (Diffusion Amont)

En plus de déclarer le format d’entrée, certains services vous permettent de choisir la manière dont le contenu est livré en amont en précisant un paramètre format= directement dans l’URL du service.

Cela ne décrit pas l’entrée que vous fournissez. Cela indique plutôt au plugin de service quelle route de diffusion ou quelle représentation utiliser, si elle est prise en charge.

Comment les Formats d’Entrée et de Sortie Fonctionnent Ensemble

Format d’entrée (body_format, --input-format, API format)
Indique à Apprise quel type de contenu vous fournissez
Format de sortie (?format= dans une URL de service)
Indique au plugin de service comment livrer ce contenu au fournisseur amont

Lorsque les deux sont précisés, Apprise adapte correctement le contenu si nécessaire avant de le transmettre à la route de diffusion amont sélectionnée.

Si le service amont ne prend pas en charge le format de sortie demandé, la demande est ignorée (un avertissement est journalisé) et le comportement par défaut du service est utilisé à la place.

Exemples

Email

L’email prend en charge plusieurs formats de diffusion.

# Comportement par défaut (email HTML)
mailto://user:pass@example.com

# Forcer une diffusion en texte brut
mailto://user:pass@example.com?format=text

Dans ce cas :

format=html est inutile car le HTML est le comportement par défaut
format=text sélectionne explicitement la voie de diffusion en texte brut
format=markdown est ignoré car l’email ne prend pas en charge la diffusion Markdown

Services avec Plusieurs Points de Terminaison

Certains services exposent plusieurs endpoints API selon la prise en charge du format.

Dans ces cas, définir format= peut :

sélectionner un endpoint amont différent ;
modifier la manière dont le contenu est rendu par le service ;
contourner complètement les transformations de format.

Ce comportement est spécifique au plugin et ne s’applique que lorsque le service prend explicitement en charge plusieurs formats de sortie.

Cas d’Usage

Préciser un format de sortie est utile si :

vous voulez imposer un type de diffusion spécifique (par exemple un email en texte brut) ;
le service prend en charge plusieurs représentations du contenu ;
vous envoyez du contenu tel quel et devez le faire passer par un chemin amont précis.

Si un service ne prend pas en charge le format de sortie demandé, Apprise revient en toute sécurité au comportement par défaut.

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 :