Имея более 200 плагинов, Telegraf имеет широкий спектр методов очистки, записи и запроса данных в InfluxDB и обратно. Однако иногда пользователям необходимо выполнить сбор данных за пределами возможностей Telegraf. Возможно, им нужно собирать пользовательские данные и отслеживать производительность приложений. Возможно, они хотят воспользоваться внешними инструментами и библиотеками для создания красивых веб-визуализаций для своих пользователей. В этих случаях имеет смысл воспользоваться преимуществами клиентских библиотек InfluxDB. Сегодня мы сосредоточимся на том, как использовать новейшую клиентскую библиотеку JavaScript InfluxDB с InfluxDB 2.0.

Важное примечание: InfluxDB v1.8 включает в себя как движок Flux для запросов, так и API записи HTTP InfluxDB v2. Это означает, что если вы не совсем готовы использовать InfluxDB v2 сегодня и планируете использовать новые клиентские библиотеки, вы можете это сделать! Эти параметры совместимости для чтения и записи позволяют вам защитить свой код в будущем!

Требования к учебнику и настройка

Это руководство было выполнено в системе MacOS с Node, установленным через Homebrew, в соответствии с документацией 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

Самый простой способ начать работу с JavaScript-клиентом InfluxDB v2 — клонировать каталог примеров в репозиторий influxdb-client-js.

После того, как вы успешно клонировали каталог, перейдите к нему и запустите:

npm install

Укажите параметры авторизации в index.html и env.js. Вам нужно будет указать организацию, сегмент и токен. Теперь мы готовы начать использовать клиент в браузере:

npm run browser

Npm должен открыть http://localhost:3001/examples/index.html, где вам будет предложено написать точку данных в протоколе строки и запросить ее через пользовательский интерфейс. Вы также сможете зарегистрировать пользователя и выполнить проверку работоспособности API.

Параметры авторизации

ИнфлюксДБ v2

Чтобы использовать клиент, вам необходимо собрать следующие параметры:

InfluxDB v1.8 и выше

Если вы планируете использовать эту новую клиентскую библиотеку с InfluxDB 1.8 или более поздней версии, вот несколько важных советов по сбору необходимых параметров авторизации:

  • Имя корзины. В InfluxDB v1.x нет концепции корзины. Однако ведро — это просто комбинация имени базы данных и ее политики хранения. Таким образом, вы можете указать это, указав имя базы данных InfluxDB 1.x и политику хранения, разделенные косой чертой (/). Если вы не укажете политику хранения, будет использоваться политика хранения по умолчанию.

Например: имя сегмента telegraf/1week позволяет вам записать базу данных InfluxDB 1.x с именем «telegraf» с политикой хранения с именем «1week». Точно так же telegraf/ или telegraf позволяют вам писать в базу данных InfluxDB 1.x с именем «telegraf» и политикой хранения по умолчанию (обычно autogen).

  • Токен. В InfluxDB v2 токены API используются для доступа к платформе и всем ее возможностям. InfluxDB v1.x использует комбинацию имени пользователя и пароля при доступе к HTTP API. Укажите свое имя пользователя и пароль InfluxDB 1.x, разделенные двоеточием (:), чтобы обозначить токен. Например: username:password
  • Org: параметр org игнорируется в режиме совместимости с InfluxDB v1.x и может быть оставлен пустым.

Запись в InfluxDB v2 с помощью клиентской библиотеки JavaScript

Точка, которую вы пишете в демонстрационном примере, жестко закодирована и включает измерение, ключ тега и значение тега. Код генерирует следующий протокол строки 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)
         })
     }

Вы предоставляете свою организацию и корзину методу getWriteApi, который создает WriteApi. Этот метод также позволяет включать параметр точности для поддержки несколько меток времени с точностью, значение по умолчанию равно ns.

Существует несколько методов форматирования данных для записи линейного протокола в InfluxDB.

  • Метод useDefaultTags указывает API использовать теги по умолчанию, определенные пользователем при записи точек.
  • Метод writeRecord принимает одну строку протокола.
  • Метод writeRecords принимает массив строк строкового протокола.

Существует два метода записи данных линейного протокола в InfluxDB.

  • writePoint поддерживает одну запись.
  • writePoints поддерживает несколько записей.

Запрос InfluxDB v2 с помощью клиентской библиотеки JavaScript

ИнфлюксДБ 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 создает QueryApi для предоставленного org. Метод queryRows выполняет запрос и возвращает строки в аннотированном 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
  • Создайте HealthAPI из объекта InfluxDB.
  • Используйте метод 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
  • Создайте SetupAPI из объекта InfluxDB.
  • Используйте метод getSetup для настройки начального пользователя, организации и корзины.

Заключительные мысли о JavaScript-клиенте InfluxDB v2

Важно отметить, что в дополнение к средам браузера также поддерживаются среды Node. Кроме того, я хочу поделиться некоторыми дополнительными ресурсами, которые могут быть полезны разработчикам JavaScript. Если вам нравится пользовательский интерфейс InfluxDB и вы хотите воспользоваться сложными алгоритмами визуализации данных временных рядов, я рекомендую проверить Giraffe и Clockface. Giraffe — это библиотека визуализации на основе React с открытым исходным кодом, используемая для реализации пользовательского интерфейса (UI) InfluxDB Cloud 2.0. Clockface — это набор пользовательского интерфейса React и Typescript с открытым исходным кодом для создания пользовательского интерфейса InfluxDB v2 и других приложений визуализации временных рядов.

Я надеюсь, что это руководство поможет вам начать знакомство с JavaScript и InfluxDB. Как всегда, я хотел бы услышать ваши мысли и ответить на любые ваши вопросы. Пожалуйста, разместите их на нашем сайте сообщества или на канале Slack.