README

本软件采用GNU Lesser General Public License v3.0许可。

变更日志

查看 CHANGELOG.md。

带有会话缓存和SSL支持的Zabbix API PHP客户端

市面上有很多与Zabbix配合得很好的Zabbix API客户端。然而，其中大多数不支持会话缓存或需要调整才能与自签名证书一起使用。

这个库旨在解决这些问题。它支持以下功能

会话缓存。
使用官方和自签名证书的HTTPS连接。
适用于Linux和Windows PHP实现。
使用不同用户帐户和/或不同服务器的多个并发连接。
Zabbix版本：3.0、3.2、3.4、4.0、4.2、4.4、5.0、5.2、5.4和6.0。
无需安装。

该软件由IntelliTrend GmbH提供商业支持和维护，该公司是官方Zabbix合作伙伴和Zabbix培训公司。

在2020年Benelux的Zabbix会议上，还有一个关于在Zabbix中使用此库的闪电演讲Zabbix API – the easy way。

为什么需要会话缓存？

通过API进行认证通常是如何工作的

每次应用程序使用user.login时，Zabbix API都会创建一个所谓的AuthKey。（参见user.login）。然后，该密钥通过每个请求通过auth请求属性传递。

在大多数情况下，API库会为用户透明地完成此操作。但是，如果脚本稍后再次调用（例如，由cron作业调用），则将执行新的user.login，从而为该新会话创建一个新的AuthKey。

Zabbix保留这些会话，直到会话过期或注销。您可以通过Zabbix前端检查您的实际设置：管理/常规/管家 - 会话部分。默认值为365天。

这意味着，任何创建的会话（如果没有注销）将保留365天。

假设我们有一组每小时运行一次的10个API脚本。这意味着我们每天将创建10 x 24 = 240个会话。使用更多脚本或更短的间隔将当然会增加这个数字。

注意：Zabbix 5.4及以后的版本支持API认证令牌，使用时不会创建会话。因此，客户端也不需要会话管理。

会话表中许多会话的问题

每次请求击中Zabbix前端（无论是通过Web浏览器还是作为JSON RPC API请求），Zabbix都必须验证请求是否与现有会话匹配。要验证的会话越多，这需要的时间就越长。

注意：我们见过拥有数百万会话的安装，其中前端访问因每个请求15秒以上的延迟而大幅减慢。请记住，例如仪表板不仅执行一个请求，而且根据使用的仪表板小部件数量执行多个请求。

因此，最好是重用会话，直到它过期。这就是会话缓存介入的地方。

使用Zabbix API进行会话缓存

当创建新的会话时，AuthKey会被加密后保存到磁盘上。这类似于在经典网页浏览器中使用cookie。如果执行新的请求，则会读取现有的会话一次，并重用AuthKey。

所以，根据之前给出的示例：使用会话缓存调用脚本，即使是一个月，也只会创建1个会话。

如果AuthKey变得无效，库会自动执行新的user.login，重新执行失败的请求，并更新存储的会话。所有这些都在后台进行，库的用户无需处理。

会话加密是如何工作的，关于多个会话呢？

每个会话都有一个基于zabbixUserName和zabbixUrl的哈希值唯一的名称。会话本身使用zabbixUserName和zabbixPassword进行加密。

这样，库可以使用不同的用户账户和不同的Zabbix服务器实例。

会话存储在哪里？

默认情况下，会话存储在用户的tmp目录中。但是，有一个配置选项sessionDir可以覆盖此设置。详见以下详细描述。

安装

注意：PHP环境必须已安装CURL。ZabbixApi.php内置了对curl的检查，如果curl缺失，将抛出异常。

不使用composer

无需安装。只需复制ZabbixApi.php文件并使用该类。

require_once "ZabbixApi.php";

use IntelliTrend\Zabbix\ZabbixApi;

$zbx = new ZabbixApi();

使用composer

require('vendor/autoload.php');

use IntelliTrend\Zabbix\ZabbixApi;

$zbx = new ZabbixApi();

参见examples/composer获取带有详细信息的完整示例。

使用方法

错误处理

库使用Exceptions。无需检查每个响应值。只需将调用包裹在try/catch块中。

根据错误发生的位置，将不同的错误代码传递给异常对象，以及消息属性。

Zabbix API错误：传递原始API错误代码和消息。
连接和SSL错误：传递原始CURL错误代码和消息。
库错误：传递由类常量EXCEPTION_CLASS_CODE定义的常量错误代码和有用的消息。默认=1000。

配置

在调用login方法时配置类。任何进一步的Zabbix API调用都通过call方法执行。

注意：可以同时运行多个实例，连接到同一个Zabbix服务器或另一个Zabbix服务器上的不同用户账户。

基本使用

让我们从一个非常简单的示例开始

require_once "ZabbixApi.php";
use IntelliTrend\Zabbix\ZabbixApi;
$zbx = new ZabbixApi();
try {
	$zbx->login('https://my.zabbixurl.com/zabbix', 'myusername', 'mypassword');
	$result = $zbx->call('host.get', array("countOutput" => true));
	print "Number of hosts:$result\n";
} catch (Exception $e) {
	print "==== Exception ===\n";
	print 'Errorcode: '.$e->getCode()."\n";
	print 'ErrorMessage: '.$e->getMessage()."\n";
	exit;
}

基本上，这就可以了。call方法对Zabbix API定义是透明的。它接受两个参数：$method和$params，正如特定Zabbix API方法所指定的。

除了使用用户名和密码进行登录外，您还可以在Zabbix 5.4+中使用API令牌

require_once "ZabbixApi.php";
use IntelliTrend\Zabbix\ZabbixApi;
$zbx = new ZabbixApi();
try {
	$zbx->loginToken('https://my.zabbixurl.com/zabbix', '123456789abcdef123456789abcdef123456789abcdef123456789abcdef1234');
	$result = $zbx->call('host.get', array("countOutput" => true));
	print "Number of hosts:$result\n";
} catch (Exception $e) {
	print "==== Exception ===\n";
	print 'Errorcode: '.$e->getCode()."\n";
	print 'ErrorMessage: '.$e->getMessage()."\n";
	exit;
}

例如，要检索所有具有所有属性的'主机组'，我们可以这样做

require_once "ZabbixApi.php";
use IntelliTrend\Zabbix\ZabbixApi;
$zbx = new ZabbixApi();
$zabUrl = 'https://my.zabbixurl.com/zabbix';
$zabUser = 'myusername';
$zabPassword = 'mypassword';
try {
	$zbx->login($zabUrl, $zabUser, $zabPassword);
	$result = $zbx->call('hostgroup.get', array("output" => 'extend'));
	foreach ($result as $hostGroup) {
		$hostGroupId = $hostGroup['groupid'];
		$hostGroupName = $hostGroup['name'];
		print "groupid:$hostGroupId, hostGroupName:$hostGroupName\n";
	}
} catch (Exception $e) {
	print "==== Exception ===\n";
	print 'Errorcode: '.$e->getCode()."\n";
	print 'ErrorMessage: '.$e->getMessage()."\n";
	exit;
}

注意：第二个示例在第一个示例之后再次调用login时不会创建新的会话。它会重用前一个示例中的会话。login在找到现有会话时返回true。

高级使用和SSL选项

基本示例在HTTPS下也可以正常工作，前提是php安装已知的有效证书。但是，当使用自签名证书时怎么办呢？

在这种情况下，我们可以在调用login时使用可选的options参数来设置SSL选项。

示例 - 关闭SSL验证

require_once "ZabbixApi.php";
use IntelliTrend\Zabbix\ZabbixApi;
$zbx = new ZabbixApi();
$options = array('sslVerifyPeer' => false, 'sslVerifyHost' => false);
try {
	$zbx->login('https://my.zabbixurl.com/zabbix', 'myusername', 'mypassword', $options);
	$result = $zbx->call('host.get', array("countOutput" => true));
	print "Number of hosts:$result\n";
} catch (Exception $e) {
	print "==== Exception ===\n";
	print 'Errorcode: '.$e->getCode()."\n";
	print 'ErrorMessage: '.$e->getMessage()."\n";
	exit;
}

使用过滤器和字段选择器

通过API传递过滤器和字段选择器相当简单。基本上，可以通过这种方式传递Zabbix-API定义的任何params。

示例 - 根据状态、维护状态和类型选择前5个主机，并添加它们的组和宏。

require_once "ZabbixApi.php";
use IntelliTrend\Zabbix\ZabbixApi;
$zbx = new ZabbixApi();
try {
	// default is to verify certificate and hostname
	$options = array('sslVerifyPeer' => false, 'sslVerifyHost' => false);
	$zbx->login('https://my.zabbixurl.com/zabbix', 'myusername', 'mypassword', $options);

	print "====================================================================\n";
	// Get hosts and other information available to this useraccount, but filtered and limited
	$limit = 5;
	$params = array(
		'output' => array('hostid', 'host', 'name', 'status', 'maintenance_status', 'description'),
		'filter' => array('status' => 0, 'maintenance_status' => 0, 'type' => 1),
		'selectGroups' => array('groupid', 'name'),
		'selectInterfaces' => array('interfaceid', 'main', 'type', 'useip', 'ip', 'dns', 'port'),
		'selectInventory' => array('os', 'contact', 'location'),
		'selectMacros' => array('macro', 'value'),
		'limit' => $limit
	);

	$result = $zbx->call('host.get',$params);
	print "==== Filtered hostlist with groups and macros ====\n";
	foreach($result as $host) {
		printf("HostId:%d - Host:%s\n", $host['hostid'], $host['host']);
		foreach($host['groups'] as $group) {
			printf("    - GroupId:%d - Group:%s\n", $group['groupid'], $group['name']);
		}
		foreach($host['macros'] as $macro) {
			printf("    - Macro:%s - Value:%s\n", $macro['macro'], $macro['value']);
		}

	}

} catch (Exception $e) {
	print "==== Exception ===\n";
	print 'Errorcode: '.$e->getCode()."\n";
	print 'ErrorMessage: '.$e->getMessage()."\n";
	exit;
}

调试模式

类提供了一个调试模式，会输出大量详细信息。要启用，可以使用选项或函数。

将调试选项作为参数传递给 login() 函数

$zbx = new ZabbixApi();
try {
	$options = array('sslVerifyPeer' => false, 'sslVerifyHost' => false, 'debug' => true);
	$zbx->login('https://my.zabbixurl.com/zabbix', 'myusername', 'mypassword', $options);
	...

调试函数 - 可在任何时候使用

# Turn debug on
$zbx = new ZabbixApi();
$zbx->setDebug(true);
try {
	$options = array('sslVerifyPeer' => false, 'sslVerifyHost' => false);
	$zbx->login('https://my.zabbixurl.com/zabbix', 'myusername', 'mypassword', $options);
	...
	# Can be turned off anytime
	$zbx->setDebug(false);
	...
	# And turned on again
	$zbx->setDebug(true);

函数参考

基本函数

login($zabUrl, $zabUser, $zabPassword, $options)

初始登录。配置类并加载存在的缓存会话。在此期间不执行请求以测试远程服务器的凭据或会话。在第一次调用 Zabbix-API 时自动发生。可以在调用 login() 后强制执行验证，通过调用 getAuthKey()。

注意：如果通过选项或调用 login() 之前的功能启用调试，则 login() 会调用 Zabbix-API 来检查会话是否被重用。

return void
throws ZabbixApiException. 无效的选项、会话问题或连接问题。
param string $zabUrl
param string $zabUser
param string $zabPassword
param array $options - 可选设置。例如：array('sslVerifyPeer' => false, 'sslVerifyHost' => false);
- debug: boolean - 默认=false。显示调试信息。也可以使用 setDebug()。默认为 false
- sessionDir: string - 默认为用户 tmp 目录。存储会话的目录。
- sslCaFile: string - 默认使用 php.ini 设置。外部 CACertBundle 的文件名。当使用内部 CA 的自签名证书时很有用。请参阅 CURL 或 Mozilla 网站，了解那些捆绑包。
- sslVerifyPeer: boolean - 默认=true。验证证书。失败时抛出异常。当为 false 时，忽略任何验证错误。
- sslVerifyHost: boolean - 默认=true。将主机名与证书中的 CN 进行验证。只有当证书可以验证时才有效。
注意：如果 sslVerifyPeer=false 但证书本身有效且主机名不匹配，则 sslVerifyHost=true 将引发异常。
- useGzip: boolean - 默认=true。为请求使用 gzip 压缩。
- connectTimeout: integer - 默认=10。连接到服务器最大秒数。
- timeout: 默认=30。处理请求最大秒数。

loginToken($zabUrl, $zabToken, $options)

使用 API 令牌的替代登录方法，该令牌直接设置为身份验证令牌。选项与 login() 相同。

由于 API 令牌不需要会话管理，因此不加载或保存缓存会话。

return void
throws ZabbixApiException. 无效的选项、会话问题或连接问题。
param string $zabUrl
param string $zabToken
param array $options - 可选设置。

call($method, $params)

执行 Zabbix API 调用。如果调用失败，将自动使用从会话中读取的当前 authKey 登录/重新登录并重试。

注意：只能在之前任何时间调用 login() 一次之后调用。

return mixed $reusedSession. 来自 API 调用的解码 Json 响应或标量。有关详细信息，请参阅 Zabbix API 文档。
throws ZabbixApiException. API 错误、会话问题或连接问题。
param string $method. Zabbix API 方法，例如 'host.get'
param mixed $params. 该方法的参数，如 Zabbix API 中定义。

logout()

从 Zabbix 服务器注销，并从文件系统中删除 authKey。

注意：只有当确实需要时才使用此方法，因为会话不能在之后重用。使用 API 令牌创建的 API 对象的注销没有效果。

return void
throws ZabbixApiException. API 错误、会话问题或连接问题

setDebug($state)

启用/禁用调试输出。可以随时使用。

return void
param boolean $state. 为 true 启用调试输出。

方便的函数

getVersion()

获取此库的版本。

return string $version。

getApiVersion()

从 Zabbix 服务器获取 Zabbix API 版本。也很有用，以检查 Zabbix Api url 是否有效。

注意：优先使用此函数而不是 call('apiinfo.version')，因为它不会尝试认证，并存储Zabbix Api版本以供后续请求使用。

返回 字符串 $version。使用API方法 'apiinfo.version'。
throws ZabbixApiException. API 错误、会话问题或连接问题

实用函数

getAuthKey()

获取用于API通信的authKey。

注意：如果没有之前的Zabbix-API调用，此函数将调用Zabbix-API以确保有效的authkey。

返回 字符串 $authKey。

getSessionDir()

获取会话目录。

返回 字符串 $directory。

getSessionFileName()

获取存储加密authKey的FileName，不包含路径。

返回 字符串 $fileName。

getSessionFile()

获取包含路径的完整FileName。

返回 字符串 $fileName。

技巧与窍门

常见的 "get" 方法参数

如Zabbix-Api 中所述，可以在 "get" 方法中添加多个参数。

附上一些不太为人所知但非常实用的参数列表，特别是 preservekeys。

intellitrend / zabbixapi

维护者

详细信息