DataStore V2 API ¶

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

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

DataStore V2 API

概要 ¶

外部システムや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の応答に時間がかかる場合があります。応答時間を短くしたい場合は後述するlimit等のオプションを指定して、必要なデータだけを取得するようにしてください。

指定可能なオプション ¶

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

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

datetime	type	module	channel0	channel1
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ファイルとして取得可能なメッセージ数に制限はありません。メッセージが大量に存在する場合、ファイルの取得に時間がかかる場合があります。

リクエスト/レスポンス	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 V2 API ¶

概要 ¶

指定可能なオプション ¶

/channels ¶

/messages ¶

/messages-bulk ¶

付与されているメタ情報 ¶

APIの基本的な使い方 ¶

DataStore V2の有効化 ¶

連携サービスの追加 ¶

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

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

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

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

APIリファレンス ¶

DataStore APIからの変更点 ¶

/channels の変更箇所 ¶

/messages の変更箇所 ¶