Qu’est-ce qu’une fonction ?

Une fonction est une recette qui transforme des valeurs nommées, ses paramètres, en commande shell. Chaque bouton de votre menu nomme exactement une fonction dans son champ function.

Imaginez une fonction comme une commande à compléter. Une fonction d’utilisation du disque possède un emplacement vide, le chemin, que chaque bouton remplit.

Que se passe-t-il lorsque vous appuyez sur un bouton ?

1. Le bot recherche la fonction indiquée dans le champ function du bouton.
2. Il collecte les valeurs écrites sur ce bouton.
3. Il construit une commande shell avec ces valeurs.
4. Il exécute la commande dans le shell et renvoie la sortie dans la conversation sous forme de bloc de code.

Si la fonction n’existe pas ou qu’une valeur obligatoire manque, le bot ne démarre pas : validate signale d’abord le problème.

Exemple détaillé

La fonction command est intégrée et toujours disponible. Elle exécute la valeur du champ command du bouton.

Utiliser la fonction intégrée command

Bouton Uptime

- name: Uptime
  type: button
  function: command
  command: "uptime"

Appuyez sur Uptime : le bot exécute uptime sur le serveur et renvoie la sortie.

Transmettre des valeurs depuis un bouton

Écrivez chaque valeur directement sur le bouton. Deux méthodes sont possibles :

1. Utilisez les champs raccourcis command, path et args. Chacun remplit le paramètre portant le même nom.
2. Pour tout autre paramètre, utilisez son nom comme clé du bouton.

Transmettre une URL avec son nom de paramètre

Bouton de vérification de l’API

- name: Check API
  type: button
  function: curl-url
  url: "https://example.com/health"

Ici, url correspond au paramètre url déclaré par curl-url. La même règle s’applique à host, unit et lines.

Ne placez pas les valeurs dans params:

params: appartient au fichier d’une fonction personnalisée, où il déclare les valeurs acceptées. Sur un bouton, écrivez chaque valeur directement :

Les valeurs se placent directement sur le bouton

- name: Nginx logs
  type: button
  function: journal-unit
  unit: "nginx.service"
  lines: 100

Les valeurs YAML numériques n’ont pas besoin de guillemets.

validate compare chaque clé aux paramètres déclarés par la fonction. Une faute ou un nom non déclaré fait échouer la validation. Les valeurs int et bool sont aussi vérifiées. Les valeurs facultatives utilisent leur valeur par défaut si le bouton les omet.

Deux types de fonction

Les fonctions sont fournies dans le programme ou proviennent d’un fichier YAML sur votre serveur. Une fois utilisées par un bouton, elles se comportent de la même manière.

	Intégrée	Personnalisée
Origine	Fournie dans le programme	Un fichier YAML que vous écrivez
Fichier à créer ?	Non	Oui, un fichier par fonction
Noms	Réservés (command, script)	Tout nom non réservé
Toujours disponible ?	Oui	Seulement avec function_directory
Modifiable ?	Non	Oui, ce sont vos fichiers

Vous pouvez mélanger les deux types dans un menu. Commencez avec des boutons command, puis créez des fonctions personnalisées lorsque vous répétez une commande en ne changeant qu’une petite partie.

Fonctions intégrées

Deux fonctions sont toujours chargées, même sans function_directory. Leurs champs command, path et args sont placés directement sur le bouton.

Fonction	Action	Obligatoire	Facultatif
command	Exécute une commande shell telle quelle	command	—
script	Exécute un script avec des arguments	path	args

Les deux noms sont réservés. Une fonction personnalisée ne peut pas les réutiliser : le chargeur s’arrête avec une erreur comme function name "command" is reserved.

Fonctions personnalisées

Une fonction personnalisée est un fichier YAML décrivant une commande réutilisable. Placez ces fichiers dans votre dossier et indiquez-le avec function_directory.

Indiquer le dossier contenant les fonctions

config.yaml

function_directory: "./functions"

Au démarrage, le bot lit ce dossier et ses sous-dossiers, puis charge tous les fichiers .yaml et .yml. Les autres fichiers sont ignorés.

L’archive de la version contient déjà un dossier functions/ avec cinq exemples :

Fonction	Action	Valeurs du bouton
Script d’écho	Exécute un script avec Bash	path, args facultatif
Chemin du disque	Affiche l’utilisation du disque	path facultatif
URL Curl	Récupère une URL	url
Ping d’un hôte	Interroge un hôte	host, count facultatif
Unité du journal	Affiche les journaux récents d’un service	unit, lines facultatif

Pour écrire la vôtre, commencez par la Structure des fichiers ou suivez le guide pas à pas.

Vérifier les fonctions chargées

Lister toutes les fonctions visibles par le bot

./telegram-commander list-functions --config config.yaml

Les fonctions intégrées affichent source=builtin ; les fonctions personnalisées affichent leur fichier d’origine.

Consignes de sécurité

Les boutons s’exécutent avec les droits du bot

Les commandes disposent des droits du compte qui exécute le bot. Si c’est root, comme dans la configuration de service par défaut, les boutons peuvent tout faire sur l’hôte. N’ajoutez que des utilisateurs autorisés de confiance.

Les paramètres sont insérés comme texte. Traitez-les comme des entrées shell : préférez des valeurs fixes et ajoutez confirm: true aux actions destructrices.

La sortie est d’abord conservée, puis livrée

Les commandes s’arrêtent à leur timeout et le bot conserve au plus max_output_bytes de leur sortie. Ce qui arrive ensuite dans la conversation, plusieurs messages ou un seul fichier .txt, est décidé par output. Consultez Contrôler la sortie.

Pages associées

• command — exécuter une commande shell
• script — exécuter un fichier de script
• Guide pas à pas — créer votre première fonction
• Menu — comment les boutons référencent les fonctions
• Paramètre — les valeurs nommées d’une fonction
• Contrôler la sortie — comment le résultat arrive dans la conversation