API SOAP OpMon

 

Objetivo

Descrever sobre as funcionalidades disponíveis na API SOAP do OpMon.

Público alvo

Administradores da plataforma OpMon que necessitam fazer integração entre sistemas que utilizam o protocolo SOAP e o OpMon.

Sobre o SOAP

SOAP (Simple Object Access Protocol) é um protocol de comunicação baseado em XML que permite a comunicação de mensagens entre aplicações via HTTP.

Utilização

O acesso descritivo da interface SOAP OpMon pode ser feito pela url:

https://[servidor]/opmon/ws

O arquivo WSDL pode ser acessado em:

https://[servidor]/opmon/ws/index.php?wsdl

Toda a execução de método deve ser feita de forma autenticada utilizando um usuário existente no sistema OpMon.

Funcionalidades

soap_opmon_export

Descrição: Este WebServices é capaz de executar o export das configurações do opmon.

Parâmetros: nenhum.

Retorno: string no formato json indicando sucesso.

soap_clone_host

Descrição: Este WebServices é utilizado para criar hosts no OpMon utilizando um outro como base.

Parâmetros:

src_hostname (string): Nome do host que será utilizado como base;

dst_hostname (string): Nome que o host clone irá assumir;

dst_host_description (string): Descrição que o host clone irá assumir;

dst_host_address (string): Endereço (FQDN/IP) que o host clone irá assumir.

Retorno: string no formato json indicando sucesso.

Exceções:

Caso alguns dos parâmetros não for informado uma exception é lançada;

Caso o usuário utilizado não seja opmonadmin uma exception é lançada;

Caso o opmon não consiga alocar recursos para clonar o host uma exception é lançada.

soap_delete_host

Descrição: Este WebServices tem como finalidade deletar um host da plataforma OpMon.

Parâmetros:

hostname_or_id (string): Nome ou ID do host que o usuário deseja deletar.

Retorno: string no formato json indicando sucesso.

Exceções:

Caso o usuário utilizado não seja opmonadmin uma exception é lançada;

Caso o host não seja encontrado no OpMon uma exception é lançada.

soap_create_host_from_template

Descrição: Este WebServices é utilizado para criar hosts no OpMon utilizando um template como base.

Parâmetros:

template_name (string): Nome do template que será utilizado como base;

dst_hostname (string): Nome que o novo host irá assumir;

dst_host_description (string): Descrição que o novo host irá assumir;

dst_host_address (string): Endereço (FQDN/IP) que o novo host irá assumir.

Retorno: string no formato json indicando sucesso.

Exceções:

Caso alguns dos parâmetros não for informado uma exception é lançada;

Caso o usuário utilizado não seja opmonadmin uma exception é lançada;

Caso o host ja exista no monitoramento uma exception é lançada;

Caso o template não seja encontrado no OpMon uma exception é lançada;

Caso o opmon não consiga alocar recursos para clonar o host uma exception é lançada;

get_host_services_status

Descrição: Status de host e serviços.

Parâmetros:

host_name (string): nome do host (obrigatório).

Retorno:

Objeto formatado em json contendo os serviços do host, seus estados e dados de performance.

soap_get_hosts_by_services

Descrição: Retorna todos os hosts e serviços do sistema.

Parâmetros: Nenhum.

Retorno:

Objeto formatado em json contendo todos os hosts e seus serviços.

soap_get_hostgroups

Descrição: Retorna todos os grupos de hosts e seus membros.

Parâmetros: Nenhum.

Retorno: Objeto formatado em json contendo todos os grupos de hosts e seus membros.

soap_get_servicegroups

Descrição: Retorna todos os grupos de serviços e seus membros.

Parâmetros: Nenhum.

Retorno: Objeto formatado em json contendo todos os grupos de serviços e seus membros.

soap_add_scheduled_downtime

Descrição: Adiciona uma parada agendada.

Parâmetros:

id (string): Id do host/serviço (host_id!service_id)/hostgroup_id/servicegroup_id (obrigatório);

comment (string): Comentário (obrigatório);

start_time (int): Data inicial em formato unix timestamp (obrigatório);

end_time (int): Data final em formato unix timestamp (obrigatório);

type (int): 1 = fixa, 0 = flexível (padrão = 1);

child_hosts (int): 0 = ignora, 1 = agenda uma parada programada, 2 = agenda uma parada não programada (padrão: 0);

triggered_by (int): downtime_id (padrão: vazio);

hour_duration (int): Duração em horas caso tipo seja flexível (padrão: 2);

minute_duration (int): Duração em minutos caso tipo seja flexível (padrão: 0);

force_utf8 (booleano): Força encodificação utf8 (padrão: false);

obj_type (int): 0 = HOST, 1 = SERVICE, 2 = HOSTGROUP, 3 = SERVICEGROUP (padrão: 0).

Retorno: Objeto formatado em json contendo o status da operação.

soap_add_scheduled_downtimes

Descrição: Adiciona uma parada agendada em múltiplos elementos.

Parâmetros:

ids (array string): Array de Ids de hosts/serviços;

(host_id!service_id)/hostgroup_id/servicegroup_id (obrigatório);

comment (string): Comentário (obrigatório);

start_time (int): Data inicial em formato unix timestamp (obrigatório);

end_time (int): Data final em formato unix timestamp (obrigatório);

type (int): 1 = fixa, 0 = flexível (padrão = 1);

child_hosts (int): 0 = ignora, 1 = agenda uma parada programada, 2 = agenda uma parada não programada (padrão: 0);

triggered_by (int): downtime_id (padrão: vazio);

hour_duration (int): Duração em horas caso tipo seja flexível (padrão: 2);

minute_duration (int): Duração em minutos caso tipo seja flexível (padrão: 0);

force_utf8 (booleano): Força encodificação utf8 (padrão: false);

obj_type (int): 0 = HOST, 1 = SERVICE, 2 = HOSTGROUP, 3 = SERVICEGROUP (padrão: 0);

Retorno: Objeto formatado em json contendo o status da operação.

soap_get_scheduled_downtime

Descrição: Lista as paradas agendadas do sistema associadas a um determinado elemento.

Parâmetros:

id (string): Id do host/serviço (host_id!service_id)/hostgroup_id/servicegroup_id (padrão: vazio);

comment (string): Filtra por comentário (padrão: vazio);

force_utf8 (booleano): força encodificação utf8 (padrão: false);

obj_type (int): 0 = HOST, 1 = SERVICE, 2 = HOSTGROUP, 3 = SERVICEGROUP (padrão: 0).

Retorno: Objeto formatado em json contendo paradas agendadas de todos os elementos associados.

OBS: Paradas com a propriedade type igual a 1102 e 1103 são consideradas abertas e paradas com type igual a 1104 são consideradas encerradas.

soap_remove_scheduled_downtime

Descrição: Remove uma parada agendada quando o argumento downtime_id for usado ou todas as paradas de um determinado elemento.

Parâmetros:

id (string): Id do host/serviço (host_id!service_id)/hostgroup_id/servicegroup_id (obrigatório);

downtime_id (int): Id da parada (opcional, caso seja usado somente uma parada será removida);

obj_type (int): 0 = HOST, 1 = SERVICE, 2 = HOSTGROUP, 3 = SERVICEGROUP (padrão: 0).

Retorno: Objeto formatado em json contendo o status da operação

soap_remove_scheduled_downtimes

Descrição: Remove todas as paradas agendas de um grupo de elementos de um mesmo tipo.

Parâmetros:

ids (array string): Array de Ids de hosts/serviços (host_id!service_id)/hostgroup_id/servicegroup_id (obrigatório);

obj_type (int): 0 = HOST, 1 = SERVICE, 2 = HOSTGROUP, 3 = SERVICEGROUP (padrão: 0).

Retorno: Objeto formatado em json contendo o status da operação.

soap_remove_scheduled_downtimes_by_comment

Descrição: Remove todas as paradas agendas de um grupo de elementos de um mesmo tipo usando o comentário como filtro.

Parâmetros:

ids (array string): Array de Ids de hosts/serviços (host_id!service_id)/hostgroup_id/servicegroup_id (obrigatório);

comment (string): Filtra por comentário (padrão: vazio);

force_utf8 (booleano): força encodificação utf8 (padrão: false);

obj_type (int): 0 = HOST, 1 = SERVICE, 2 = HOSTGROUP, 3 = SERVICEGROUP (padrão: 0);

Retorno: Objeto formatado em json contendo o status da operação.

get_avail

Descrição: Retorna os dados referente a disponibilidade dos elementos passados por parâmetro

Parâmetros:

reportType (string): Tipo do relatório que será gerado, valores possíveis: simplified, detailed or tabular;
objectType (string): Tipo de objeto que será selecionado, valores possíveis: host, service, servicecatalog, hostgroup, servicegroup;
timeCutName (string): Nome do timecut cadastrado no opmon. ex: 24×7, 8×5 e etc;
reportPeriod (string): Período dos dados a serem coletados, valores possíveis: thishour, thisweek, thismonth, thisyear, today, yesterday, last24hours, lastweek, lastmonth, lastyear, last7days, last31days, {“last”: {“counter”: , “unit”: <days|hours|weeks|months>} ou {“custom”: {“start”: , “end”: }”;
selectedItens (string): String no formato json que contêm os elementos dos quais deseja-se obter o dados.

Exemplos:
hosts => “[‘opmon’, ‘windows’]”,
services => “[‘opmon!Load’]”,
servicecatalog => “[‘test’]”,
hostgroup => “[‘Linux’]”,
servicegroup => “[‘other’]”

advancedOptions (string): String no formato json representando um array com as informações que serão setadas. Os valores que o array pode conter são: “showThreshold”, “schedAsOk”, “breachAsOk” ou “softStates”. (opcional)

Exemplo:
“[‘showThreshold’, ‘schedAsOk’]”

Retorno: string no formato json com os dados solicitados.

Exceções:

Caso alguns dos parâmetros não for informado ou for inválido uma exception é lançada;

get_avail_by_report_name

Descrição: Retorna os dados referente a disponibilidade dos elementos baseando-se em um relatório salvo.

Parâmetros:
reportName (string): Nome do relatório salvo na interface do relatório de disponibilidade.

Retorno:
string no formato json com os dados solicitados.

//"reportType": "simplified|detailed|tabular",
$reportType = 'detailed';

//"objectType": "host|service|hostgroup|servicegroup|servicecatalog",
$objectType = 'service';

$advancedOptions = json_encode(array("showThreshold", "schedAsOk", "breachAsOk", "softStates"));

$timeCutName = '24x7';

//"reportPeriod": "thishour|thisweek|thismonth|thisyear|today|yesterday|
//last24hours|lastweek|lastmonth|lastyear|last7days|last31days|{last: {counter: 1, unit: days|hours|weeks|months}|
//custom: {start: dd-mm-yyyy HH:MM, end: dd-mm-yyyy HH:MM}",
$reportPeriod = json_encode(array('custom' => array('start' => '29-08-2016 23:59', 'end' => '31-08-2014 23:59')));

$selectedItens = json_encode(array('opmon!Load', 'opmon!Disk_/'));

$args = array(
    'reportType' => $reportType,
    'objectType' => $objectType,
    'timeCutName' => $timeCutName,
    'reportPeriod' => $reportPeriod,
    'selectedItens' => $selectedItens
    'advancedOptions' => $advancedOptions
);

// Coletando dados
echo ($client->call('get_avail', $args));

//Coletando dados utilizando um relatório salvo
echo ($client->call('get_avail_by_report_name', array('reportName' => 'test')));

 

Exemplos:

Seguem alguns exemplos de uso da API em PHP usando a biblioteca NuSOAP

<?php
//error_reporting(E_ALL);
require "nusoap/lib/nusoap.php";

//host onde esta rodando o servidor opmon
$service = "https://localhost/opmon/ws/";
$client = new nusoap_client($service); 
$client->soap_defencoding = 'UTF-8'; 
$client->decode_utf8 = false;

//Usuário e senha do opmon 
$client->setCredentials("opmonadmin","opservices");

//Retorna todas as paradas agendadas ativas ou não do serviço ID 187!60522
$rs = $client->call('soap_get_scheduled_downtime', 
array('187!60522','',false,1));
var_dump($rs);

//adiciona uma parada agendada para todos os serviços de um grupo com ID 1 
$rs = $client->call('soap_add_scheduled_downtimes', 
array(array(1),'nova parada',time()+1,time()+60,1,0,0,2,0,false,3));

//Remove todas a paradas ativas do host ID 2
$rs = $client->call('soap_remove_scheduled_downtime',array('2',null,0)); 

//Remove todas a paradas ativas filtradas pelo comentário "test" do grupo de serviço com ID 1
$rs = $client->call('soap_remove_scheduled_downtimes_by_comment', array(array('1'),'test',false,0,3));

//Saida de API
echo 'Response';
echo '< pre >' . htmlspecialchars($client->response, ENT_QUOTES) .
'< /pre >'; 
echo 'Fault';
echo '< pre >' . htmlspecialchars($client->fault, ENT_QUOTES) . '< /pre >';
?>