連携サービスAPI

ここでは、 連携サービスのAPIの使い方について説明します。

Incoming Webhook API

Incoming Webhook を利用することで、各モジュールにメッセージを送信することができます。 プロジェクトごとに、複数のIncoming Webhook APIを作成することができ、 そのプロジェクトに属するモジュールにメッセージを送信することができます。

Incoming Webhook APIを設定するごと Token が発行され、このTokenを用いて、APIにアクセスします。 各Tokenごとに、 Secret を設定することができ、APIを安全に利用することができます。

連携サービスの作成

コントロールパネルから連携サービスの追加を行い、 Incoming Webhook を追加します。 Secretとして、以下では、 _secret_ を入力したとします。 作成したIncoming Webhookの連携サービス画面からTokenが確認できます。 これを以下では _token_ とします。

データの準備

送信対象のモジュールと、モジュールに送信するデータを決めます。 データの送信には、モジュールのIDです。コントロールパネルまたは管理APIから確認することができます。

モジュールのIDを <module id> 、送信するデータは

  • チャンネル 0 に int32_t 型の 0という数値を送る
  • チャンネル 1 に int32_t 型の 0という数値を送る

とします。

これを data.json というファイルに書いたことにします。

data.json
 {
   "type": "channels",
   "module": "<module id>",
   "payload": {
     "channels": [
       {
         "channel": 0,
         "type": "i",
         "value": 0
       },
       {
         "channel": 1,
         "type": "i",
         "value": 0
       }
     ]
   }
 }

データ送信

最後に改行コードが入っているとうまく行かないので、ファイル末尾の改行コードを削除しておきます。

$ perl -pi -e 'chomp if eof' data.json
$ cat data.json # module id が module-name のモジュールに送る例
{"type":"channels","module":"module-name","payload":{"channels":[{"channel":0,"type":"i","value":10},{"channel":1,"type":"f","value":1.5}]}}%

リクエストボディをメッセージとして、 Secret をKeyとするHMAC-SHA1を計算します。

$ cat data.json | openssl dgst -sha1 -hmac "_secret_"
(stdin)= xxxxxx

上記の HMAC-SHA1 を X-Sakura-Signature ヘッダに入れて、POSTリクエストを送ります。

curl -X POST --header 'Accept: application/json' --header 'X-Sakura-Signature: xxxxxx' -d @data.json 'https://api.sakura.io/incoming/v1/_token_'
{"status":"ok"}

Arduino の sakura.io スケッチ例のStandard を使ってシリアルモニタ経由で見た例が以下です。 受信できていることが確認できます。

Queue に2つのデータが来ていることが確認できる

API リファレンス

sakura.io Incoming Webhook

DataStore API

注意事項

DataStoreおよびDataStore APIは標準機能としての提供を2020年5月12日に終了いたしました。現在は移行期間中となります。 同様の機能はDataStore V2およびDataStore V2 APIでオプションとして提供されます。 今後、sakura.io上で通信したデータの保存を希望する場合は データ保存機能(DataStore V2)仕様 および DataStore V2 API をご覧ください。

DataStore API を利用することで、モジュールから送信されたメッセージを後から取得できます。 取得単位としては、メッセージ単位( /datastore/v1/messages )、または、チャンネルデータ単位 ( /datastore/v1/channels ) で取得可能です。

/datastore/v1/messages では、 すべてのタイプのメッセージ が取得でき、モジュールからのメッセージも同時にメッセージかどうかを区別できます。 一方で、 /datastore/v1/channels では、モジュールから送信されたデータのみが最初からフィルタされており、さらに、特定のチャンネルのみのメッセージを得ることができます。 そのため、特定のチャンネルに注目した処理や分析を書く場合には、 /datastore/v1/channels を利用すると良いでしょう。

DataStore APIの連携サービスを作成しなくとも、標準機能であるDataStoreにメッセージは記録されています。 そのため、必要な時に連携サービスを作成することができます。 記録されている期間は、データストアのプランによって異なります。

連携サービスの作成

コントロールパネルから連携サービスの追加を行い、 DataStore API を追加します。 作成したDataStore APIを見ると、Tokenが確認できます。 これを以下では _token_ とします。

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

全メッセージを取得する場合は以下の通りです。 メッセージフォーマットは、 メッセージ仕様 を参照ください。

$ curl -X GET --header 'Accept: application/json' 'https://api.sakura.io/datastore/v1/messages?token=_token_&size=100'
{
  "meta": {
    "count": 100,
    "cursor": "eJwNyMEBABAMA8CJkIa2qTm87D8I9zzCshkacaDtaxt6lJdqpu7gVNJ8MTzyL/QA/gkKQQ==",
    "match": 576,
    "project_option": {
      "datastore": "light",
      "location": false
    }
  },
  "results": [
    {
      "datetime": "2017-10-31T10:08:06.876701033Z",
      "id": "242726415106784256",
      "module": "_module_id_",
      "payload": {
        "is_online": false
      },
      "type": "connection"
    },
    {
      "datetime": "2017-10-31T10:04:30.545672604Z",
      "id": "242725509136575488",
      "module": "_module_id_",
      "payload": {
        "channels": [
          {
            "channel": 0,
            "datetime": "2017-10-31T10:04:09.621674307Z",
            "type": "i",
            "value": 10
          },
          {
            "channel": 0,
            "datetime": "2017-10-31T10:04:14.841674307Z",
            "type": "i",
            "value": 11
          }
        ]
      },
      "type": "channels"
    },
    ...
  ]
}

取得したいメッセージの条件を指定することもできます。 特定のモジュールが、ある時刻以降の、プラットフォームへの接続履歴を取得したい場合は以下のようにします。 時刻フォーマットは、 ISO 8601形式を利用します。

$ curl -X GET --header 'Accept: application/json' 'https://api.sakura.io/datastore/v1/messages?token=_token_&module=_module_id_&size=100&type=connection&after=2017-10-31T19%3A03%3A30%2B09%3A00'

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

チャンネルメッセージをチャンネル単位取得する場合は以下の通りです。 メッセージフォーマットは、 メッセージ仕様#channels形式 を参照ください。

$ curl -X GET --header 'Accept: application/json' 'https://api.sakura.io/datastore/v1/channels?token=_token_&size=100'
{
  "meta": {
    "count": 2,
    "cursor": "eJwFwcEBwCAIA8CJsCSEiM7RV/cfpHdM7EAG6wUu56aXjGqY/h7WGW1Jo2bL7cAPELcKhg==",
    "match": 2,
    "project_option": {
      "datastore": "light",
      "location": false
    }
  },
  "results": [
    {
      "channel": 1,
      "datetime": "2017-10-23T11:28:11.655170568Z",
      "id": "239847465812629504-1",
      "module": "_module_id_",
      "type": "I",
      "value": 2,
      "value_num": 2,
      "value_str": "2"
    },
    ...
  ]
}

取得したいデータの条件を指定することもできます。 特定のモジュールが、ある時刻以降のメッセージを取得したい場合は以下のようにします。 時刻フォーマットは、 ISO 8601形式を利用します。

$ curl -X GET --header 'Accept: application/json' 'https://api.sakura.io/datastore/v1/messages?token=_token_&module=_module_id_&size=100&after=2017-10-31T19%3A03%3A30%2B09%3A00'

APIリファレンス

sakura.io DataStore API