DataPoints - 時系列データ(データポイント形式)へのアクセスオブジェクト¶
データポイントリソースへのアクセスAPIを提供します。 データポイントは、時系列データをバイナリフォーマットで格納するリソースです。
Request Methods¶
警告
以下のアクセスオブジェクトは、必ず client の data_points を使用して生成してください。
client = intdash.Client(...)
client.data_points.list(edge_name='test_edge', start='2020/07/01 09:00+09:00', end='2020/07/01 10:00+09:00')
- class DataPoints(...)[ソース]¶
時系列データ(データポイントリソース)へのアクセスオブジェクトです。
- list(start, end, measurement_uuid=None, edge_uuid=None, edge_name=None, id_queries=None, labels=None, limit=None, iterator=False, exit_on_error=False)[ソース]¶
時系列データ(データポイント)のリストを取得します。
- パラメータ
start (pandas.Timestamp) -- 取得対象範囲の始点
end (pandas.Timestamp) -- 取得対象範囲の終点
measurement_uuid (str) -- 取得元の計測のUUID
edge_uuid (str) -- 取得元のエッジUUID
edge_name (str) -- 取得元のエッジ名
id_queries (list[IdQuery]) -- 取得対象のidのリスト
labels (list[str]) -- 取得対象のラベル名
limit (int) -- 最大取得件数
iterator (bool) -- Trueの場合、イテレータを生成します
exit_on_error (bool) -- Trueの場合、取得中にエラーが発生すると処理を中断し、中断前までのDataResponseのリストを返します
- 戻り値
データオブジェクト
- 戻り値の型
list[DataResponse]
サンプル
出力されたintdash.DataResponseの data_payload はバイナリデータです。使用する data_type に合わせて、 intdash.data.Data の from_payload() を使用することで、物理値を得ることができます。
>>> dps = client.data_points.list( measurement_uuid=sample_measurement.uuid, id_queries=[ intdash.IdQuery( data_type=intdash.DataType.int.value, data_id='test' ) ], start=timeutils.str2timestamp("2020-01-01T00:00:00.000000Z"), end=timeutils.str2timestamp("2020-01-02T00:00:00.000000Z"), )
>>> print(intdash.data.Int.from_payload(dps[0].data_payload)) data_type: int data_id: test value: 2
注釈
measurement_uuid
edge_uuid
edge_name
はいずれか1つを指定してください。 同時に指定された場合、measurement_uuid
>edge_uuid
>edge_name
の優先順位で参照し、低順位のものは無視されます。注釈
labels
とid_queries
両方を指定した場合、双方いずれかにあてはまるデータすべてが対象となります。 (ただしlabels
については、別途「信号定義」を登録する必要があります)注釈
limit
を指定しない場合、指定範囲の全データを取得します。取得データの容量が大きい場合、limit
に取得数の上限を指定しiterator
をTrue
にすることで、 上限ごとに繰り返し取得処理を実行するイテレーターを使用することができます。詳しくは、 チュートリアル の 時系列データを取得する を参考にしてください。注釈
サーバー側の取得処理にて例外が発生すると、例外メッセージを格納したDataResponseが出力され、処理自体は正常に終了します (以下サンプル参照)。この時、Unitの
data_type
はStringです。 例外発生時に処理を中断したい場合、exit_on_error
にTrue
を指定してください。サンプル
以下は、データ取得時に例外が発生した場合のサンプルです。 エラーメッセージがDataResponseに格納されています。エラーメッセージを格納したDataResponseの data_type はStringです。 data_id には、エラーが発生したエンドポイントのnamespaceが出力されます。 DataResponseの内容を確認することで、再取得や原因究明に使用できます。
>>> dps = lc.data_points.list( measurement_uuid=sample_measurement.uuid, labels=['nmea'], start=sample_measurement.basetime, end=sample_measurement.basetime + pd.Timedelta(seconds=10) )
>>> import json >>> for p in dps: if 'error' in p.data_id: print(p) data = intdash.data.String.from_payload(p.data_payload) error_message = json.loads(data.value)['error_description'] raise ValueError(f'contains failed data: {error_message}') # time: 2020-06-23T05:08:25.676942+00:00 # measurement_uuid: 3b5b9bed-d509-4198-aea0-54ee714f7a5b # data_type: 10 # channel: 1 # data_id: intdash/measurement/get/data/error # data_payload: b'error{"error":"converted_error","error_description":"Error occurred in signal conversion","error_extra":{"signal_channel":1,"signal_data_id":"GPRMC","signal_data_type":2,"signal_label":"nmea"}}' ValueError: contains failed data: Error occurred in signal conversion
- store(measurement_uuid, data_points, serial_number=0, final=True)[ソース]¶
時系列データ(データポイント)をサーバーへ保存します。
- パラメータ
measurement_uuid (str) -- 保存先の計測のUUID
data_points (list[DataPoint]) -- 保存するデータポイントオブジェクトのリスト
serial_number (int) -- セクションの通し番号
final (bool) -- 最終フラグ
サンプル
DataPoint の data_payload には、バイナリデータを指定します。バイナリデータは、使用する data_type に合わせて intdash.data.Data の to_payload() を使用することにより作成できます。
>>> data_points = [ DataPoint( elapsed_time=pd.Timedelta(seconds=0) , data_type=DataType.int.value, channel=1, data_payload=intdash.data.Int(data_id='test', value=2).to_payload() ) ]
>>> client.data_points.store( measurement_uuid=sample_measurement.uuid, data_points=data_points )
注釈
一回の処理で指定できる
data_points
の容量は2GBまでです。2GBを超える場合は、store()
を複数回実行してください。
Request Params¶
- class DataPoint(...)[ソース]¶
DataPointリソースを表すオブジェクトです。データをサーバーに保存する際に使用します。
- elapsed_time¶
データの経過時間
- Type
pandas.Timedelta
- channel¶
チャンネル番号
- Type
int
- data_payload¶
データのペイロード
- Type
bytes
Response¶
データ型を示すオブジェクトについては、別途 時系列データオブジェクト を参照してください。