API操作方法

sakura.ioの通信モジュールの登録、プロジェクト作成、連携サービスの設定、料金の確認といった操作はコントロールパネルやAPIを介して行います。 ここでは、sakura.ioで提供されるAPI、およびAPIを利用した場合のプラットフォームの操作方法を記載します。

APIの説明

sakura.ioではGUI経由にとどまらず、REST APIを活用したシステムからの各種操作を提供します。 APIは現在用途に応じて数種類提供されております。

sakura.io API

sakura.io APIはコントロールパネルで提供している、通信モジュールの登録や解除、といった基本的な操作のコマンド生成を支援するドキュメントページです。

  • プロジェクトの一覧取得(GET /v1/projects/)
  • プロジェクトの新規作成(POST /v1/projects/)
  • 特定プロジェクトの削除(DELETE /v1/projects/{projectId}/)
  • 特定プロジェクトの詳細取得(GET /v1/projects/{projectId}/)
  • 特定プロジェクトの名称変更(PUT /v1/projects/{projectId}/)
  • 通信モジュールの一覧取得(GET /v1/modules/)
  • 通信モジュールの新規登録(POST /v1/modules/)
  • 特定通信モジュールの登録解除(DELETE /v1/modules/{moduleId}/)
  • 特定通信モジュールの詳細取得(GET /v1/modules/{moduleId}/)
  • 特定通信モジュールの名称変更(PUT /v1/modules/{moduleId}/)
  • 特定通信モジュールの所属プロジェクト変更(PUT /v1/modules/{moduleId}/)
  • 連携サービスの一覧取得(GET /v1/services/)
  • 特定連携サービスの削除(DELETE /v1/services/{serviceId}/)
  • 特定連携サービスの詳細取得(GET /v1/services/{serviceId}/)

sakura.io Incoming Webhook

sakura.io Incoming WebhookはIncoming Webhookで提供している、通信モジュールへの送信するためのデータフォーマットおよびコマンド生成を支援するドキュメントページです。

注意事項

本ドキュメントページではSecret指定時のハッシュ値生成までは提供しません。

設定で Secret を指定された場合、X-Sakura-Signature ヘッダを付加してPOSTしてください。 この値は Secret と HTTPのペイロードの文字列から計算することができます。

この署名をIoT Platform側で検証することによって、悪意のある第三者から送信されたデータを無視することができます。

import hmac
import hashlib
import requests
import json
secret = "Secret"
data = {"module": "XXXXXXXXX","type": "channels","payload": {"channels": [{"channel": 1,"type": "i","value": 1},{"channel": 2,"type": "b","value": "0f1e2d3c4b5c6b7a"}]}}
payload = json.dumps(data)
x_sakura_signature = hmac.new(secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha1).hexdigest()
print(x_sakura_signature)

headers = {'X-Sakura-Signature' : x_sakura_signature}
requests.post('https://secure.sakura.ad.jp/iot-alpha/incoming/hogehoge', data=payload, headers=headers)

sakura.io DataStore API

sakura.io DataStore APIはsakura.ioに蓄積されたデータを定期処理等の用途でまとめて取り出すためのコマンド生成を支援するドキュメントページです。

DataStore APIでは大きく2つの方式での取得方法を提供します。

  • チャンネル毎のデータを取得する(/channels)

蓄積されたデータをチャンネル単位で取得します。単体のデータを複数の形式(入力時の形式[value]、数値[value_num]、文字列[value_str])で格納しているため、単体でも価値のあるデータが活用しやすい形式となっています。

  • チャンネルのデータや、モジュールUP/DOWN等のデータも取得する(/messages)

蓄積されたデータをRM単位で取得します。RMに含まれる複数チャンネルのデータの関係性が重要な場合に活用しやすい形式です。(鍵の「解錠者ID」と「入退室フラグ」等) また、通信モジュールの接続および切断の情報も含まれています。

APIキーの管理

APIキーに関する操作を行うにはsakura.ioコントロールパネルにログインします。

APIキーの発行

ログイン後、右上の会員IDが記載されたボタンをクリックし、APIキーをクリックするとAPIキー管理画面に遷移します。

[APIキー]欄の右上の[+]ボタンをクリックすると、[APIキーの追加]画面に遷移します。

名前およびアクセスレベルを指定し、作成するボタンをクリックすると一意のTokenSecretが生成されます。

注意事項

APIキーのTokenおよびSecretは認証および各操作を実現するための重要な情報となります。また、会員毎にユニークなものが割り振られており、利用者の個人情報となります。SNSなどを通して第三者に共有したりせず、大切に保存してください。

APIキーの名称およびアクセスレベルの変更

名前やアクセスレベルを変更したい場合はメモボタンをクリックします。 該当画面で任意の項目を編集し、保存するボタンをクリックすることで設定内容を変更できます。

APIキーの削除

作成したAPIキーを削除したい場合はゴミ箱ボタンをクリックします。 削除する旨確認されますので、よろしければ削除するボタンをクリックします。