Javascript / node.jsライブラリ ambient-lib

Javascript / node.jsでAmbientにデータを送受信するライブラリです。

Javascript

ライブラリの読み込み

AmbientのJavascriptライブラリはunpkg.comというサイト(CDN)に登録されています。Ambientライブラリを使うにはaxiosとqsというライブラリも必要になるので、JavascriptでAmbientにデータを送受信するには、次のように3つのライブラリを読み込みます。

<script src="https://unpkg.com/axios/dist/axios.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/qs/6.10.1/qs.min.js" integrity="sha512-aTKlYRb1QfU1jlF3k+aS4AqTpnTXci4R79mkdie/bp6Xm51O5O3ESAYhvg6zoicj/PD6VYY0XrYwsWLcvGiKZQ==" crossorigin="anonymous"></script>
<script src="https://unpkg.com/[email protected]/lib/ambient-lib.js"></script>

Ambientへのデータ送信

Ambientにデータを送信するには、まずAmbientオブジェクトの初期化をおこない、次にsendメソッドで送信します。

    am = new Ambient(チャネルId, ライトキー);
    am.send({d1: 値1, d2: 値2, ...}, function(response) {
        console.log(response.status);
    });

AmbientオブジェクトはチャネルId、ライトキー、リードキーを指定して初期化します。送信のみおこなう場合はリードキーはなくても構いません。

    am = new Ambient(チャネルId, ライトキー[, リードキー]);

データ送信はsendメソッドでおこないます。

    am.send(データ, コールバック関数[, timeout]);

引数

データ: 次のようなJSON形式で、キーはd1からd8のいずれかを指定します。lat(緯度)とlng(経度)でデータと共に位置情報を送ることもできます。位置情報をつけてデータを送ると、Ambientで地図チャートで見ると地図上にデータが表示されます。詳しくは「データに位置情報を付加する」をご覧ください。

また、cmntでデータにコメントをつけて送ることもできます。詳しくは「リストチャート、表示/非表示の制御、コメント」をご覧ください。

    var data = {d1: 1.1, d2: 2.2};
    var data = {d1: 1.1, d2: 2.2, lat: 35.5, lng: 139.5};  // 位置情報をつけて送る
    var data = {d1: 1.1, d2: 2.2, cmnt: '風が吹いた'};   // コメントをつけて送る

コールバック関数: データ送信後に呼ばれるコールバック関数です。パラメータはaxiosモジュールのコールバック関数のパラメータと同じです。response.statusで送信のステータスが確認できます。
timeout: タイムアウト値（ミリ秒）。省略時は30秒です。

この形式でデータを送信した場合、Ambientはデータを受信した時刻を合わせて記録します。次のようにデータを測定した時刻を指定することもできます。

    var data = {created: 'YYYY-MM-DD HH:mm:ss.sss', d1: 1.1, d2: 2.2};

また、次のように複数のデータを一括で送信することもできます。

    var data = [
        {created: '2021-05-03 12:00:00', d1: 1.1, d2: 2.1},
        {created: '2021-05-03 12:01:00', d1: 1.5, d2: 3.8},
        {created: '2021-05-03 12:02:00', d1: 1.0, d2: 0.8}
    ];

Ambientからのデータ読み込み

データを読み込むには、Ambientオブジェクトの初期化をおこない、次にreadメソッドで読み込みます。

    am = new Ambient(チャネルId, ライトキー, リードキー);
    am.read(パラメータ, function(response) {
        console.log(response.status);
        console.log(response.data);
    });

データの読み込みにはデータ件数を指定する方法、日付を指定する方法、期間を指定する方法があります。

件数を指定してデータを読み込む

    am.read({n: 件数[, skip: スキップ件数]}, function(response) {
        console.log(response.status);
        console.log(response.data);
    }[, timeout]);

引数

n: 読み込むデータ件数を指定します。最新のn件のデータが読み込まれます。
skip: スキップ件数。最新からスキップ件のデータを読み飛ばし、その先n件のデータが読み込まれます。
コールバック関数: データ送信後に呼ばれるコールバック関数。パラメータはaxiosモジュールのコールバック関数のパラメータと同じです。response.statusで送信のステータスが確認でき、読み込んだデータはresponse.dataに次のようなJSON形式の配列でセットされます。

    [
        {created: '2021-05-03T15:01:48.000Z', d1: 数値, d2: 数値, d3: 数値},
        {created: '2021-05-03T15:06:47.000Z', d1: 数値, d2: 数値, d3: 数値},
        …
    ];

データの生成時刻’created’は協定世界時(UTC)で表示されます。データは生成時刻の昇順(古いものから新しいものへ)で並びます。

timeout: タイムアウト値（ミリ秒）。省略時は30秒です。

日付を指定してデータを読み込む

    am.read({date: 'YYYY-mm-dd'}, function(response) {
        console.log(response.status);
        console.log(response.data);
    }[, timeout]);

引数

date: ’YYYY-mm-dd’: 指定した日付のデータを読み込みます。

期間を指定してデータを読み込む

    am.read({start: 'YYYY-mm-dd HH:MM:SS', end: 'YYYY-mm-dd HH:MM:SS'}, function(response) {
        console.log(response.status);
        console.log(response.data);
    }[, timeout]);

引数

start: ’YYYY-mm-dd HH:MM:SS’:
end: ’YYYY-mm-dd HH:MM:SS’:
startからendまでの期間のデータを読み込みます。

Node.js

インストール

ライブラリはnode.jsのパッケージ管理サービスnpmに登録してあり、次のようにnpmコマンドを使ってインストールできます。

    $ npm install ambient-lib

ライブラリの読み込み

ライブラリの読み込みは次のようにおこないます。

    var Ambient = require('ambient-lib');

Ambientへのデータ送受信

Javascriptと同様に、Ambientオブジェクトの初期化をおこない、次にsendメソッドで送信、readメソッドで受信します。使い方もJavascriptと同じです。

    am = new Ambient(チャネルId, ライトキー);
    am.send({d1: 値1, d2: 値2, ...}, function(response) {
        console.log(response.status);
    });

    am.read(パラメータ, function(response) {
        console.log(response.status);
        console.log(response.data);
    });

データを送受信した際、「TypeError: utf8 is not a function」というエラーがでることがあります。node.jsのバージョンが古いのが原因です。node.jsをv6以上にバージョンアップしてください。