JavaScript 和 InfluxDB 2.0 入门

导航到

Telegraf 拥有 200 多个插件,Telegraf 提供了多种方法来抓取、写入和查询进出 InfluxDB 的数据。但是,有时用户需要执行 Telegraf 功能范围之外的数据收集。也许他们需要收集自定义数据并监控应用程序性能。也许他们想利用外部工具和库为其用户创建精美的基于 Web 的可视化效果。在这些情况下,利用 InfluxDB 的客户端库是有意义的。今天,我们将重点介绍如何将最新的 InfluxDB JavaScript 客户端库与 InfluxDB 2.0 一起使用。

重要提示:InfluxDB v1.8 同时包含用于查询的 Flux 引擎和 InfluxDB v2 HTTP 写入 API。这意味着,如果您还没有准备好今天使用 InfluxDB v2,并且您计划利用新的客户端库,您可以这样做!这些读取和写入兼容性选项允许您面向未来地编写代码!

教程要求和设置

本教程在 MacOS 系统上执行,该系统通过 Homebrew 安装了 Node,根据 Node.js 文档

#update brew before installing
brew update 
brew install node 
#check to make sure you have successfully installed Node and NPM
node -v
npm -v

开始使用 InfluxDB v2 JavaScript 客户端的最简单方法是克隆 examples 目录,该目录位于 influxdb-client-js repo 中。

成功克隆目录后,导航到该目录并运行

npm install

index.htmlenv.js 中指定您的授权参数。您需要指定 org、bucket 和 token。现在我们准备好在浏览器中使用客户端,通过

npm run browser

Npm 应该会打开 http://localhost:3001/examples/index.html,您将在其中被提示以行协议写入数据点,并通过 UI 查询它。您还可以载入用户并执行 API 健康检查。

授权参数

InfluxDB v2

为了使用客户端,您需要收集以下参数

InfluxData UI example

InfluxData UI 示例。Bucket 和 Token 可以在“Load Data”选项卡下找到。Org 名称(如“my-org”)可以在左上角“Load Data”标题下方找到。

InfluxDB v1.8 及更高版本

如果您计划将此新客户端库与 InfluxDB 1.8 或更高版本一起使用,以下是关于收集所需授权参数的一些重要提示

  • Bucket 名称:InfluxDB v1.x 中没有 Bucket 的概念。但是,bucket 只是数据库名称及其保留策略的组合。因此,您可以通过提供 InfluxDB 1.x 数据库名称和保留策略(以正斜杠 (/) 分隔)来指定它。如果您不提供保留策略,则使用默认保留策略。

例如:bucket 名称 telegraf/1week 允许您写入 InfluxDB 1.x 数据库,该数据库名为“telegraf”,保留策略名为“1week”。同样,telegraf/ 或 telegraf 允许您写入 InfluxDB 1.x 数据库,该数据库名为“telegraf”,并使用默认保留策略(通常为 autogen)。

  • Token:在 InfluxDB v2 中,API Token 用于访问平台及其所有功能。InfluxDB v1.x 在访问 HTTP API 时使用用户名和密码组合。提供您的 InfluxDB 1.x 用户名和密码,以冒号 (:) 分隔以表示 token。例如:username:password
  • Org:org 参数在与 InfluxDB v1.x 的兼容模式下被忽略,可以留空。

InfluxDB JavaScript client examples

使用 JavaScript 客户端库写入 InfluxDB v2

您在示例演示中写入的点被硬编码为包含 measurement、tag key 和 tag value。代码生成以下行协议 temperature,example=index.html value=28.7,使用以下函数

function writeExample(value) {
       const writeApi = influxDB.getWriteApi(org, bucket)
       // setup default tags for all writes through this API
       writeApi.useDefaultTags({location: 'browser'})

       log('\n*** WRITE ***')
       const point1 = new Point('temperature')
         .tag('example', 'index.html')
         .floatField('value', value)
       writeApi.writePoint(point1)
       log(` ${point1}`)
// flush pending writes and close writeApi
       writeApi
         .close()
         .then(() => {
           log('WRITE FINISHED')
         })
         .catch(e => {
           log('WRITE FAILED', e)
         })
     }

您将您的 org 和 bucket 提供给 getWriteApi 方法,该方法创建一个 WriteApi。此方法还允许您包含精度参数以支持 多种时间戳精度,默认精度为 ns。

有几种数据格式化方法可以将行协议写入 InfluxDB。

  • useDefaultTags 方法指示 API 使用默认标签,默认标签由用户在写入点时定义。
  • writeRecord 方法接受单个行协议字符串。
  • writeRecords 方法接受行协议字符串数组。

有两种方法可以将行协议数据写入 InfluxDB。

使用 JavaScript 客户端库查询 InfluxDB v2

InfluxDB v2

既然我们已经将一些随机温度数据写入了 InfluxDB 实例,我们就可以查询它了。

function queryExample(fluxQuery) {
       log('\n*** QUERY ***')
       const queryApi = influxDB.getQueryApi(org)
       queryApi.queryRows(fluxQuery, {
         next(row, tableMeta) {
           const o = tableMeta.toObject(row)
           if (o.example){
             // custom output for example query
             log(
               `${o._time} ${o._measurement} in '${o.location}' (${o.example}): ${o._field}=${o._value}`
             )
           } else {
             // default output
             log(JSON.stringify(o, null, 2))
           }
         },
         error(error) {
           log('QUERY FAILED', error)
         },
         complete() {
           log('QUERY FINISHED')
         },
       })
     }

getQueryApi 方法为提供的 org 创建一个 QueryApi。queryRows 方法执行查询并以 annotated csv 格式返回行,其中 console.log(o) 产生

{result: "_result", table: "0", _start: "1970-01-01T00:00:00Z", _stop: "2020-04-03T20:39:23.761184Z", _time: "2020-04-03T18:31:33.95Z", …}
result: "_result"
table: "0"
_start: "1970-01-01T00:00:00Z"
_stop: "2020-04-03T20:39:23.761184Z"
_time: "2020-04-03T18:31:33.95Z"
_value: 29.9
_field: "value"
_measurement: "temperature"
example: "index.html"
location: "browser"
__proto__: Object

InfluxDB v1.8 或更高版本

上面的示例同样适用,但连接 URL 不同。对于 Flux 查询端点,请使用:http://<hostname>:8086/api/v2/query

健康检查

通过 API 监控数据库实例的健康状况是构建可信管道的关键步骤。此浏览器示例还包含健康检查

const {InfluxDB} = require('@influxdata/influxdb-client')
const {HealthAPI} = require('@influxdata/influxdb-client-apis')
const {url, token} = require('./env')

console.log('*** HEALTH CHECK ***')
const influxDB = new InfluxDB({url, token})
const healthAPI = new HealthAPI(influxDB)

healthAPI
  .getHealth()
  .then((result /* : HealthCheck */) => {
    console.log(JSON.stringify(result, null, 2))
    console.log('\nFinished SUCCESS')
  })
  .catch(error => {
    console.error(error)
    console.log('\nFinished ERROR')
  })

要获取实例的健康状况,您需要

  • 创建一个新的 InfluxDB 对象
  • 从 InfluxDB 对象创建一个 HealthAPI
  • 使用 getHealth 方法返回 API 的状态(有关更多详细信息,请参阅 API 文档

载入

最后,此演示包括用户载入示例。简单快速的用户载入使应用程序开发人员能够为希望访问其时间序列数据的用户提供低门槛的采用方式。为了实现载入工具,您必须将用户的用户名和密码提供给 ./env

const setupApi = new SetupAPI(new InfluxDB({url}))

setupApi
  .getSetup()
  .then(async ({allowed}) => {
    if (allowed) {
      await setupApi.postSetup({
        body: {
          org,
          bucket,
          username,
          password,
          token,
        },
      })
      console.log(`InfluxDB '${url}' is now onboarded.`)
    } else {
      console.log(`InfluxDB '${url}' has been already onboarded.`)
    }
    console.log('\nFinished SUCCESS')
  })
  .catch(error => {
    console.error(error)
    console.log('\nFinished ERROR')
  })

与健康检查类似,为了载入新用户,您需要

  • 创建一个新的 InfluxDB 对象
  • 从 InfluxDB 对象创建一个 SetupAPI
  • 使用 getSetup 方法来设置初始用户、org 和 bucket

关于 InfluxDB v2 JavaScript 客户端的最后想法

重要的是要注意,除了浏览器环境之外,Node 环境也受支持。此外,我想分享一些可能对 JavaScript 开发人员有价值的额外资源。如果您喜欢 InfluxDB UI 并想利用 复杂的时间序列数据可视化算法,我建议您查看 Giraffe 和 Clockface。Giraffe 是一个开源的基于 React 的可视化库,用于实现 InfluxDB Cloud 2.0 用户界面 (UI)。Clockface 是一个开源的 React 和 Typescript UI 工具包,用于构建 InfluxDB v2 UI 和其他时间序列可视化应用程序。

我希望本教程能帮助您开始 JavaScript 和 InfluxDB 之旅。与往常一样,我很乐意听取您的想法并回答您的任何问题。请在我们的 社区站点Slack 频道上发布它们。