/

M5Stack EzDataのAPIリスト

syagawa

M5Stackが提供するEzDataというIoT機器用のクラウドストレージサービスがあることを知ったのですがドキュメントなどが見つかりませんでした。

githubのソースやEzData Control Panelからどういう処理が許可されてるのか、どのようなAPIがあるのかはある程度わかるのですが体系的に使い方が書かれているページが無いようです。

なのでEzDataのAPIについてわかっている範囲でまとめてみます。

1. トークンの取得

トークンが無いとデータの保存も取得も削除もできません。まずトークンを取得します。https://docs.m5stack.com/en/arduino/iotservice/ezdataをブラウザで開きます、EzDataのイメージ図の下にRefresh tokenというボタンがあるのでそれをクリックします。

右側の"Click refresh to get token..."の部分に生成されたトークンが表示されるのでコピーしてください。

ブラウザが無くてもLinux環境であればcurlで取得も可能です。

$ curl -X POST  https://ezdata.m5stack.com/api/accessKey/apply
# レスポンス {"status":1,"data":{"accessKey":"thisissampletokennnnnnnnnnnnnnnn"}}
# accessKeyの値がトークン {"status":1,"data":{"accessKey":"thisissampletokennnnnnnnnnnnnnnn"}}

2. データの保存と取得と削除

データの保存

  • url: https://ezdata.m5stack.com/api/store/<token>/<key>
  • method: POST

下記がcurlコマンドでPOSTする例となります。

# token: thisissampletokennnnnnnnnnnnnnnn
# key(topic): test
# value: test-string
$ curl -X POST -d '{"value": "test-string"}' -H "Content-Type: application/json" https://ezdata.m5stack.com/api/store/thisissampletokennnnnnnnnnnnnnnn/test

保存できる値は文字列または整数となります。再度同じkey(topic)に対してPOSTすると上書き保存となります。 ※EzDataでは保存データのkeyをtopicと呼んでいるようですが、この記事ではkeyで統一します。

List(配列)への追加

  • url: https://ezdata.m5stack.com/api/store/<token>/list/<key>
  • method: POST

配列にデータを追加します。下記がcurlコマンドの例となります。

# token: thisissampletokennnnnnnnnnnnnnnn
# key(topic): test-list
# payload: {"test-object-key": "sample", "test-array": [1,2,3]}
$ curl -X POST -d '{"payload": {"test-object-key": "sample", "test-array": [1,2,3]} }' -H "Content-Type: application/json" https://ezdata.m5stack.com/api/store/thisissampletokennnnnnnnnnnnnnnn/list/test-list

追加できる値は文字列、整数、オブジェクト(JSON)となります。再度同じkeyにPOSTするとList(配列)に値が追加されます。

保存したデータの取得

  • url: https://ezdata.m5stack.com/api/store/<token>/<key>
  • method: GET

下記はURLの例となります。

# 通常のデータの取得 GET
## token: thisissampletokennnnnnnnnnnnnnnn
## key(topic): test-string
https://ezdata.m5stack.com/api/store/thisissampletokennnnnnnnnnnnnnnn/test-string

# 配列の0番目から1個データを取得 GET
## token: thisissampletokennnnnnnnnnnnnnnn
## key(topic): test-list
## index: 0
## count: 1
https://ezdata.m5stack.com/api/store/thisissampletokennnnnnnnnnnnnnnn/test-string?offset=0&count=1

GETなのでブラウザでURLを表示するだけで確認可能です。

データの削除

  • url: https://ezdata.m5stack.com/api/store/<token>/delete/<key>
  • method: POST

DELETEメソッドではなくPOSTメソッドであることに注意してください。

# token: thisissampletokennnnnnnnnnnnnnnn
# key(topic): test-string
$ curl -X POST https://ezdata.m5stack.com/api/store/MpkUCSumv4YNs0Zwcdn39xeGP1b0mSmj/delete/test-string

特定のトークンに保存されたデータ一覧の取得

  • url: https://ezdata.m5stack.com/api/store/keys/<token>
  • method: GET

データの一覧やデータの更新日時などが取得可能です。

# token: thisissampletokennnnnnnnnnnnnnnn
https://ezdata.m5stack.com/api/store/keys/thisissampletokennnnnnnnnnnnnnnn

ブラウザでの使用

IoT機器用のサービスのようですがブラウザから使用することも可能です。m5stack.comのサイト(例 http://docs.m5stack.com/en/arduino/iotservice/ezdata ) をChromeなどで開いて開発者ツールのconsoleからfetch APIでリクエストしてみてください。

以前(2023年の8月くらい)は適当なサイト(google.comとか)からCORSに引っかからずfetchでpostなどが叩けたのですが、現在(2024年2月)はエラーとなります。

下記はfetch APIでデータを保存する場合のサンプルです。

// token: thisissampletokennnnnnnnnnnnnnnn
// key(topic): test
// value: test-string

fetch("https://ezdata.m5stack.com/api/store/thisissampletokennnnnnnnnnnnnnnn/test",{
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({value: "test-string"})
})
  .catch(err => err)
  .then(res => {console.log(res)});

EzDataコントロールパネル

ブラウザでの使用をするのならm5stack.comドメインのEzData Control Panelの方がよいです。トークンを入れればCRUD操作が直接できます。

データの保存期間

半年以上データへの操作が行われないとデータは消去されるようです。データと言うのがトークン全体なのか、トークン内の一つのkey(topic): valueなのかは不明ですが永続的なストレージではないという点に留意して使ったほうがいいということです。

また、1トークンあたり1時間に何リクエストを許可するかみたいな使用制限についても不明です。Webブラウザ上からも操作可能なため、M5Stackの発売している機器だけでなく相当数のPCを含むデバイスがEzDataを使っている可能性があります。ですのでサーバーが頻繁にダウンしている可能性もあります。その点も留意して使用してください。

現状で無料で使用できているようですが、今後EzDataへのリクエスト数が増加した場合ブラウザからのリクエストが遮断されたり有料化される可能性もあるでしょう。リクエストの投げすぎには注意しましょう。

追記/更新

  • 2024/02/13 fetch APIでのCRUD操作がm5stack.domドメイン上でないとできないようになっていたので、それについて追記しました