This is a translation of the original English documentation page. Help us make it better.

20. Moduli

Panoramica

È possibile migliorare la funzionalità del frontend di Zabbix aggiungendo moduli di terze parti o sviluppando i propri moduli senza la necessità di modificare il codice sorgente di Zabbix.

Si noti che il codice del modulo verrà eseguito con gli stessi privilegi di Zabbix codice sorgente. Questo significa:

  • i moduli di terze parti possono essere dannosi. Devi fidarti dei moduli che sei installazione;
  • Gli errori nel codice di un modulo di terze parti possono causare l'arresto anomalo del frontend. Se questo accade, basta rimuovere il codice del modulo dal frontend. Non appena ricarichi il frontend di Zabbix, vedrai una nota che dice che alcuni i moduli sono assenti. Vai a Modulo amministrazione (in AmministrazioneGeneraleModuli) e fare clic su Scansione directory di nuovo per rimuovere i moduli inesistenti dal database.

Installazione

Si prega di leggere sempre il manuale di installazione per un particolare modulo. Esso si consiglia di installare i nuovi moduli uno per uno per rilevare i guasti facilmente.

Appena prima di installare un modulo:

  • Assicurati di aver scaricato il modulo da una fonte attendibile. L'installazione di codice dannoso può portare a conseguenze, come i dati perdita
  • È possibile installare diverse versioni dello stesso modulo (stesso ID). parallel, ma è possibile abilitare una sola versione alla volta

Passaggi per installare un modulo:

  • Scompattare il modulo all'interno della propria cartella nella cartella modules di il front-end di Zabbix
  • Assicurati che la cartella del modulo contenga almeno manifest.json file
  • Passare a Modulo amministrazione e fare clic sul pulsante Scansiona directory
  • Il nuovo modulo apparirà nell'elenco insieme alla sua versione, autore, descrizione e stato
  • Abilitare il modulo cliccando sul suo stato

Risoluzione dei problemi:

|Problema|Soluzione| |---------|--------------------------------------- -| |Il modulo non è apparso nell'elenco|Assicurati che il file manifest.json esista nella cartella modules/your-module/ del frontend Zabbix. In tal caso, significa che il modulo non è adatto all'attuale versione di Zabbix. Se il file manifest.json non esiste, probabilmente hai decompresso nella directory sbagliata.| |Frontend crashato|Il codice del modulo non è compatibile con l'attuale versione di Zabbix o con la configurazione del server. Elimina i file del modulo e ricarica il frontend. Vedrai un avviso che alcuni moduli sono assenti. Vai a Amministrazione del modulo e fai di nuovo clic su Scansiona directory per rimuovere i moduli inesistenti dal database.| |Viene visualizzato un messaggio di errore su namespace, ID o azioni identici|Un nuovo modulo ha provato a registrare un namespace, ID o azioni che sono già registrati da altri moduli abilitati. Disabilita il modulo in conflitto (menzionato nel messaggio di errore) prima di abilitare quello nuovo.| |Compaiono messaggi di errore tecnico|Segnala gli errori allo sviluppatore del modulo.|

Sviluppo di moduli

I moduli sono scritti in linguaggio PHP. Model-view-controller (MVC) è preferito il design del modello software, poiché viene utilizzato anche in Zabbix frontend e faciliterà lo sviluppo. Anche la tipizzazione rigorosa di PHP è benvenuto ma non obbligatorio.

Si noti che con i moduli è possibile aggiungere facilmente nuove voci di menu e rispettive visualizzazioni e azioni al frontend di Zabbix. Attualmente non lo è possibile registrare nuove API o creare nuove tabelle di database tramite moduli.

Struttura del modulo

Ogni modulo è una directory (posizionata all'interno della directory modules) con sottodirectory contenenti controller, viste e qualsiasi altro codice:

example_module_directory/ (obbligatorio)
           manifest.json (obbligatorio) Metadati e definizione dell'azione.
           Module.php Inizializzazione del modulo e gestione degli eventi.
           azioni/File del controller di azione.
               QualcosaView.php
               QualcosaCreate.php
               QualcosaDelete.php
               esportazione_dati/
                   ExportAsXml.php
                   ExportAsExcel.php
           views/ Visualizza i file.
               esempio.qualcosa.view.php
               esempio.qualcosa.delete.php
               js/ JavaScript utilizzati nelle viste.
                   esempio.qualcosa.view.js.php
           partial/ Visualizza i file parziali.
               esempio.qualcosa.riutilizzabile.php
               js/ JavaScript utilizzati nei partial.
                   esempio.qualcosa.reusable.js.php

Come puoi vedere, l'unico file obbligatorio all'interno del modulo personalizzato la directory è manifest.json. Il modulo non si registrerà senza questo file. Module.php è responsabile della registrazione delle voci di menu e eventi di elaborazione come "onBeforeAction" e "onTerminate". Il Le directory actions, views e partials contengono PHP e JavaScript codice necessario per le azioni del modulo.

Convenzione di denominazione

Prima di creare un modulo, è importante concordare la denominazione convenzione per diversi elementi del modulo come directory e file così che potremmo mantenere le cose ben organizzate. Puoi anche trovare degli esempi sopra, nella sezione Struttura del modulo.

Elemento Regole di denominazione Esempio
Directory del modulo [a-z] minuscole, underscore e cifre decimali esempio_v2
Sottodirectory delle azioni [a-z] minuscole e trattino basso data_export
File di azione CamelCase, che termina con tipo di azione SomethingView.php
Vista e file parziali [a-z] minuscola
Parole separate da punto
Preceduto da module. seguito dal nome del modulo
Termina con tipo di azione ed estensione file .php
modulo.esempio .qualcosa.view.php
File Javascript Si applicano le stesse regole dei file view e partial, eccetto l'estensione file .js.php. module.example.something.view.js.php

Si noti che il prefisso "modulo" e l'inclusione del nome sono obbligatori per la visualizzazione e nomi di file parziali, a meno che non sia necessario sovrascrivere le viste principali di Zabbix o parziali. Questa regola, tuttavia, non si applica ai nomi dei file di azione.

Preparazione manifesto

Ogni modulo dovrebbe avere un file manifest.json con quanto segue campi in formato JSON:

Parametro Obbligatorio Tipo Predefinito Descrizione
manifest_version Double - Versione manifest del modulo. La versione attualmente supportata è 1.
id Stringa - ID modulo. È possibile abilitare un solo modulo con un determinato ID alla volta.
nome Stringa - Nome del modulo visualizzato nella sezione Amministrazione.
versione Stringa - Versione del modulo visualizzata nella sezione Amministrazione.
namespace Stringa - Spazio dei nomi PHP per Module.php e classi di azioni.
author No Stringa "" Autore del modulo visualizzato nella sezione Amministrazione.
url No Stringa "" URL del modulo visualizzato nella sezione Amministrazione.
description No Stringa "" Descrizione del modulo visualizzata nella sezione Amministrazione.
actions No Oggetto {} Azioni da registrare con questo modulo. Vedere Azioni.
config No Oggetto {} Configurazione modulo.

Per riferimento, vedere un esempio di manifest.json nel file Sezione Riferimento.

Azioni

Il modulo avrà il controllo sulle azioni di frontend definite all'interno del file actions nel file manifest.json. Così sono le nuove azioni definito. Allo stesso modo puoi ridefinire le azioni esistenti. Ogni chiave di le azioni dovrebbero rappresentare il nome dell'azione e il valore corrispondente dovrebbe contenere le chiavi class e facoltativamente layout e view.

Un'azione è definita da quattro controparti: nome, controller, vista e disposizione. La convalida e la preparazione dei dati viene in genere eseguita nel file controller, la formattazione dell'output viene eseguita nella vista o nei parziali e il file layout è responsabile della decorazione della pagina con elementi come menu, intestazione, piè di pagina e altri.

Le azioni del modulo devono essere definite nel file manifest.json come actions oggetto:

Parametro Obbligatorio Tipo Predefinito Descrizione
*chiave* Stringa - Nome dell'azione, in minuscolo [a-z], separando le parole con un punto.
class Stringa - Nome della classe azione, incluso il percorso della sottodirectory (se utilizzata) all'interno della directory actions.
layout No Stringa "layout.htmlpage" Layout azione.
view No Stringa null Vista azione.

Esistono diversi layout predefiniti, come layout.json o disposizione.xml. Questi sono destinati ad azioni che producono diversi risultato di un HTML. Puoi esplorare i layout predefiniti nel file app/views/ directory o persino crearne una tua.

A volte è necessario solo ridefinire la vista parte di qualche azione lasciando intatto il controller. In tal caso basta posizionare il necessario view e/o i file parziali all'interno della directory views del modulo.

Per riferimento, vedere un file di action controller di esempio nel file Sezione Riferimento. Non esitate a esplorare azioni correnti del codice sorgente di Zabbix, che si trova nella directory app/.

Modulo.php

Questo file PHP opzionale è responsabile anche dell'inizializzazione del modulo come gestione degli eventi. La classe 'Modulo' dovrebbe essere definita in questo file, che estende la classe base \Core\CModule. La classe Module deve essere definito all'interno dello spazio dei nomi specificato nel file manifest.json.

<?php
       
       namespace Moduli\Esempio;
       usa Core\CModule come BaseModule;
       
       class Module extends BaseModule {
           ...
       }

Per riferimento, vedere un esempio di Module.php nel file Sezione Riferimento.

Riferimento

Questa sezione contiene le versioni base di diversi elementi del modulo introdotto nelle sezioni precedenti.

manifest.json

{
           "versione_manifest": 1.0,
           "id": "modulo_esempio",
           "name": "Modulo di esempio",
           "versione": "1.0",
           "namespace": "Esempio",
           "autore": "John Smith",
           "url": "http://modulo.esempio.com",
           "description": "Breve descrizione del modulo.",
           "Azioni": {
               "esempio.qualcosa.vista": {
                   "class": "QualcosaVista",
                   "view": "modulo.esempio.qualcosa.view"
               },
               "esempio.qualcosa.create": {
                   "class": "QualcosaCrea",
                   "disposizione": nullo
               },
               "esempio.qualcosa.delete": {
                   "class": "QualcosaCancella",
                   "disposizione": nullo
               },
               "esempio.qualcosa.export.xml": {
                   "class": "data_export/ExportAsXml",
                   "disposizione": nullo
               },
               "esempio.qualcosa.export.excel": {
                   "class": "data_export/ExportAsExcel",
                   "disposizione": nullo
               }
           },
           "config": {
               "nomeutente": "john_smith"
           }
       }

Modulo.php

<?php Declaration(strict_types = 1);
       
       namespace Moduli\Esempio;
       
       utilizzare l'APP;
       usa CController come CAction;
       
       /**
        * Consulta la classe Core\CModule per ulteriori riferimenti.
        */
       classe Il modulo estende \Core\CModule {
       
           /**
            * Inizializza il modulo.
            */
           funzione pubblica init(): void {
               // Inizializza il menu principale (istanza della classe CMenu).
               APP::Component()→get('menu.main')
                   →findOrAdd(_('Rapporti'))
                       →getSottomenu()
                           →add((new \CMenuItem(_('Esempio di report esteso')))
                               →setAction('esempio.report.wide.php')
                           )
                           →add((new \CMenuItem(_('Esempio di report ristretto')))
                               →setAction('example.report.narrow.php')
                           );
           }
       
           /**
            * Gestore di eventi, attivato prima dell'esecuzione dell'azione.
            *
            * @param CAction $action Istanza dell'azione responsabile della richiesta corrente.
            */
           public function onBeforeAction(CAction $action): void {
           }
       
           /**
            * Gestore di eventi, attivato all'uscita dall'applicazione.
            *
            * @param CAction $action Istanza dell'azione responsabile della richiesta corrente.
            */
           public function onTerminate(CAction $action): void {
           }
       }

Controller d'azione

<?php Declaration(strict_types = 1);
       
       spazio dei nomi Moduli\Esempio\Azioni;
       
       utilizzare CControllerResponseData;
       utilizzare CControllerResponseFatal;
       usa CController come CAction;
       
       /**
        * Esempio di azione del modulo.
        */
       class SomethingView estende CAction {
       
           /**
            * Inizializza l'azione. Metodo chiamato da Zabbix core.
            *
            * @return void
            */
           funzione pubblica init(): void {
               /**
                * Disabilita la convalida SID (Sessoin ID). La convalida dell'ID di sessione deve essere utilizzata solo per azioni che coinvolgono dati
                * modifica, come azioni di aggiornamento o eliminazione. In tal caso, l'ID di sessione deve essere presentato nell'URL, in modo che
                * l'URL scadrà non appena la sessione sarà scaduta.
                */
               $this→disableSIDvalidation();
           }
       
           /**
            * Controlla e disinfetta i parametri di input dell'utente. Metodo chiamato da Zabbix core. L'esecuzione si interrompe se viene restituito false.
            *
            * @return bool vero in caso di successo, falso in caso di errore.
            */
           funzione protetta checkInput(): bool {
               $campi = [
                   'nome' => 'obbligatorio|stringa',
                   'email' => 'obbligatorio|stringa',
                   'telefono' => 'stringa'
               ];
       
               // Solo i dati convalidati saranno ulteriormente disponibili utilizzando $this→hasInput() e $this→getInput().
               $ret = $this→validateInput($fields);
       
               se (!$ret) {
                   $this→setResponse(new CControllerResponseFatal());
               }
       
               ritorna $ret;
           }
       
           /**
            * Controlla se l'utente ha il permesso di eseguire questa azione. Metodo chiamato da Zabbix core.
            * L'esecuzione si interrompe se viene restituito false.
            *
            * @return bool
            */
           funzione protetta checkPermissions(): bool {
               $permit_user_types = [USER_TYPE_ZABBIX_ADMIN, USER_TYPE_SUPER_ADMIN];
       
               return in_array($this→getUserType(), $permit_user_types);
           }
       
           /**
            * Preparare l'oggetto risposta per la vista. Metodo chiamato da Zabbix core.
            *
            * @return void
            */
           funzione protetta doAction(): void {
               $contatti = $this→getInput('email');
       
               if ($this→hasInput('telefono')) {
                   $contatti .= ', '.$this→getInput('telefono');
               }
       
               $dati = [
                   'nome' => $this→getInput('nome'),
                   'contatti' => $contatti
               ];
       
               $ risposta = nuovo CControllerResponseData ($ dati);
       
               $this→setResponse($response);
           }
       }

Vista azione

<?php Declaration(strict_types = 1);
       
       /**
        * @var CView $this
        */
       
       $this→includeJsFile('example.something.view.js.php');
       
       (nuovo CWidget())
           →setTitle(_('Vista qualcosa'))
           →addItem(new CDiv($data['name']))
           →addItem(new CPartial('module.example.something.reusable', [
               'contatti' => $data['contatti']
           ])
           →mostra();