DataStore V2 API

sakura.ioでは、保存されたデータの呼び出し方法として「DataStore V2 API」を提供しています。 データ保存機能(DataStore V2)に蓄積されたデータは、APIを介して一括取得する事ができます。

データ方向 追加費用 使用プロトコル
sakura.io→外部 一部プラン有償 HTTPS

概要

外部システムやWebブラウザから、用意されているAPIのエンドポイントに対して、HTTPSリクエストを送信することで、DataStore V2に保存されたメッセージを参照することができます。 なお、DataStore V2 APIには用途に応じて3つのAPIが用意されています。

/datastore/v2/channels では、モジュールから送信されたデータのみが最初からフィルタされており、さらに、特定のチャンネルのみのメッセージを得ることができます。 一方で、 /datastore/v2/messages では、 すべてのタイプのメッセージ が取得でき、プロジェクト全体の状況を確認することができます。/messagesのデータからメタ情報を除いたデータは /datastore/v2/messages-bulk を使って任意の形式でダウンロードすることもできます。

また、コントロールパネルからはCSVファイルのダウンロードも可能です。

API名 役割 想定利用ケース
/channels 特定デバイスから送信された特定チャンネルのデータのみを取得する 特定チャンネルのデータに注目した処理や分析をする
/messages チャンネルのデータだけでなく、モジュールの接続開始やオプション機能由来のデータ等も取得する 同一のメッセージに含まれる複数チャンネルのデータの相関関係含めて活用する
/messages-bulk メッセージを一括でファイルとしてダウンロードする メッセージデータをJSONファイルとして外部のツールに取り込む

指定可能なオプション

各APIにはいくつかのオプションが存在します。これらをURLパラメータとして指定することで、任意の条件に適合するメッセージのみ抽出して参照することができます。 APIごとに使用可能なオプションを以下に示します。

/channels

パラメータ名 役割 指定 デフォルト値 備考
token 対象プロジェクトの指定および認証 必須 無し 指定がない場合、 invalid token エラーを返します
module 対象モジュールの指定 必須 無し 指定がない場合、 invalid field Module エラーを返します
limit 1リクエストで取得する最大数 任意 200件 1件~2,000件で指定可能、範囲を超えた場合は invalid field Limit エラーを返します
order チャンネルデータのソート順 任意 DESC(降順) 指定する場合、DESCもしくはASCのいずれかを指定します
after 取得する時間範囲の指定(開始日時) 任意 無し 指定にはRFC3339形式(例:YYYY-MM-DDThh:mm:ss+hh:mm)を使用します
before 取得する時間範囲の指定(終了日時) 任意 無し 指定にはRFC3339形式(例:YYYY-MM-DDThh:mm:ss+hh:mm)を使用します
cursor 複数回に分けたリクエストの識別子 任意 無し limitを超えるデータがあった場合、指定することで残りのチャンネルデータをリクエストします
channel 対象となるチャンネル番号指定 任意 0 指定可能なチャンネルは1つのみとなります

/messages

パラメータ名 役割 指定 デフォルト値 備考
token 対象プロジェクトの指定および認証 必須 無し 指定がない場合、 invalid token エラーを返します
module 対象モジュールの指定 任意 全件 指定がない場合、 invalid field Module エラーを返します
limit 1リクエストで取得する最大数 任意 200件 1件~2,000件で指定可能、範囲を超えた場合は invalid field Limit エラーを返します
order メッセージのソート順 任意 DESC(降順) 指定する場合、DESCもしくはASCのいずれかを指定します
after 取得する時間範囲の指定(開始日時) 任意 無し 指定にはRFC3339形式(例:YYYY-MM-DDThh:mm:ss+hh:mm)を使用します
before 取得する時間範囲の指定(終了日時) 任意 無し 指定にはRFC3339形式(例:YYYY-MM-DDThh:mm:ss+hh:mm)を使用します
cursor 複数回に分けたリクエストの識別子 任意 無し limitを超えるデータがあった場合、指定することで残りのメッセージをリクエストします

/messages-bulk

パラメータ名 役割 指定 デフォルト値 備考
token 対象プロジェクトの指定および認証 必須 無し 指定がない場合、 invalid token エラーを返します
module 対象モジュールの指定 任意 全件 指定がない場合、 invalid field Module エラーを返します
limit 1リクエストで取得する最大数 任意 200件 1件~2,000件で指定可能、範囲を超えた場合は invalid field Limit エラーを返します
order メッセージのソート順 任意 DESC(降順) 指定する場合、DESCもしくはASCのいずれかを指定します
after 取得する時間範囲の指定(開始日時) 任意 無し 指定にはRFC3339形式(例:YYYY-MM-DDThh:mm:ss+hh:mm)を使用します
before 取得する時間範囲の指定(終了日時) 任意 無し 指定にはRFC3339形式(例:YYYY-MM-DDThh:mm:ss+hh:mm)を使用します
encoding ダウンロード時の拡張子の指定 任意 PLAIN_TEXT FILE_ZIP、FILE_GZIPもしくはPLAIN_TEXTのいずれを指定します

付与されているメタ情報

/channels および /messages から取得できるデータには、デバイスからのデータだけでなく、プラットフォーム側で付与されたメタ情報が存在します。 以下に meta フィールドにメタ情報として含まれる情報の詳細を示します。

パラメータ名 役割
cursor 指定した条件にマッチするデータがlimitを超える場合、パラメータとして指定することで次のデータを取得することができます
hasNext 指定した条件にマッチするデータがlimitを超える場合は true 、超えない場合は false を返します
plan 現在データ保存機能(DataStore V2)で選択されているプランを返します

また、基本のメッセージフォーマットは、 メッセージ仕様#channels形式 を参照ください。

APIの基本的な使い方

APIを利用するには事前にデータ保存機能であるDataStore V2の有効化、および連携サービスであるDataStore V2 APIの追加が必要になります。 以下では基本的な利用までの手順を示します。

DataStore V2の有効化

こちらを参考にコントロールパネルからDataStore V2を有効化します。 データ保存機能(DataStore V2)仕様

Note

既にDataStore V2を有効化している場合、DataStore V2 APIの連携サービスを作成していなくとも、メッセージは記録されています。 そのため、必要な時に連携サービスを作成し、保存されているデータを参照することができます。 保存されている期間は、利用しているDataStore V2のプランによって異なります。

連携サービスの追加

こちらを参考にコントロールパネルから DataStore V2 API を追加します。 連携サービスの操作

作成したDataStore V2 APIを見ると、Tokenが確認できます。 これを以下では _token_ とします。

Note

DataStore V2 APIでは、エンドポイントは sakura.iosakuraio.jp の2つが用意されています。 これにより、ドメインを管理するレジストリでの障害時においても、エンドポイントを変更することで連携するシステムの動作を継続させることができます。

チャンネル単位でのデータ取得(/channels)

/channels を使用してメッセージをチャンネル単位で取得する方法は以下の通りです。 これは特定のチャンネルのデータに絞って活用したい場合に便利な方法です。 取得できるデータは形式が channels のものに限られます。

以下のリクエストを用意されたエンドポイントに対して行います。 また、取得したいデータの条件を指定することもできます。 例えば、特定のモジュールのある時刻以降のメッセージを取得したい場合は以下のようにします。

$ curl -X GET --header 'Accept: application/json' 'https://api.sakura.io/datastore/v2/channels?token=_token_&module=_module_id_&order=DESC&after=2020-04-21T00%3A00%3A00.0000%2B09%3A00'
or
$ curl -X GET --header 'Accept: application/json' 'https://api.sakuraio.jp/datastore/v2/channels?token=_token_&module=_module_id_&order=DESC&after=2020-04-21T00%3A00%3A00.0000%2B09%3A00'

リクエストに対する応答のイメージは以下のとおりです。 モジュールごとの固有のIDを以下では _module_id_ とします。

$ curl -X GET --header 'Accept: application/json' 'https://api.sakura.io/datastore/v2/channels?token=_token_&module=_module_id_&order=DESC&after=2020-04-21T00%3A00%3A00%2B09%3A00'
{
  "meta": {
    "cursor": "1588237982428301926/_module_id_",
    "hasNext": true,
    "plan": "36M"
  },
  "results": [{
      "channel": 0,
      "datetime": "2020-04-30T09:13:11.432401183Z",
      "id": "11__module_id__0_1588237991432401183",
      "module": "_module_id_",
      "type": "l",
      "value": 269462
    },
    {
      "channel": 0,
      "datetime": "2020-04-30T09:13:10.43216209Z",
      "id": "11__module_id__0_1588237990432162090",
      "module": "_module_id_",
      "type": "l",
      "value": 269461
    },
    {
      "channel": 0,
      "datetime": "2020-04-30T09:13:09.431276589Z",
      "id": "11__module_id__0_1588237989431276589",
      "module": "_module_id_",
      "type": "l",
      "value": 269460
    },
    {
      "channel": 0,
      "datetime": "2020-04-30T09:13:08.430940893Z",
      "id": "11__module_id__0_1588237988430940893",
      "module": "_module_id_",
      "type": "l",
      "value": 269459
    },
    {
      "channel": 0,
      "datetime": "2020-04-30T09:13:07.430669539Z",
      "id": "11__module_id__0_1588237987430669539",
      "module": "_module_id_",
      "type": "l",
      "value": 269458
    },
    {
      ...
    }
  ]
}

Note

/channels で一回のリクエストで取得可能なチャンネルデータの数は 1件~2,000件 になります。 以降のデータが必要となる場合は、 cursor パラメータを指定して次のデータを取得することができます。

メッセージ単位でのデータ取得 (/messages)

/messages を使用してデバイスから送信されたメッセージを取得する方法は以下の通りです。 これは同一メッセージに含まれる複数のチャンネルデータの関係性が重要な場合に便利な方法です。

リクエストを用意されたエンドポイントに対して行います。 取得したいデータの条件を指定することもできます。 例えば、特定のモジュールの、ある時刻以降のメッセージを取得したい場合は以下のようにします。

$ curl -X GET --header 'Accept: application/json' 'https://api.sakura.io/datastore/v2/messages?token=_token_&module=_module_id_&limit=20&order=DESC&after=2020-04-21T00%3A00%3A00.0000%2B09%3A00'
or
$ curl -X GET --header 'Accept: application/json' 'https://api.sakuraio.jp/datastore/v2/messages?token=_token_&module=_module_id_&limit=20&order=DESC&after=2020-04-21T00%3A00%3A00.0000%2B09%3A00'

リクエストに対する応答のイメージは以下のとおりです。 モジュールごとの固有のIDを以下では _module_id_ とします。

$ curl -X GET --header 'Accept: application/json' 'https://api.sakura.io/datastore/v2/messages?token=_token_&module=_module_id_&order=DESC&after=2020-04-21T00%3A00%3A00.0000%2B09%3A00'
{
  "meta": {
    "cursor": "1588239069959131110/_module_id_",
    "hasNext": true,
    "plan": "36M"
  },
  "results": [{
    "datetime": "2020-04-30T09:31:13.961689341Z",
    "id": "573214866392041474",
    "module": "_module_id_",
    "payload": {
      "channels": [{
        "channel": 1,
        "datetime": "2020-04-30T09:31:08.961689666Z",
        "type": "l",
        "value": 270544
      }]
    },
    "type": "channels"
  }, {
    "datetime": "2020-04-30T09:31:13.961386847Z",
    "id": "573214866392036354",
    "module": "_module_id_",
    "payload": {
      "channels": [{
        "channel": 0,
        "datetime": "2020-04-30T09:31:13.961387668Z",
        "type": "l",
        "value": 270544
      }]
    },
    "type": "channels"
  }, {
    "datetime": "2020-04-30T09:31:12.961167829Z",
    "id": "573214862193543170",
    "module": "_module_id_",
    "payload": {
      "channels": [{
        "channel": 1,
        "datetime": "2020-04-30T09:31:07.961168179Z",
        "type": "l",
        "value": 270543
      }]
    },
    "type": "channels"
  }, {
    "datetime": "2020-04-30T09:31:12.960745338Z",
    "id": "573214862193538050",
    "module": "_module_id_",
    "payload": {
      "channels": [{
        "channel": 0,
        "datetime": "2020-04-30T09:31:12.96074609Z",
        "type": "l",
        "value": 270543
      }]
    },
    "type": "channels"
  }, {
    "datetime": "2020-04-30T09:31:11.96048739Z",
    "id": "573214857999239169",
    "module": "_module_id_",
    "payload": {
      "channels": [{
        "channel": 1,
        "datetime": "2020-04-30T09:31:06.960487653Z",
        "type": "l",
        "value": 270542
      }]
    },
    "type": "channels"
  }, {
    "datetime": "2020-04-30T09:31:11.960218609Z",
    "id": "573214858011816960",
    "module": "_module_id_",
    "payload": {
      "channels": [{
        "channel": 0,
        "datetime": "2020-04-30T09:31:11.960219249Z",
        "type": "l",
        "value": 270542
      }]
    },
    "type": "channels"
  }, {
    "datetime": "2020-04-30T09:31:10.960276443Z",
    "id": "573214853830100994",
    "module": "_module_id_",
    "payload": {
      "channels": [{
        "channel": 1,
        "datetime": "2020-04-30T09:31:05.960294132Z",
        "type": "l",
        "value": 270541
      }]
    },
    "type": "channels"
  }, {
    "datetime": "2020-04-30T09:31:10.960009173Z",
    "id": "573214853830095874",
    "module": "_module_id_",
    "payload": {
      "channels": [{
        "channel": 0,
        "datetime": "2020-04-30T09:31:10.960009873Z",
        "type": "l",
        "value": 270541
      }]
    },
    "type": "channels"
  }, {
    "datetime": "2020-04-30T09:31:09.959402568Z",
    "id": "573214849606436866",
    "module": "_module_id_",
    "payload": {
      "channels": [{
        "channel": 1,
        "datetime": "2020-04-30T09:31:04.959423631Z",
        "type": "l",
        "value": 270540
      }]
    },
    "type": "channels"
  }, {
    "datetime": "2020-04-30T09:31:09.95913111Z",
    "id": "573214849610626048",
    "module": "_module_id_",
    "payload": {
      "channels": [{
        "channel": 0,
        "datetime": "2020-04-30T09:31:09.959131823Z",
        "type": "l",
        "value": 270540
      }]
    },
    "type": "channels"
  }]
}

Note

/messages で一回のリクエストで取得可能なメッセージの数は 2,000件 になります。 以降のデータが必要となる場合は、 cursor パラメータを指定して次のデータを取得することができます。

メッセージ単位での取得 (/messages-bulk)

/messages-bulk を使用してデバイスから送信されたメッセージをテキストファイルとして取得する方法は以下の通りです。 これはメッセージデータをJSONとして外部のツールで活用する場合に便利な方法です。

リクエストを用意されたエンドポイントに対して行います。 取得したいデータの条件を指定することもできます。 例えば、特定のモジュールの、直近100件のメッセージをzip形式で取得したい場合は以下のようにします。

$ curl -X GET --header 'Accept: application/zip' 'https://api.sakura.io/datastore/v2/messages-bulk?token=_token_&module=_module_id_&order=DESC&limit=100&encoding=FILE_ZIP'
or
$ curl -X GET --header 'Accept: application/zip' 'https://api.sakuraio.jp/datastore/v2/messages-bulk?token=_token_&module=_module_id_&order=DESC&limit=100&encoding=FILE_ZIP'

リクエストにより入手したファイルのイメージは以下のとおりです。 モジュールごとの固有のIDを以下では _module_id_ とします。

{"id":"569836693407376386","module":"_module_id_","type":"channels","datetime":"2020-04-21T01:47:34.759466292Z","payload":{"channels":[{"channel":1,"type":"l","value":1100766,"datetime":"2020-04-21T01:47:29.759466752Z"}]}}
{"id":"569836693407345664","module":"_module_id_","type":"channels","datetime":"2020-04-21T01:47:34.758992097Z","payload":{"channels":[{"channel":0,"type":"l","value":1100766,"datetime":"2020-04-21T01:47:34.758993233Z"}]}}
{"id":"569836689208878082","module":"_module_id_","type":"channels","datetime":"2020-04-21T01:47:33.758637473Z","payload":{"channels":[{"channel":1,"type":"l","value":1100765,"datetime":"2020-04-21T01:47:28.758637728Z"}]}}
{"id":"569836689208847362","module":"_module_id_","type":"channels","datetime":"2020-04-21T01:47:33.75836677Z","payload":{"channels":[{"channel":0,"type":"l","value":1100765,"datetime":"2020-04-21T01:47:33.75836772Z"}]}}
{"id":"569836685039739906","module":"_module_id_","type":"channels","datetime":"2020-04-21T01:47:32.758316921Z","payload":{"channels":[{"channel":1,"type":"l","value":1100764,"datetime":"2020-04-21T01:47:27.758317328Z"}]}}
...

Note

/message-bulk で一回のリクエストで取得可能なメッセージ数に制限はありません。 メッセージが大量に存在する場合、ファイルの取得に時間がかかる場合があります。

メッセージ単位でのデータ取得 (CSV出力)

デバイスから送信されたメッセージをCSVファイルとして、コントロールパネルから取得する方法は以下の通りです。 これはメッセージデータをCSVとして外部のツールで活用する場合に便利な方法です。

まず、コントロールパネルにて、作成したDataStore V2 APIの連携サービス詳細画面を開き、 CSV出力 をクリックします。

連携サービス詳細画面にてCSV出力をクリックします

CSV出力モーダルが表示されます。 取得したいデータの条件を指定することもできます。 例えば、すべてのモジュールの直近100件のメッセージを取得したい場合は以下のようにします。 プレビューでは、出力されるデータの内容をダウンロード前に確認することができます。 条件の指定ができたら、 download をクリックします。

CSV出力モーダルにてパラメータを指定してdownloadをクリックします

リクエストにより入手したファイルのイメージは以下のとおりです。 モジュールごとの固有のIDを以下では _module_id_ とします。

datetime type module channel0 channel1 is_online coordinate_latitude coordinate_longitude coordinate_range_m
2020-04-21 21:14:15 channels _module_id_   1138347        
2020-04-21 21:14:15 channels _module_id_ 1138347          
2020-04-21 21:14:14 channels _module_id_   1138346        
2020-04-21 21:14:14 channels _module_id_ 1138346          
2020-04-21 21:14:13 channels _module_id_   1138345        

Note

CSVファイルとして取得可能なメッセージ数に制限はありません。 メッセージが大量に存在する場合、ファイルの取得に時間がかかる場合があります。

APIリファレンス

コントロールパネルからのみ利用可能なCSV出力を除き、以下のリファレンスにより発行するコマンドの生成やテストを行うことができます。 sakura.io DataStore V2 API

DataStore APIからの変更点

DataStore V2 APIと前身であるDataStore APIの間にはいくつかの変更点があります。 移行の際には以下の違いを確認のうえ、システムの実装を検討ください。

/channels の変更箇所

リクエスト/レスポンス V1パラメータ名 V2パラメータ名 役割 変更点
リクエスト module module 対象モジュールの指定 複数モジュール指定は廃止、すべてのモジュールもしくはいずれか1つのみ指定可能
リクエスト size limit 1リクエストで取得する最大数 名称を変更、およびデフォルト値を変更(100 -> 200)
リクエスト order order メッセージのソート順 指定パラメータの小文字を廃止、大文字のみ受け付けるよう厳格化
リクエスト after after 取得する時間範囲の指定(開始日時), RFC3339形式のみ受け付けるよう厳格化  
リクエスト before before 取得する時間範囲の指定(終了日時), RFC3339形式のみ受け付けるよう厳格化  
リクエスト channel channel 対象となるチャンネル番号指定, 複数チャンネル指定は廃止、いずれか1つのみ指定可能  
レスポンス datastore plan パラメータ名を変更、およびプラン名を変更  
レスポンス (該当なし) hasNext 新規追加  
レスポンス project_option (該当なし) 該当パラメータ廃止  
レスポンス count (該当なし) 該当パラメータ廃止  
レスポンス match (該当なし) 該当パラメータ廃止  
レスポンス location (該当なし) 該当パラメータ廃止、管理APIにて参照可能のため  

/messages の変更箇所

リクエスト/レスポンス V1パラメータ名 V2パラメータ名 役割 変更点
リクエスト module module 対象モジュールの指定 複数モジュール指定は廃止、すべてのモジュールもしくはいずれか1つのみ指定可能
リクエスト size limit 1リクエストで取得する最大数 名称を変更、およびデフォルト値を変更(100 -> 200)
リクエスト order order メッセージのソート順 指定パラメータの小文字を廃止、大文字のみ受け付けるよう厳格化
リクエスト after after 取得する時間範囲の指定(開始日時) RFC3339形式のみ受け付けるよう厳格化
リクエスト before before 取得する時間範囲の指定(終了日時) RFC3339形式のみ受け付けるよう厳格化
リクエスト type (該当なし) 該当項目廃止  
レスポンス datastore plan パラメータ名を変更、およびプラン名を変更  
レスポンス (該当なし) hasNext 新規追加  
レスポンス project_option (該当なし) 該当パラメータ廃止  
レスポンス count (該当なし) 該当パラメータ廃止  
レスポンス match (該当なし) 該当パラメータ廃止  
レスポンス location (該当なし) 該当パラメータ廃止、管理APIにて参照可能のため  

DataStore および DataStore API からの移行

環境の移行についてはこちらを参考にsakura.ioおよび外部サービス側を変更ください。 DataStore および DataStore APIからの移行