peynman/influxdb-client-php

InfluxDB (v2+) PHP 客户端库

维护者

详细信息

github.com/peynman/influxdb-client-php

主页

源代码

安装: 5

依赖: 0

建议者: 0

安全: 0

星星: 0

关注者: 1

分支: 47

1.7.0 2020-10-02 05:42 UTC

Requires

Requires (Dev)

MIT 5881416def300c99cd485afca463f8117e7473fd

influxdb

This package is auto-updated.

Last update: 2024-09-07 14:07:03 UTC

README

CircleCI codecov Packagist Version License GitHub issues GitHub pull requests PHP from Packagist Slack Status

此存储库包含 InfluxDB 2.x 的参考 PHP 客户端。

注意：请使用此客户端库与 InfluxDB 2.x 和 InfluxDB 1.8+ 配合使用（查看详细信息）。要连接到 InfluxDB 1.7 或更早版本，请使用 influxdb-php 客户端库。

文档

本节包含客户端库文档的链接。

安装

客户端不与 Guzzle、Buzz 或其他 HTTP 客户端库硬绑定。客户端使用通用抽象（PSR-7 - HTTP 消息、PSR-17 - HTTP 工厂、PSR-18 - HTTP 客户端），这为您提供了使用您最喜欢的库的自由。

安装库

InfluxDB 2 客户端捆绑并托管在 https://packagist.org.cn/，并且可以使用 composer 安装。

composer require influxdata/influxdb-client-php guzzlehttp/guzzle

用法

创建客户端

使用 InfluxDB2\Client 创建连接到正在运行的 InfluxDB 2 实例的客户端。

$client = new InfluxDB2\Client([
    "url" => "https://:8086",
    "token" => "my-token",
    "bucket" => "my-bucket",
    "org" => "my-org",
    "precision" => InfluxDB2\Model\WritePrecision::NS
]);

客户端选项

自定义 HTTP 客户端

以下代码演示了如何使用和配置 cURL HTTP 客户端

通过 composer 安装依赖项
composer require influxdata/influxdb-client-php nyholm/psr7 php-http/curl-client
配置 cURL 客户端
$curlOptions = [
    CURLOPT_CONNECTTIMEOUT => 30, // The number of seconds to wait while trying to connect.
];
$curlClient = new Http\Client\Curl\Client(
    Http\Discovery\Psr17FactoryDiscovery::findRequestFactory(),
    Http\Discovery\Psr17FactoryDiscovery::findStreamFactory(),
    $curlOptions
);
初始化 InfluxDB 客户端
$client = new Client([
    "url" => "https://:8086",
    "token" => "my-token",
    "bucket" => "my-bucket",
    "org" => "my-org",
    "httpClient" => $curlClient
]);

查询

通过 QueryApi 查询获取的结果可以是以下格式之一

  1. 原始查询响应
  2. Flux 数据结构：FluxTable、FluxColumn 和 FluxRecord
  3. FluxRecord 流

查询原始

同步执行 Flux 查询并返回未处理的字符串结果

$this->client = new Client([
    "url" => "https://:8086",
    "token" => "my-token",
    "bucket" => "my-bucket",
    "precision" => WritePrecision::NS,
    "org" => "my-org",
    "debug" => false
]);

$this->queryApi = $this->client->createQueryApi();

$result = $this->queryApi->queryRaw(
            'from(bucket:"my-bucket") |> range(start: 1970-01-01T00:00:00.000000001Z) |> last()');

同步查询

同步执行 Flux 查询并返回 FluxTables 数组的结果

$this->client = new Client([
    "url" => "https://:8086",
    "token" => "my-token",
    "bucket" => "my-bucket",
    "precision" => WritePrecision::NS,
    "org" => "my-org",
    "debug" => false
]);

$this->queryApi = $this->client->createQueryApi();

$result = $this->queryApi->query(
            'from(bucket:"my-bucket") |> range(start: 1970-01-01T00:00:00.000000001Z) |> last()');

然后可以轻松地使用 json_encode 进行编码

header('Content-type:application/json;charset=utf-8');
echo json_encode( $result, JSON_PRETTY_PRINT ) ;

查询流

同步执行 Flux 查询并返回 FluxRecord 流

$this->client = new Client([
    "url" => "https://:8086",
    "token" => "my-token",
    "bucket" => "my-bucket",
    "precision" => WritePrecision::NS,
    "org" => "my-org",
    "debug" => false
]);

$this->queryApi = $this->client->createQueryApi();

$parser = $this->queryApi->queryStream(
            'from(bucket:"my-bucket") |> range(start: 1970-01-01T00:00:00.000000001Z) |> last()');

foreach ($parser->each() as $record)
{
    ...
}

参数化查询

InfluxDB Cloud 支持使用 InfluxDB API 动态更改查询中的值的 参数化查询。参数化查询使 Flux 查询更易于重用，并且还可以用于帮助防止注入攻击。

InfluxDB Cloud 将 params 对象插入到名为 params 的 Flux 记录中作为 Flux 查询的一部分。使用点或方括号表示法在 Flux 查询中访问 params 记录中的参数。参数化 Flux 查询仅支持 int、float 和 string 数据类型。要将支持的数据类型转换为其他 Flux 基本数据类型，请使用 Flux 类型转换函数。

参数化查询示例

⚠️ 目前仅支持 InfluxDB Cloud 中的参数化查询，InfluxDB OSS 中目前没有支持。

<?php
require __DIR__ . '/../vendor/autoload.php';

use InfluxDB2\Client;
use InfluxDB2\Model\Query;
use InfluxDB2\Point;
use InfluxDB2\WriteType as WriteType;

$url = "https://us-west-2-1.aws.cloud2.influxdata.com";
$organization = 'my-org';
$bucket = 'my-bucket';
$token = 'my-token';

$client = new Client([
    "url" => $url,
    "token" => $token,
    "bucket" => $bucket,
    "org" => $organization,
    "precision" => InfluxDB2\Model\WritePrecision::NS,
    "debug" => false
]);

$writeApi = $client->createWriteApi(["writeType" => WriteType::SYNCHRONOUS]);
$queryApi = $client->createQueryApi();

$today = new DateTime("now");
$yesterday = $today->sub(new DateInterval("P1D"));

$p = new Point("temperature");
$p->addTag("location", "north")->addField("value", 60)->time($yesterday);
$writeApi->write($p);
$writeApi->close();

//
// Query range start parameter using duration
//
$parameterizedQuery = "from(bucket: params.bucketParam) |> range(start: duration(v: params.startParam))";
$query = new Query();
$query->setQuery($parameterizedQuery);
$query->setParams(["bucketParam" => "my-bucket", "startParam" => "-1d"]);
$tables = $queryApi->query($query);

foreach ($tables as $table) {
    foreach ($table->records as $record) {
        var_export($record->values);
    }
}

//
// Query range start parameter using DateTime
//
$parameterizedQuery = "from(bucket: params.bucketParam) |> range(start: time(v: params.startParam))";
$query->setParams(["bucketParam" => "my-bucket", "startParam" => $yesterday]);
$query->setQuery($parameterizedQuery);
$tables = $queryApi->query($query);

foreach ($tables as $table) {
    foreach ($table->records as $record) {
        var_export($record->values);
    }
}

$client->close();

写入数据

WriteApi 支持将数据同步和批量写入 InfluxDB 2.x。默认情况下使用同步写入。要启用批量写入，可以使用 WriteOption。

$client = new InfluxDB2\Client(["url" => "https://:8086", "token" => "my-token",
    "bucket" => "my-bucket",
    "org" => "my-org",
    "precision" => InfluxDB2\Model\WritePrecision::NS
]);
$write_api = $client->createWriteApi();
$write_api->write('h2o,location=west value=33i 15');

批量写入

写入是分批处理的，可以通过 WriteOptions 进行配置。

use InfluxDB2\Client;
use InfluxDB2\WriteType as WriteType;

$client = new Client(["url" => "https://:8086", "token" => "my-token",
    "bucket" => "my-bucket",
    "org" => "my-org",
    "precision" => InfluxDB2\Model\WritePrecision::NS
]);

$writeApi = $client->createWriteApi(
    ["writeType" => WriteType::BATCHING, 'batchSize' => 1000]);

foreach (range(1, 10000) as $number) {
    $writeApi->write("mem,host=aws_europe,type=batch value=1i $number");
}

// flush remaining data
$writeApi->close();

时间精度

配置默认时间精度

$client = new InfluxDB2\Client(["url" => "https://:8086", "token" => "my-token",
    "bucket" => "my-bucket",
    "org" => "my-org",
    "precision" => \InfluxDB2\Model\WritePrecision::NS
]);

配置每次写入的精度

$client = new InfluxDB2\Client([
    "url" => "https://:8086",
    "token" => "my-token",
    "bucket" => "my-bucket",
    "org" => "my-org",
]);

$writeApi = $client->createWriteApi();
$writeApi->write('h2o,location=west value=33i 15', \InfluxDB2\Model\WritePrecision::MS);

允许的精度值包括

  • WritePrecision::NS 用于纳秒
  • WritePrecision::US 用于微秒
  • WritePrecision::MS 用于毫秒
  • WritePrecision::S 用于秒

配置目标位置

默认的 bucket 和 organization 目标位置通过 InfluxDB2\Client 配置

$client = new InfluxDB2\Client([
    "url" => "https://:8086",
    "token" => "my-token",
    "bucket" => "my-bucket",
]);

但也可以在每次写入时覆盖配置

$client = new InfluxDB2\Client(["url" => "https://:8086", "token" => "my-token"]);

$writeApi = $client->createWriteApi();
$writeApi->write('h2o,location=west value=33i 15', \InfluxDB2\Model\WritePrecision::MS, "production-bucket", "customer-1");

数据格式

数据可以以以下格式写入

  1. 格式化为 InfluxDB 的行协议的 string
  2. 带有键：name、tags、fields 和 time 的 array
  3. 数据点 结构
  4. 上述项目的 Array
$client = new InfluxDB2\Client([
    "url" => "https://:8086",
    "token" => "my-token",
    "bucket" => "my-bucket",
    "org" => "my-org",
    "precision" => InfluxDB2\Model\WritePrecision::US
]);

$writeApi = $client->createWriteApi();

//data in Point structure
$point=InfluxDB2\Point::measurement("h2o")
    ->addTag("location", "europe")
    ->addField("level",2)
    ->time(microtime(true));

$writeApi->write($point);

//data in array structure
$dataArray = ['name' => 'cpu', 
    'tags' => ['host' => 'server_nl', 'region' => 'us'],
    'fields' => ['internal' => 5, 'external' => 6],
    'time' => microtime(true)];

$writeApi->write($dataArray);

//write lineprotocol
$writeApi->write('h2o,location=west value=33i 15');

默认标签

有时在每次度量中存储相同的信息很有用，例如 hostname、location、customer。客户端可以使用静态值、应用程序设置或环境变量作为标签值。

表达式

  • California Miner - 静态值
  • ${env.hostname} - 环境属性
通过 API
$this->client = new Client([
    "url" => "https://:8086",
    "token" => "my-token",
    "bucket" => "my-bucket",
    "precision" => WritePrecision::NS,
    "org" => "my-org",
    "tags" => ['id' => '132-987-655', 
        'hostname' => '${env.Hostname}']
]);

$writeApi = $this->client->createWriteApi(null, ['data_center' => '${env.data_center}']);
    
$writeApi->pointSettings->addDefaultTag('customer', 'California Miner');

$point = Point::measurement('h2o')
            ->addTag('location', 'europe')
            ->addField('level', 2);

$this->writeApi->write($point);

高级用法

检查服务器状态

可以使用 $client->ping(); 方法检查服务器可用性。这相当于 influx ping。

InfluxDB 1.8 API 兼容性

InfluxDB 1.8.0 引入了与 InfluxDB 2.x 兼容的 API，这使得您可以从 InfluxDB 1.x 简单迁移到 InfluxDB 2.x Cloud 或开源版本。

以下是与 InfluxDB 2.x 兼容的 API

有关详细信息，请参阅 InfluxDB 1.8 示例。

InfluxDB 2.x 管理API

InfluxDB 2.x API 客户端使用 influxdb-clients-apigen 生成。源代码位于 InfluxDB2\Service\ 和 InfluxDB2\Model\ 包中。

以下示例展示了如何使用 OrganizationService 和 BucketService 创建一个新的 bucket。

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

use InfluxDB2\Client;
use InfluxDB2\Model\BucketRetentionRules;
use InfluxDB2\Model\Organization;
use InfluxDB2\Model\PostBucketRequest;
use InfluxDB2\Service\BucketsService;
use InfluxDB2\Service\OrganizationsService;

$organization = 'my-org';
$bucket = 'my-bucket';
$token = 'my-token';

$client = new Client([
    "url" => "https://:8086",
    "token" => $token,
    "bucket" => $bucket,
    "org" => $organization,
    "precision" => InfluxDB2\Model\WritePrecision::S
]);

function findMyOrg($client): ?Organization
{
    /** @var OrganizationsService $orgService */
    $orgService = $client->createService(OrganizationsService::class);
    $orgs = $orgService->getOrgs()->getOrgs();
    foreach ($orgs as $org) {
        if ($org->getName() == $client->options["org"]) {
            return $org;
        }
    }
    return null;
}

$bucketsService = $client->createService(BucketsService::class);

$rule = new BucketRetentionRules();
$rule->setEverySeconds(3600);

$bucketName = "example-bucket-" . microtime();
$bucketRequest = new PostBucketRequest();
$bucketRequest->setName($bucketName)
    ->setRetentionRules([$rule])
    ->setOrgId(findMyOrg($client)->getId());

//create bucket
$respBucket = $bucketsService->postBuckets($bucketRequest);
print $respBucket;

$client->close();

通过UDP写入

通过 UDP 发送在执行时间至关重要以避免发送指标到 InfluxDB 时可能出现的延迟（甚至超时）的情况下很有用。
众所周知，通过 UDP 发送不等待响应，这与 TCP（HTTP）不同。

UDP 写入器要求

  1. 安装了 ext-sockets
  2. 由于Influxdb 2.0+版本不支持UDP协议，您需要安装并配置Telegraf插件：[Telegraf插件](https://docs.influxdb.org.cn/telegraf/v1.16/plugins/#socket_listener)
  3. 传递给客户端的额外配置选项：udpPort。您可以选择指定udpHost，否则udpHost将从URL选项解析
  4. 传递给客户端的额外配置选项：ipVersion。您可以选择指定IP版本，默认为IPv4
$client = new InfluxDB2\Client(["url" => "https://:8086", "token" => "my-token",
    "bucket" => "my-bucket",
    "org" => "my-org",
    "precision" => InfluxDB2\Model\WritePrecision::NS,
    "udpPort" => 8094,
    "ipVersion" => 6,
]);
$writer = $client->createUdpWriter();
$writer->write('h2o,location=west value=33i 15');
$writer->close();

删除数据

DefaultService.php支持从InfluxDB桶中删除点。

<?php
/**
 * Shows how to delete data from InfluxDB by client
 */
use InfluxDB2\Client;
use InfluxDB2\Model\DeletePredicateRequest;
use InfluxDB2\Service\DeleteService;

$url = 'https://:8086';
$token = 'my-token';
$org = 'my-org';
$bucket = 'my-bucket';

$client = new Client([
    "url" => $url,
    "token" => $token,
    "bucket" => $bucket,
    "org" => $org,
    "precision" => InfluxDB2\Model\WritePrecision::S
]);

//
// Delete data by measurement and tag value
//
/** @var DeleteService $service */
$service = $client->createService(DeleteService::class);

$predicate = new DeletePredicateRequest();
$predicate->setStart(DateTime::createFromFormat('Y', '2020'));
$predicate->setStop(new DateTime());
$predicate->setPredicate("_measurement=\"mem\" AND host=\"host1\"");

$service->postDelete($predicate, null, $org, $bucket);

$client->close();

更多详细信息请参阅DeleteDataExample.php。

代理和重定向

您可以通过两种方式在代理后配置InfluxDB PHP客户端：

1. 使用环境变量

根据您的服务器URL的方案设置环境变量HTTP_PROXY或HTTPS_PROXY。更多信息请参阅Guzzle文档 - [环境变量](https://docs.guzzlephp.org/en/5.3/clients.html?highlight=PROXY#environment-variables)

2. 通过选项配置客户端以使用代理

您可以在创建客户端时传递一个proxy配置

$client = new InfluxDB2\Client([
  "url" => "https://:8086", 
  "token" => "my-token",
  "bucket" => "my-bucket",
  "org" => "my-org",
  "proxy" => "http://192.168.16.1:10",
]);

更多信息请参阅Guzzle文档 - [代理](https://docs.guzzlephp.org/en/5.3/clients.html?highlight=PROXY#proxy)

重定向

客户端会自动遵循HTTP重定向。您可以通过allow_redirects配置来配置重定向行为

$client = new InfluxDB2\Client([
  "url" => "https://:8086", 
  "token" => "my-token",
  "bucket" => "my-bucket",
  "org" => "my-org",
  "allow_redirects" => false,
]);

更多信息请参阅重定向插件文档 - [允许重定向](https://docs.php-http.org/en/latest/plugins/redirect.html#redirect-plugin)

本地测试

# run unit & integration tests
make test

贡献

欢迎在GitHub上提交错误报告和pull请求：[influxdb-client-php](https://github.com/influxdata/influxdb-client-php)

许可证

此gem根据MIT许可协议作为开源软件提供。