README

本包的 3.x 版本与 Zabbix™（从版本 3.0.0 到 3.4.15）兼容并经过测试。如果您要从 2.x 版本迁移到此包，请参考升级说明。

关于

PhpZabbixApi 是一个开源的 PHP SDK，用于与 Zabbix JSON-RPC API 通信。

由于此包直接从原始 Zabbix PHP 前端源代码生成，每个实际的 Zabbix JSON-RPC API 方法都直接作为 PHP 方法实现。这意味着 PhpZabbixApi 对 IDE 友好，因为每个 API 方法都有一个声明的 PHP 方法，且没有 PHP 魔术函数或其他类似功能。

许可证

PhpZabbixApi 在 MIT 许可证 下授权。

安装

确保您要安装的包版本与您的 Zabbix API 版本兼容。如果您不确定您的 Zabbix API 版本，可以向 apiinfo.version 方法发送请求

curl -X POST <your-zabbix-api-endpoint> \
    -H 'Content-Type: application/json-rpc' \
    -d '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'

将 <your-zabbix-api-endpoint> 替换为您的 Zabbix API 端点（例如，"https://your-zabbix-domain/api_jsonrpc.php")。然后，您将能够安装最适合您的 PhpZabbixApi 版本

composer require confirm-it-solutions/php-zabbix-api:<version>

可以安装所有 标记 版本，例如

composer require confirm-it-solutions/php-zabbix-api:^3.0

或者

composer require confirm-it-solutions/php-zabbix-api:^3.2

标签名称可能包含 构建元数据（加号之后的部分），以便轻松识别支持的 Zabbix API 版本范围。例如，标签 42.1.2+z3.0.0-z3.4.15 表示 PhpZabbixApi 版本 42.1.2 与从 3.0.0 到 3.4.15 的 Zabbix API 兼容并经过测试。

如果您正在寻找更多 前沿 版本（例如用于测试），您还可以通过设置版本约束中的特定 稳定性标志 来使用开发 分支

composer require confirm-it-solutions/php-zabbix-api:3.0@dev

使用该工具

命名概念

要将 Zabbix API 调用转换为 SDK 方法调用，您只需进行以下操作：

1. 删除点号；
2. 将操作名称的首字母大写。

示例

基本用法

要使用 PhpZabbixApi，您只需加载 ZabbixApi.php，创建一个新的 ZabbixApi 实例，然后就可以开始使用了

<?php
// Load ZabbixApi.

require_once __DIR__.'/vendor/autoload.php';

use Confirm\ZabbixApi\Exception;
use Confirm\ZabbixApi\ZabbixApi;

try {
    // Connect to Zabbix API.
    $api = new ZabbixApi(
        'https://zabbix.confirm.ch/api_jsonrpc.php',
        'zabbix_user',
        'zabbix_password'
    );

    // Do your stuff here.
} catch (Exception $e) {
    // Caught exception from ZabbixApi.
    echo $e->getMessage();
}

API 也可以与 HTTP Basic 认证 一起使用，您只需在构造函数中添加额外的参数即可

// Connect to Zabbix API through HTTP basic auth.
$api = new ZabbixApi(
    'https://zabbix.confirm.ch/api_jsonrpc.php',
    'zabbix_user',
    'zabbix_password',
    'http_user',
    'http_password'
);

如果您已经有了一个身份验证令牌，您可以将该值作为第 6 个参数传递，以避免库执行需要认证用户的 user.login 方法的请求。如果令牌有效，您可以省略第 2 和 3 个参数，因为它们将不再需要

// This token was previously obtained from a call to the `user.login` method.
$token = 'my_secret_token';

$api = new ZabbixApi(
    'https://zabbix.confirm.ch/api_jsonrpc.php',
    null,
    null,
    null,
    null,
    $token
);

// Make any secured method call.
$api->userGet();

HTTP 客户端

该软件包内部使用Guzzle HTTP客户端来针对Zabbix API进行请求。为了给您提供更多关于客户端配置的控制和灵活性，您可以将自己的\GuzzleHttp\ClientInterface实现作为ZabbixApi的第7个参数传递。

// Using your own HTTP client.

use GuzzleHttp\Client;

$httpClient = new Client([/* Your own config */]);

$api = new ZabbixApi(
    'https://zabbix.confirm.ch/api_jsonrpc.php',
    'zabbix_user',
    'zabbix_password',
    'http_user',
    'http_password',
    null,
    $httpClient
);

另外，如果您更喜欢为内置客户端提供选项而不是提供自己的客户端，您可以传递一个选项数组作为第8个参数。

// Using custom options fot the built-in HTTP client.

use GuzzleHttp\Client;

$httpClientOptions = [/* Your own config */];

$api = new ZabbixApi(
    'https://zabbix.confirm.ch/api_jsonrpc.php',
    'zabbix_user',
    'zabbix_password',
    'http_user',
    'http_password',
    null,
    null,
    $httpClientOptions
);

请注意，第7个参数和第8个参数不能同时使用。您必须从中选择一个。

身份验证令牌缓存

为了提高响应时间，避免在每次请求中调用user.login方法，您可以配置一个用于身份验证令牌的PSR-6缓存后端。这样，SDK将在第一次登录后获取缓存令牌，直到其过期。以下示例使用一个虚构的Psr6FilesystemAdapter类，但您可以选择任何可用的实现。

/** @var \Psr\Cache\CacheItemPoolInterface $psr6Cache */
$psr6Cache = new Psr6FilesystemAdapter();
$api->setTokenCache($psr6Cache);

示例

简单请求

这是一个使用graph.get API方法获取所有定义的图表的简单请求。

// Get all graphs.

/** @var array<array<string, mixed>> $graphs */
$graphs = $api->graphGet();

// Print all graph IDs.
foreach ($graphs as $graph) {
    echo $graph['graphid']."\n";
}

默认情况下，值将以关联数组的形式返回，但您始终可以选择在方法调用中将false作为第3个参数，以获取\stdClass实例。

// Get all graphs as instances of `\stdClass`.

/** @var \stcClass[] $graphs */
$graphs = $api->graphGet([], null, false);

// Print all graph IDs.
foreach ($graphs as $graph) {
    echo $graph->graphid."\n";
}

带参数的请求

大多数时候，您想要定义一些特定的参数。以下是一个使用graph.get API方法获取所有CPU图表的示例。

// Get all graphs named "CPU".
$cpuGraphs = $api->graphGet([
    'output' => 'extend',
    'search' => ['name' => 'CPU'],
]);

// Print graph ID with graph name.
foreach ($cpuGraphs as $graph) {
    printf("id:%d name:%s\n", $graph['graphid'], $graph['name']);
}

定义默认参数

有时您想定义默认参数，这些参数将包含在每个API请求中。您可以通过定义数组中的参数来实现，使用setDefaultParams()。

// Use extended output for all further requests.
$api->setDefaultParams([
    'output' => 'extend',
]);

// Get all graphs named "CPU".
$cpuGraphs = $api->graphGet([
    'search' => ['name' => 'CPU'],
]);

// Print graph ID with graph name.
foreach ($cpuGraphs as $graph) {
    printf("id:%d name:%s\n", $graph['graphid'], $graph['name']);
}

获取关联/非索引数组

默认情况下，所有API响应都将返回为索引数组。

因此，如果您正在寻找一个特定的命名图表，您必须遍历索引数组并比较每个元素的name属性。这可能有点麻烦，因此有一个简单的方法可以获取关联数组而不是索引数组。您只需传递方法参数2，即您希望用作结果数组键的属性名称。

以下是一个使用关联数组获取所有图表的示例，其中图表的name用作数组键。

// Get all graphs in an associative array (key=name).
$graphs = $api->graphGet([], 'name');

// Print graph ID with graph name.
if (array_key_exists('CPU Load Zabbix Server', $graphs)) {
    echo 'Graph "CPU Load Zabbix Server" exists.';
} else {
    echo 'Could not find graph "CPU Load Zabbix Server".';
}

我们正在寻找贡献者，点击此处获取更多信息