Esta é uma tradução da página de documentação original em inglês. Ajude-nos a torná-la melhor.

20. Módulos

Visão geral

É possível melhorar a funcionalidade do frontend do Zabbix adicionando 3º módulos do partido ou desenvolvendo seus próprios módulos sem a necessidade de alterar o código fonte do Zabbix.

Observe que o código do módulo será executado com os mesmos privilégios do Zabbix Código fonte. Isso significa:

  • Módulos de terceiros podem ser prejudiciais. Você deve confiar nos módulos que você está instalação;
  • Erros em um código de módulo de terceiros podem travar o frontend. Se este acontece, basta remover o código do módulo do frontend. Assim que você recarregar o frontend do Zabbix, você verá uma nota dizendo que alguns módulos estão ausentes. Vá para Módulo administração (em AdministraçãoGeralMódulos) e clique em Digitalizar directory novamente para remover módulos inexistentes do banco de dados.

Instalação

Por favor, leia sempre o manual de instalação de um módulo específico. Isto é recomendado instalar novos módulos um por um para detectar falhas facilmente.

Pouco antes de instalar um módulo:

  • Certifique-se de ter baixado o módulo de uma fonte confiável. A instalação de código nocivo pode levar a consequências, como dados perda
  • Diferentes versões do mesmo módulo (mesmo ID) podem ser instaladas em paralelo, mas apenas uma única versão pode ser habilitada por vez

Etapas para instalar um módulo:

  • Descompacte seu módulo dentro de sua própria pasta na pasta modules do a interface do Zabbix
  • Certifique-se de que a pasta do módulo contenha pelo menos o manifest.json Arquivo
  • Navegue até Módulo administração e clique no botão Digitalizar diretório
  • Novo módulo aparecerá na lista junto com sua versão, autor, descrição e estado
  • Habilite o módulo clicando em seu status

Solução de problemas:

Problema Solução
O módulo não apareceu na lista Certifique-se de que o arquivo manifest.json existe na pasta modules/your-module/ do frontend do Zabbix. Se isso acontecer, significa que o módulo não é compatível com a versão atual do Zabbix. Se o arquivo manifest.json não existir, você provavelmente descompactou no diretório errado.
Frontend travado O código do módulo não é compatível com a versão atual do Zabbix ou configuração do servidor. Por favor, exclua os arquivos do módulo e recarregue o frontend. Você verá um aviso de que alguns módulos estão ausentes. Vá para Module administration e clique em Scan directory novamente para remover módulos inexistentes do banco de dados.
Aparece uma mensagem de erro sobre namespace, ID ou ações idênticas Novo módulo tentou registrar um namespace, ID ou ações que já estão registradas por outros módulos habilitados. Desabilite o módulo conflitante (mencionado na mensagem de erro) antes de habilitar o novo.
Aparecem mensagens de erro técnico Relatar erros ao desenvolvedor do módulo.

Desenvolvendo módulos

Os módulos são escritos em linguagem PHP. Controlador de visualização de modelo (MVC) design de padrão de software é o preferido, pois também é usado no Zabbix frontend e facilitará o desenvolvimento. A tipagem estrita do PHP também é bem-vindo, mas não obrigatório.

Observe que com os módulos você pode adicionar facilmente novos itens de menu e respectivas visualizações e ações para o frontend do Zabbix. Atualmente não é possível registrar uma nova API ou criar novas tabelas de banco de dados através módulos.

Estrutura do módulo

Cada módulo é um diretório (colocado dentro do diretório modules) com subdiretórios contendo controllers, views e qualquer outro código:

example_module_directory/ (obrigatório)
           manifest.json (obrigatório) Metadados e definição de ação.
           Module.php Inicialização do módulo e manipulação de eventos.
           actions/Arquivos do controlador de ação.
               AlgoView.php
               AlgoCreate.php
               AlgoDelete.php
               data_export/
                   ExportAsXml.php
                   ExportAsExcel.php
           visualizações/Visualizar arquivos.
               exemplo.algo.view.php
               exemplo.algo.excluir.php
               js/ arquivos JavaScript usados ​​em views.
                   exemplo.algo.view.js.php
           parciais/ Visualizar arquivos parciais.
               exemplo.algo.reutilizável.php
               js/ arquivos JavaScript usados ​​em parciais.
                   exemplo.algo.reutilizável.js.php

Como você pode ver, o único arquivo obrigatório dentro do módulo personalizado diretório é manifest.json. O módulo não será registrado sem isso Arquivo. Module.php é responsável por registrar itens de menu e processamento de eventos como 'onBeforeAction' e 'onTerminate'. O Os diretórios actions, views e partials contêm PHP e JavaScript código necessário para ações do módulo.

Convenção de nomes

Antes de criar um módulo, é importante concordar com a nomenclatura convenção para diferentes itens de módulo, como diretórios e arquivos, que poderíamos manter as coisas bem organizadas. Você também pode encontrar exemplos acima, na seção Estrutura do módulo.

Item Regras de nomenclatura Exemplo
Diretório do módulo minúsculas [a-z], sublinhado e dígitos decimais exemplo_v2
Subdiretórios de ação minúsculas [a-z] e caractere de sublinhado dados_export
Arquivos de ação CamelCase, terminando com tipo de ação SomethingView.php
Visualização e arquivos parciais minúsculas [az]
Palavras separadas por ponto
Prefixado por module. seguido pelo nome do módulo
Terminando com tipo de ação e extensão de arquivo .php
module.example .algo.view.php
Arquivos Javascript As mesmas regras se aplicam aos arquivos de visualização e parciais, exceto a extensão de arquivo .js.php. module.example.something.view.js.php

Observe que o prefixo 'módulo' e a inclusão do nome são obrigatórios para visualização e nomes de arquivos parciais, a menos que você precise substituir as visualizações principais do Zabbix ou parciais. Essa regra, no entanto, não se aplica a nomes de arquivos de ação.

Preparação do manifesto

Espera-se que cada módulo tenha um arquivo manifest.json com o seguinte campos no formato JSON:

Parâmetro Requerido Tipo Padrão Descrição
manifest_version Yes Double - Versão de manifesto do módulo. A versão atualmente suportada é 1.
id Sim String - ID do módulo. Apenas um módulo com determinado ID pode ser habilitado ao mesmo tempo.
name Yes String - Nome do módulo conforme exibido na seção Administração.
versão Sim String - Versão do módulo conforme exibido na seção Administração.
namespace Yes String - PHP namespace para Module.php e classes de ação.
autor Não String "" Autor do módulo conforme exibido na seção Administração.
url No String "" URL do módulo conforme exibido na seção Administração.
description No String "" Descrição do módulo conforme exibido na seção Administração.
actions No Object {} Ações para registrar com este módulo. Consulte Ações.
config No Object {} Configuração do módulo.

Para referência, veja um exemplo de manifest.json no seção Reference.

Ações

O módulo terá controle sobre as ações de frontend definidas dentro do actions no arquivo manifest.json. Desta forma, novas ações são definiram. Da mesma forma, você pode redefinir as ações existentes. Cada chave de actions devem representar o nome da ação e o valor correspondente deve conter as chaves class e opcionalmente layout e view.

Uma ação é definida por quatro contrapartes: nome, controlador, visão e disposição. A validação e a preparação dos dados geralmente são feitas no controlador, a formatação de saída é feita na visão ou parciais, e o layout é responsável por decorar a página com elementos como menu, cabeçalho, rodapé e outros.

As ações do módulo devem ser definidas no arquivo manifest.json como actions objeto:

Parâmetro Requerido Tipo Padrão Descrição
*chave* Sim String - Nome da ação, em letras minúsculas [a-z], separando palavras com ponto.
class Yes String - Nome da classe de ação, incluindo o caminho do subdiretório (se usado) dentro do diretório actions.
layout Não String "layout.htmlpage" Layout da ação.
view No String null Visualização de ação.

Existem vários layouts predefinidos, como layout.json ou layout.xml. Estes destinam-se a ações que produzem diferentes resultado do que um HTML. Você pode explorar layouts predefinidos no app/views/ diretório ou até mesmo criar o seu próprio.

Às vezes é necessário apenas redefinir a visão parte de alguma ação deixando o controlador intacto. Nesse caso, basta colocar o necessário view e/ou arquivos parciais dentro do diretório views do módulo.

Para referência, consulte um exemplo de arquivo de controlador de ação no seção Reference. Por favor, não hesite em explorar ações atuais do código fonte do Zabbix, localizadas no diretório app/.

Módulo.php

Este arquivo PHP opcional também é responsável pela inicialização do módulo como tratamento de eventos. Espera-se que a classe 'Módulo' seja definida neste arquivo, estendendo a classe base \Core\CModule. A classe Módulo deve ser definido no namespace especificado no arquivo manifest.json.

<?php
       
       Módulos de namespace\Exemplo;
       use Core\CModule como BaseModule;
       
       class Module estende BaseModule {
           ...
       }

Para referência, veja um exemplo de Module.php no seção Reference.

Referência

Esta seção contém versões básicas de diferentes elementos do módulo introduzido nas seções 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"
           }
       }

Módulo.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 {
           }
       }

Controlador de ação

<?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);
           }
       }

Visualização de ação

<?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();