連携サービスAPI

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

Incoming Webhook API

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

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

連携サービスの作成

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

データの準備

送るデータを決めます。 以下では、 data.json というファイルに書いたことにします。データフォーマットはJSONで、以下のようなフォーマットです。 <module id> はメッセージを受け取るモジュールのIDです。コントロールパネルまたは管理APIから確認することができます。

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

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

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

連携サービスの作成

コントロールパネルからサービス追加を行い、 Datastore API を追加します。 Secretとして、以下では、 _secret_ を入力したとします。 作成したIncoming Webhook を見ると、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