Pythonライブラリー

AmbientのPythonライブラリーです。Ambientにデーターを送信する機能と、Ambientに蓄積されたデーターを読み込む機能があります。

インストール

ライブラリーはGithubに公開しました。Githubから次のようにライブラリーをインストールできます。

$ pip3 install git+https://github.com/AmbientDataInc/ambient-python-lib.git
$ pip3 list | grep ambient
  ambient      0.1.6

ライブラリーの読み込み

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

import ambient

Ambientへのデーター送信

最初にチャネルIdとライトキーを指定してAmbientのインスタンスを作り、send()メソッドでデーターを送信します。

am = ambient.Ambient(チャネルId, ライトキー[, リードキー[, ユーザーキー]])
r = am.send({'d1': 数値, 'd2': 数値}[, timeout = timeout])

パラメーター

データーは上記のような辞書形式で渡します。キーは’d1’から’d8’までのいずれかを指定します。この形式でデーターを送信した場合、Ambientはデーターを受信した時刻を合わせて記録します。次のようにデーターを測定した時刻を指定することもできます。

r = am.send({'created': 'YYYY-MM-DD HH:mm:ss.sss', 'd1': 1.1, 'd2': 2.2})

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

data = [
    {'created': '2017-02-18 12:00:00', 'd1': 1.1, 'd2': 2.1},
    {'created': '2017-02-18 12:01:00', 'd1': 1.5, 'd2': 3.8},
    {'created': '2017-02-18 12:02:00', 'd1': 1.0, 'd2': 0.8}
]
r = am.send(data)

timeoutはサーバー接続のタイムアウト値（秒）です。省略時は30.0秒になります。

戻り値

PythonのRequestsの戻り値と同じものが返ります。特に

r.status_code

に、サーバーにデーターを送信したときの結果(ステータスコード)がセットされます。送信に成功していれば200がセットされます。

例外

ambientライブラリーは内部でrequests(MicroPythonの場合はurequests)を使って処理しています。

requestsは通信エラーがあったとき、例外を発生させます。requestsが発生させる例外はrequestsドキュメントの「エラーと例外」に書かれています。それによると、原因によりConnectionError、HTTPError、Timeout、TooManyRedirectsが発生し、それらをまとめてrequests.exceptions.RequestExceptionで例外処理できるとのことです。

ambientライブラリーでデーターを送受信する時は、次のように例外を受けることができます。

import ambient
import requests

    try:
        ret = am.send(data)
        print('sent to Ambient (ret = %d)' % ret.status_code)
    except requests.exceptions.RequestException as e:
        print('request failed: ', e)

Ambientからのデーター読み込み

データー送信と同様に最初にチャネルIdとライトキー、リードキーを指定してインスタンスを作ります。読み込みしかしない場合、ライトキーは”を指定しても大丈夫です。

am = ambient.Ambient(チャネルId, ライトキー, リードキー[, ユーザーキー])

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

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

d = am.read(n=件数[, skip=スキップ件数[, timeout = timeout]])

パラメーター

n: 読み込むデーター件数を指定します。最新のn件のデーターが読み込まれます。
skip: スキップ件数。最新からスキップ件のデーターを読み飛ばし、その先n件のデーターが読み込まれます。
timeout:サーバー接続のタイムアウト値（秒）。省略時は30.0秒。

戻り値

次のような辞書形式(JSON形式)の配列が返されます。

[
    {'created': '2017-02-25T15:01:48.000Z', 'd1': 数値, 'd2': 数値, 'd3': 数値},
    {'created': '2017-02-25T15:06:47.000Z', 'd1': 数値, 'd2': 数値, 'd3': 数値},
    ...
]

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

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

d = am.read(date='YYYY-mm-dd'[, timeout = timeout])

パラメーター

date=’YYYY-mm-dd’: 指定した日付のデーターを読み込みます。
timeout:サーバー接続のタイムアウト値（秒）。省略時は30.0秒。

戻り値

件数を指定した場合と同じ辞書形式の配列が返されます。

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

d = am.read(start='YYYY-mm-dd HH:MM:SS', end='YYYY-mm-dd HH:MM:SS'[, timeout = timeout])

パラメーター

start=’YYYY-mm-dd HH:MM:SS’:
end=’YYYY-mm-dd HH:MM:SS’:
startからendまでの期間のデーターを読み込みます。
timeout:サーバー接続のタイムアウト値（秒）。省略時は30.0秒。

戻り値

件数を指定した場合と同じ辞書形式の配列が返されます。

チャネル情報の取得

データー名やチャネルの位置情報など、Ambientで指定したチャネル情報を取得します。

prop = am.getprop([timeout = timeout])

パラメーター

timeout:サーバー接続のタイムアウト値（秒）。省略時は30.0秒。

戻り値

チャネル情報が辞書形式で返されます。d1からd8までのデーターに設定した名前は

prop['d1']['name']

で参照できます。

ダウンロードデーターの扱い

Ambientからライブラリーでデーターを読み込む方法とは別に、チャネルに保存したデーターをダウンロードし、そのファイルをPythonで読み込むこともできます。

次のようにするとチャネルに保存したデーターがcsv形式でファイルにダウンロードされます。

ファイルのエンコーディングはUTF-8形式で、先頭にバイトオーダーマーク (0xEF 0xBB 0xBF) というデーターが付与されています。

Pythonでこのファイルを読み込む時は、次のようにします。encoding=’utf_8_sig’を指定してください。

import csv
csv_file = open('./data100.csv', 'r', encoding='utf_8_sig')
f = csv.reader(csv_file)

ダウンロードしたデーターの先頭行は次のような形式です。チャネル設定でデーター名を設定している場合はd1〜d8がデーター名になります。

created,d1,d2,d3,d4,d5,d6,d7,d8

encoding=’utf_8_sig’を指定しないと、0xEF 0xBB 0xBFがデーターとして扱われ、次のようになってしまいます。

0xEF 0xBB 0xBF created,d1,d2,d3,d4,d5,d6,d7,d8

先頭行をprintすると’created’の前にバイトオーダーマークがついてしまっています。扱いにくいので、encoding=’utf_8_sig’を指定するようにしてください。

head = next(f)
print(head)
# ['\ufeffcreated', 'd1', 'd2', 'd3', 'd4', 'd5', 'd6', 'd7', 'd8']

Python pandas で読み込む時は、次のようにします。ここでもencoding=’utf_8_sig’を指定してください。

import pandas as pd
df = pd.read_csv('./data100.csv', encoding='utf_8_sig')

encoding=’utf_8_sig’を指定しないと、’created’の前にバイトオーダーマークがついてしまいます。カラムを確認すると、’created’と表示されるのですが、実際には頭にバイトオーダーマークがついています。必ずencoding=’utf_8_sig’を指定してください。

df.columns
# Index(['created', 'd1', 'd2', 'd3', 'd4', 'd5', 'd6', 'd7', 'd8'], dtype='object')
df['created']
# KeyError: 'created'

コードサンプル

コードサンプルは「AmbientのデーターをPythonで扱う」をご覧ください。