20 Módulos

Descripción general

Es posible mejorar la funcionalidad de la interfaz de Zabbix agregando módulos de terceros o desarrollando sus propios módulos sin necesidad de cambiar el código fuente de Zabbix.

Tenga en cuenta que el código del módulo se ejecutará con los mismos privilegios que el código fuente de Zabbix. Esto significa:

  • Los módulos de terceros pueden ser perjudiciales. Debe confiar en los módulos que instala;
  • Los errores en el código de un módulo de terceros pueden bloquear la interfaz. Si esto sucede, simplemente elimine el código del módulo de la interfaz. Tan pronto como recargue la interfaz de Zabbix, verá una nota que dice que algunos de los módulos están ausentes. Ir a administración del módulo (en AdministraciónGeneralMódulos) y haga clic en Escanear directorio nuevamente para eliminar módulos inexistentes de la base de datos.

Instalación

Lea siempre el manual de instalación de un módulo en particular. Se recomienda instalar nuevos módulos uno por uno para detectar fallos fácilmente.

Justo antes de instalar un módulo:

  • Asegúrese de haber descargado el módulo de una fuente confiable. La instalación de código dañino puede tener consecuencias, como la pérdida de datos. pérdida
  • Se pueden instalar diferentes versiones del mismo módulo (mismo ID) en paralelo, pero solo se puede habilitar una versión a la vez

Pasos para instalar un módulo:

  • Desempaquete su módulo dentro de su propia carpeta en la carpeta modules de la interfaz de Zabbix
  • Asegúrese de que la carpeta de su módulo contenga al menos el archivo manifest.json
  • Vaya a administración del módulo y haga clic en el botón Escanear directorio
  • El nuevo módulo aparecerá en la lista junto con su versión, autor, descripción y estado
  • Habilite el módulo haciendo clic en su estado

Solución de problemas:

|Problema|Solución| |---------|------------------------------------------------ -| |El módulo no apareció en la lista|Asegúrese de que el archivo manifest.json exista en la carpeta modules/your-module/ de la interfaz de Zabbix. Si es así, significa que el módulo no se adapta a la versión actual de Zabbix. Si el archivo manifest.json no existe, probablemente lo hayas descomprimido en el directorio equivocado.| |La interfaz falló|El código del módulo no es compatible con la versión actual de Zabbix o la configuración del servidor. Elimine los archivos del módulo y vuelva a cargar la interfaz. Verá un aviso de que algunos módulos están ausentes. Vaya a Administración de módulos y haga clic en Escanear directorio nuevamente para eliminar módulos inexistentes de la base de datos.| |Aparece un mensaje de error sobre un espacio de nombres, ID o acciones idénticos|Un nuevo módulo intentó registrar un espacio de nombres, ID o acciones que ya están registrados por otros módulos habilitados. Deshabilite el módulo en conflicto (mencionado en el mensaje de error) antes de habilitar el nuevo.| |Aparecen mensajes de error técnico|Reportar errores al desarrollador del módulo.|

Desarrollo de módulos

Los módulos están escritos en lenguaje PHP. Modelo-vista-controlador (MVC) Se prefiere el diseño de patrones de software, ya que también se utiliza en la interfaz Zabbix y facilitará el desarrollo. La tipificación estricta de PHP también es recomendada pero no obligatoria.

Tenga en cuenta que con los módulos puede agregar fácilmente nuevos elementos de menú y vistas y acciones respectivas a la interfaz de Zabbix. Actualmente no es posible registrar una nueva API o crear nuevas tablas de bases de datos a través de módulos.

Estructura del módulo

Cada módulo es un directorio (ubicado dentro del directorio modules) con subdirectorios que contienen controladores, vistas y cualquier otro código:

example_module_directory/           (obligatorio)
           manifest.json                   (obligatorio)  Metadatos y definición de acción.
           Module.php                                  Inicialización del módulo y manejo de eventos.
           actions/                                    Archivos del controlador de acciones.
               SomethingView.php
               SomethingCreate.php
               SomethingDelete.php
               data_export/                                 
                   ExportAsXml.php
                   ExportAsExcel.php
           views/                                      Archivos de vista.
               example.something.view.php
               example.something.delete.php
               js/                                     Archivos JavaScript usados en vistas.
                   example.something.view.js.php
           partials/                                   Archivos parciales de vistas.
               example.something.reusable.php
               js/                                     Archivos JavaScript usados en los parciales.
                   example.something.reusable.js.php

Como puede ver, el único archivo obligatorio dentro del módulo personalizado El directorio es manifest.json. El módulo no se registrará sin esto. archivo. Module.php es responsable de registrar los elementos del menú y procesar eventos como 'onBeforeAction' y 'onTerminate'. El Los directorios actions, views y partials contienen PHP y JavaScript código necesario para las acciones del módulo.

Convenio de denominación

Antes de crear un módulo, es importante acordar la convención de los nombres para diferentes elementos del módulo, como directorios y archivos, de forma que podamos mantener las cosas bien organizadas. También puede encontrar ejemplos arriba, en la sección Estructura del módulo.

Elemento Reglas de nomenclatura Ejemplo
Directorio del módulo minúsculas [a-z], guión bajo y dígitos decimales ejemplo_v2
Subdirectorios de acciones Minúsculas [a-z] y carácter de subrayado datos_export
Archivos de acción CamelCase, que termina con el tipo de acción SomethingView.php
Vista y archivos parciales [a-z] en minúscula
Palabras separadas por un punto
Con el prefijo módulo. seguido del nombre del módulo
Terminando con el tipo de acción y la extensión de archivo .php
módulo.ejemplo .algo.vista.php
Archivos Javascript Se aplican las mismas reglas que para los archivos de vista y parciales, excepto la extensión de archivo .js.php. module.example.something.view.js.php

Tenga en cuenta que el prefijo 'module' y la inclusión del nombre son obligatorios para las vistas y los nombres de archivos parciales, a menos que necesite anular las vistas principales de Zabbix o los parciales. Sin embargo, esta regla no se aplica a los nombres de archivos de acciones.

Preparación del manifiesto

Se espera que cada módulo tenga un archivo manifest.json con los siguientes campos en formato JSON:

Parámetro Obligatorio Tipo Predeterminado Descripción
manifest_version Doble - Versión del manifiesto del módulo. La versión actualmente admitida es 1.
id Cadena - ID del módulo. Sólo se puede habilitar un módulo con ID determinado al mismo tiempo.
name Cadena - Nombre del módulo como se muestra en la sección Administración.
version Cadena - Versión del módulo como se muestra en la sección Administración.
namespace Cadena - Espacio de nombres PHP para Module.php y clases de acción.
author No Cadena "" Autor del módulo como se muestra en la sección Administración.
url No Cadena "" URL del módulo como se muestra en la sección Administración.
description No Cadena "" Descripción del módulo como se muestra en la sección Administración.
actions No Objeto {} Acciones para registrarse en este módulo. Ver Acciones.
config No Objeto {} Configuración del módulo.

Como referencia, consulte un ejemplo de manifest.json en la sección Referencia.

Acciones

El módulo tendrá control sobre las acciones de la interfaz definidas dentro del objeto actions en el archivo manifest.json. De esta manera se definen nuevas acciones. De la misma manera puede redefinir acciones existentes. Cada clave de las acciones debe representar el nombre de la acción y el valor correspondiente debe contener las claves class y, opcionalmente, layout y view.

Una acción está definida por cuatro contrapartes: nombre, controlador, vista y disposición. La validación y preparación de datos generalmente se realiza en el controlador, el formateo de salida se realiza en la vista o parciales, y el diseño se encarga de decorar la página con elementos como menú, encabezado, pie de página y otros.

Las acciones del módulo deben definirse en el archivo manifest.json como un objeto actions:

Parámetro Obligatorio Tipo Predeterminado Descripción
key Cadena - Nombre de la acción, en minúsculas [a-z], separando las palabras con punto.
class Cadena - Nombre de la clase de acción, incluida la ruta del subdirectorio (si se usa) dentro del directorio acciones.
layout No Cadena "layout.htmlpage" Diseño de acción.
view No Cadena nulo Vista de acción.

Hay varios diseños predefinidos, como layout.json o diseño.xml. Están destinados a acciones que producen diferentes resultados que un HTML. Puede explorar diseños predefinidos en el directorio app/views/ o incluso crea el suyo propio.

A veces es necesario redefinir solo la parte de vista de alguna acción dejando el controlador intacto. En tal caso simplemente coloque la vista necesaria y/o los archivos parciales dentro del directorio views del módulo.

Como referencia, consulte un archivo de controlador de acciones de ejemplo en la sección Referencia. Por favor no dudes en explorar Acciones actuales del código fuente de Zabbix, ubicadas en el directorio app/.

Module.php

Este archivo PHP opcional también es responsable de la inicialización del módulo. como manejo de eventos. Se espera que la clase 'Módulo' esté definida en este archivo, extendiendo la clase base \Core\CModule. La clase Módulo debe ser definido dentro del espacio de nombres especificado en el archivo manifest.json.

<?php
       
       namespace Modules\Example;
       use Core\CModule as BaseModule;
       
       class Module extends BaseModule {
           ...
       }

Como referencia, consulte un ejemplo de Module.php en la sección Referencia.

Referencia

Esta sección contiene versiones básicas de diferentes elementos del módulo.introducido en las secciones anteriores.

manifest.json

{
           "manifest_version": 1.0,
           "id": "example_module",
           "name": "Example module",
           "version": "1.0",
           "namespace": "Example",
           "author": "John Smith",
           "url": "http://module.example.com",
           "description": "Short description of the module.",
           "actions": {
               "example.something.view": {
                   "class": "SomethingView",
                   "view": "module.example.something.view"
               },
               "example.something.create": {
                   "class": "SomethingCreate",
                   "layout": null
               },
               "example.something.delete": {
                   "class": "SomethingDelete",
                   "layout": null
               },
               "example.something.export.xml": {
                   "class": "data_export/ExportAsXml",
                   "layout": null
               },
               "example.something.export.excel": {
                   "class": "data_export/ExportAsExcel",
                   "layout": null
               }
           },
           "config": {
               "username": "john_smith"
           }
       }

Module.php

<?php declare(strict_types = 1);
       
       namespace Modules\Example;
       
       use APP;
       use CController as CAction;
       
       /**
        * Please see Core\CModule class for additional reference.
        */
       class Module extends \Core\CModule {
       
           /**
            * Initialize module.
            */
           public function init(): void {
               // Initialize main menu (CMenu class instance).
               APP::Component()->get('menu.main')
                   ->findOrAdd(_('Reports'))
                       ->getSubmenu()
                           ->add((new \CMenuItem(_('Example wide report')))
                               ->setAction('example.report.wide.php')
                           )
                           ->add((new \CMenuItem(_('Example narrow report')))
                               ->setAction('example.report.narrow.php')
                           );
           }
       
           /**
            * Event handler, triggered before executing the action.
            *
            * @param CAction $action  Action instance responsible for current request.
            */
           public function onBeforeAction(CAction $action): void {
           }
       
           /**
            * Event handler, triggered on application exit.
            *
            * @param CAction $action  Action instance responsible for current request.
            */
           public function onTerminate(CAction $action): void {
           }
       }

Action controller

<?php declare(strict_types = 1);
       
       namespace Modules\Example\Actions;
       
       use CControllerResponseData;
       use CControllerResponseFatal;
       use CController as CAction;
       
       /**
        * Example module action.
        */
       class SomethingView extends CAction {
       
           /**
            * Initialize action. Method called by Zabbix core.
            *
            * @return void
            */
           public function init(): void {
               /**
                * Disable SID (Session ID) validation. Session ID validation should only be used for actions which involve data
                * modification, such as update or delete actions. In such case Session ID must be presented in the URL, so that
                * the URL would expire as soon as the session expired.
                */
               $this->disableSIDvalidation();
           }
       
           /**
            * Check and sanitize user input parameters. Method called by Zabbix core. Execution stops if false is returned.
            *
            * @return bool true on success, false on error.
            */
           protected function checkInput(): bool {
               $fields = [
                   'name'  => 'required|string',
                   'email' => 'required|string',
                   'phone' => 'string'
               ];
       
               // Only validated data will further be available using $this->hasInput() and $this->getInput().
               $ret = $this->validateInput($fields);
       
               if (!$ret) {
                   $this->setResponse(new CControllerResponseFatal());
               }
       
               return $ret;
           }
       
           /**
            * Check if the user has permission to execute this action. Method called by Zabbix core.
            * Execution stops if false is returned.
            *
            * @return bool
            */
           protected function checkPermissions(): bool {
               $permit_user_types = [USER_TYPE_ZABBIX_ADMIN, USER_TYPE_SUPER_ADMIN];
       
               return in_array($this->getUserType(), $permit_user_types);
           }
       
           /**
            * Prepare the response object for the view. Method called by Zabbix core.
            *
            * @return void
            */
           protected function doAction(): void {
               $contacts = $this->getInput('email');
       
               if ($this->hasInput('phone')) {
                   $contacts .= ', '.$this->getInput('phone');
               }
       
               $data = [
                   'name' => $this->getInput('name'),
                   'contacts' => $contacts
               ];
       
               $response = new CControllerResponseData($data);
       
               $this->setResponse($response);
           }
       }

Action view

<?php declare(strict_types = 1);
       
       /**
        * @var CView $this
        */
       
       $this->includeJsFile('example.something.view.js.php');
       
       (new CWidget())
           ->setTitle(_('Something view'))
           ->addItem(new CDiv($data['name']))
           ->addItem(new CPartial('module.example.something.reusable', [
               'contacts' => $data['contacts']
           ])
           ->show();