PHP的InfluxDB客户端库使用

这是一个influxdb的1.新版本客户端
GitHub - influxdata/influxdb-php: influxdb-php: A PHP Client for InfluxDB, a time series database
如果使用的是2.x版本，请使用找个客户端

GitHub - influxdata/influxdb-client-php: InfluxDB (v2+) Client Library for PHP

概览

一个易于使用的库，用于将inflexdb与PHP结合使用。由 @thecodeassassin, @gianarb. 维护。inflexdbphp库是为了拥有python influxdb客户机的php端口而创建的。这样，不同编程语言之间将有一个通用的抽象库。

安装

可以使用composer完成安装：

$ composer require influxdb/influxdb-php

PHP 5.3 和 PHP 5.4 用户请zhu'yi
如果使用php5.3和php5.4，0.1.x版本仍然受支持（bug修复和新版本修复）。0.1.x分支将在php5.3和php5.4上运行，但不包含1.0.0版本所具有的所有特性，例如UDP支持。

开始使用

初始化一个新的客户端对象

$client = new InfluxDB\Client($host, $port);

这将创建一个新的客户机对象，您可以使用它来读写InfluxDB的点。还可以从DSN（数据源名称）创建客户端：

// 直接获取数据库句柄
$database = InfluxDB\Client::fromDSN(sprintf('influxdb://user:pass@%s:%s/%s', $host, $port, $dbname));

// 使用客户端检索其他数据库
$client = $database->getClient();

重要提示：当使用DSN时，不要忘记urlencode（）password（和username），尤其是当它包含非字母数字字符时。不这样做可能会引发异常。

读取数据

要从InfluxDB获取记录，可以直接在数据库上执行查询：

// 选择数据库
$database = $client->selectDB('influx_test_db');

//执行查询将生成resultset对象
$result = $database->query('select * from test_metric LIMIT 5');

// 从resultset获取点生成一个数组
$points = $result->getPoints();

也可以使用QueryBuilder对象。这个类简化了构建查询的过程。

// 使用查询生成器检索点
$result = $database->getQueryBuilder()
    ->select('cpucount')
    ->from('test_metric')
    ->limit(2)
    ->offset(2)
    ->getResultSet()
    ->getPoints();

//从QueryBuilder获取查询
$query = $database->getQueryBuilder()
    ->select('cpucount')
    ->from('test_metric')
    ->where(["region = 'us-west'"])
    ->getQuery();

确保在对字符串执行where查询时输入单引号；否则InfluxDB将返回空结果。

您可以从客户端获取最后执行的查询：

// 使用 getLastQuery() 获取方法
$lastQuery = $client->getLastQuery();

// 或直接访问静态变量：
$lastQuery = Client::lastQuery;

使用超时读取数据

在生产环境中，如果您正在查询InfluxDB以生成对web或API请求的响应，则可能需要为InfluxDB调用设置一个特定的超时，而不是让它们无限期运行的默认值。

// 使用5秒超时获取数据库
$database = InfluxDB\Client::fromDSN(sprintf('influxdb://user:pass@%s:%s/%s', $host, $port, $dbname), 5);

写入数据

通过向数据库上的writePoints方法提供一个点数组来写入数据：

// 创建点阵列
$points = array(
    new Point(
        'test_metric', // name of the measurement
        0.64, // the measurement value
        ['host' => 'server01', 'region' => 'us-west'], // optional tags
        ['cpucount' => 10], // optional additional fields
        1435255849 // Time precision has to be set to seconds!
    ),
    new Point(
        'test_metric', // name of the measurement
        0.84, // the measurement value
        ['host' => 'server01', 'region' => 'us-west'], // optional tags
        ['cpucount' => 10], // optional additional fields
        1435255849 // Time precision has to be set to seconds!
    )
);

// 我们正在编写unix时间戳，它有第二个精度
$result = $database->writePoints($points, Database::PRECISION_SECONDS);

在将测量值写入InfluxDB时，可以添加多个字段。point类允许您轻松地将数据成批写入influxDB。

度量的名称和值是必需的。其他字段、标记和时间戳是可选的。InfluxDB将当前时间作为默认时间戳。

也可以在不指定多个测量值的情况下写入多个字段：

$points = [
    new Point(
        'instance', // the name of the measurement
        null, // measurement value
        ['host' => 'server01', 'region' => 'us-west'], // measurement tags
        ['cpucount' => 10, 'free' => 1], // measurement fields
        exec('date +%s%N') // timestamp in nanoseconds on Linux ONLY
    ),
    new Point(
        'instance', // the name of the measurement
        null, // measurement value
        ['host' => 'server01', 'region' => 'us-west'], // measurement tags
        ['cpucount' => 10, 'free' => 2], // measurement fields
        exec('date +%s%N') // timestamp in nanoseconds on Linux ONLY
    )
];

使用udp写入数据

首先，将InfluxDB主机设置为支持传入的UDP套接字：

[udp]
  enabled = true
  bind-address = ":4444"
  database = "test_db"

然后，在客户端中配置UDP驱动程序：

// set the UDP driver in the client
$client->setDriver(new \InfluxDB\Driver\UDP($client->getHost(), 4444));

$points = [
    new Point(
        'test_metric',
        0.84,
        ['host' => 'server01', 'region' => 'us-west'],
        ['cpucount' => 10],
        exec('date +%s%N') // this will produce a nanosecond timestamp on Linux ONLY
    )
];

// now just write your points like you normally would
$result = $database->writePoints($points);

或者只需使用DSN（数据源名称）使用UDP发送指标：

// get a database object using a DSN (Data Source Name)
$database = InfluxDBClient::fromDSN('udp+influxdb://username:pass@localhost:4444/test123');

// write your points
$result = $database->writePoints($points);

注意：重要的是要注意使用UDP时精度将被忽略。使用UDP将数据写入InfluxDB时，应始终使用纳秒精度。

时间戳精度

向点对象添加时间戳时，提供正确的精度非常重要。这是因为如果以秒为单位指定时间戳，并且设置了默认（纳秒）精度，则输入的时间戳将无效。

// Points will require a nanosecond precision (this is default as per influxdb standard)
$newPoints = $database->writePoints($points);

// Points will require second precision
$newPoints = $database->writePoints($points, Database::PRECISION_SECONDS);

// Points will require microsecond precision
$newPoints = $database->writePoints($points, Database::PRECISION_MICROSECONDS);

请注意，exec（'date+%s%N'）在MacOS下不工作；您可以使用PHP的microtime来获得微秒精度的时间戳，如下所示：

list($usec, $sec) = explode(' ', microtime());
$timestamp = sprintf('%d%06d', $sec, $usec*1000000);

创建数据库

当添加了一个默认的数据库保留策略时。此保留策略没有持续时间，因此将用内存刷新数据。

使用此库，可以在创建数据库时轻松提供保留策略：

// create the client
$client = new \InfluxDB\Client($host, $port, '', '');

// select the database
$database = $client->selectDB('influx_test_db');

// create the database with a retention policy
$result = $database->create(new RetentionPolicy('test', '5d', 1, true));

// check if a database exists then create it if it doesn't
$database = $client->selectDB('test_db');

if (!$database->exists()) {
    $database->create(new RetentionPolicy('test', '1d', 2, true));
}

您还可以更改保留策略：

$database->alterRetentionPolicy(new RetentionPolicy('test', '2d', 5, true));

展示数据

$result = $database->listRetentionPolicies();

添加更多保留策略

$result = $database->createRetentionPolicy(new RetentionPolicy('test2', '30d', 1, true));

客户端方法

客户端方法有些函数对于数据库来说过于通用。因此，在客户端中可以使用：

// list users
$result = $client->listUsers();

// list databases
$result = $client->listDatabases();

管理员方法

// add a new user without privileges
$client->admin->createUser('testuser123', 'testpassword');

// add a new user with ALL cluster-wide privileges
$client->admin->createUser('admin_user', 'password', InfluxDBClientAdmin::PRIVILEGE_ALL);

// drop user testuser123
$client->admin->dropUser('testuser123');

列出所有用户

// show a list of all users
$results = $client->admin->showUsers();

// show users returns a ResultSet object
$users = $results->getPoints();

取消授权和授权

可以在数据库级别和群集范围内授予权限。要在数据库上授予用户特定的权限，请提供数据库对象或数据库名称。

// grant permissions using a database object
$database = $client->selectDB('test_db');
$client->admin->grant(\InfluxDB\Client\Admin::PRIVILEGE_READ, 'testuser123', $database);

// give user testuser123 read privileges on database test_db
$client->admin->grant(InfluxDBClientAdmin::PRIVILEGE_READ, 'testuser123', 'test_db');

// revoke user testuser123's read privileges on database test_db
$client->admin->revoke(InfluxDBClientAdmin::PRIVILEGE_READ, 'testuser123', 'test_db');

// grant a user cluster-wide privileges
$client->admin->grant(InfluxDBClientAdmin::PRIVILEGE_READ, 'testuser123');

// Revoke an admin's cluster-wide privileges
$client->admin->revoke(InfluxDBClientAdmin::PRIVILEGE_ALL, 'admin_user');

待完成功能

• 更多单元测试

*增加文档（wiki？）

*向查询生成器添加更多功能

*向保留策略添加验证