Botón

Un elemento que se puede tocar en el menú de Telegram. Tiene un name y, al tocarlo, ejecuta una función en el servidor y devuelve el resultado al chat.

Los botones y las categorías forman el árbol del menú bajo la clave raíz menu del archivo de configuración. Un botón realiza una acción; una categoría solo abre un submenú.

Aspecto de un botón

Los botones aparecen en el teclado bajo el cuadro de mensajes, dos por fila de forma predeterminada. El nombre que elija será el texto de la tecla, así que procure que sea suficientemente breve para leerlo en un teléfono. Consulte Menú → Aspecto del menú.

Partes de un botón

Cada línea controla una parte del botón

Un botón con todas sus partes

- name: Restart nginx # (1)!
  type: button # (2)!
  icon: "🔄" # (3)!
  function: command # (4)!
  command: "systemctl restart nginx" # (5)!
  confirm: true # (6)!

1. El texto de la tecla en Telegram. Debe ser único entre los elementos vecinos del mismo menú.
2. Aquí siempre se usa button. Use category si quiere un submenú.
3. Emoji opcional que aparece antes del nombre. Es solo decorativo y no cambia lo que se ejecuta.
4. La función que se usará. command es la función integrada que ejecuta un comando de shell.
5. Lo que ejecuta la función command. Puede escribir aquí cualquier comando válido en una terminal.
6. Es opcional. Pregunta «¿Está seguro?» antes de ejecutar. Omítalo para acciones que solo consultan información.

Qué ocurre al tocarlo

1. El bot publica una breve línea Running para indicar que ha empezado.
2. El comando se ejecuta en la máquina donde funciona el bot.
3. La salida vuelve como bloque de código, con el código de salida y la duración. Una salida corta se queda en el chat como uno o varios mensajes; una salida más larga puede llegar como archivo .txt (consulte Resultados largos como archivo).
4. Usted permanece en el mismo menú, por lo que Atrás sigue saliendo de esa categoría.

Botones habituales

Comprobar algoGestionar un servicioLeer un registroEjecutar un scriptAlgo destructivo

Botón Uptime

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

Botón Restart nginx

- name: Restart nginx
  type: button
  icon: "🔄"
  function: command
  command: "systemctl restart nginx"

Botón Nginx log

- name: Nginx log
  type: button
  function: command
  command: "journalctl -u nginx -n 50 --no-pager"

Botón Nightly backup

- name: Nightly backup
  type: button
  function: script
  path: "/usr/local/bin/backup.sh"

Botón Stop nginx

- name: Stop nginx
  type: button
  icon: "🛑"
  function: command
  command: "systemctl stop nginx"
  confirm: true

Iconos

icon antepone un emoji al nombre. Es solo decorativo y se puede cambiar sin alterar lo que ejecuta el botón.

Un icono solo cambia la etiqueta

El mismo botón, con y sin icono

- name: Disk usage
  type: button
  function: command
  command: "df -h"

- name: Disk usage
  type: button
  icon: "💾"
  function: command
  command: "df -h"

Preguntar antes de acciones peligrosas

Añada confirm: true y el bot mostrará primero Sí o Cancelar. Úselo para cualquier acción que detenga un servicio, elimine datos o reinicie la máquina. La pregunta caduca tras un tiempo, cinco minutos de forma predeterminada.

Lea Confirmación para saber cuándo usarla y cambiar la espera.

Ajustes exclusivos de un botón

La mayoría de los ajustes globales se pueden sustituir en un solo botón, lo que resulta útil cuando una tarea se comporta de forma distinta a las demás:

Sustituir ajustes para una tarea lenta

Una tarea lenta que se ejecuta en otro lugar

- name: Long backup
  type: button
  function: command
  command: "/usr/local/bin/backup.sh"
  timeout: "10m"
  workdir: "/var/backups"
  env:
    BACKUP_MODE: "full"

timeout concede más tiempo a este comando, workdir elige el directorio donde se ejecuta y env añade variables de entorno solo para él.

Resultados largos como archivo

No hace falta output en un botón. Si lo omite, el botón usa el ajuste de la raíz (auto salvo que lo haya cambiado): un resultado corto se queda como mensajes de chat, y uno que necesitaría más de dos mensajes llega como un archivo .txt. Ponga output solo cuando ese botón deba enviar siempre un archivo o quedarse siempre en texto. max_output_messages no se puede poner en un botón.

Ponga output: file en un botón que siempre imprime mucho (por ejemplo registros), u output: text para conservar el comportamiento antiguo solo en ese botón.

Las claves raíz output y max_output_messages están documentadas en Configuración → Cuánta salida de comando verá. Controlar la salida recorre todas las combinaciones de raíz y botón con un ejemplo cada una.

Valores para la función

Escriba los valores de la función directamente en el botón. command, path y args son atajos para parámetros del mismo nombre. Los nombres personalizados, como url, host, unit y lines, funcionan igual.

Pasar valores personalizados

Registros recientes de Nginx

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

No coloque estos valores dentro de un mapa params:. Cada clave debe coincidir con un parámetro declarado por la función seleccionada. validate detecta nombres desconocidos, valores obligatorios ausentes y valores int o bool inválidos.

Configuración

Para todos los campos admitidos, consulte Configuración → Menú.

Relacionado

• Categoría

  ---

  Abre un submenú en vez de ejecutar algo.

  Categoría

• Función

  ---

  Lo que se ejecuta al tocar un botón.

  Función

• Parámetro

  ---

  Valores que necesita una función y que proporciona el botón.

  Parámetro

• Menú

  ---

  Cree y organice todo el árbol.

  Menú

• Controlar la salida

  ---

  Mensajes o un archivo .txt, y cómo un botón sustituye a la raíz.

  Controlar la salida