Sesame API Version 3 のチュートリアル


参考

準備

環境

スマートロックであるSESAMEとWifiアクセスポイントの設定を済ませましょう。
参考: WiFiアクセスポイントを設定する
セサミスマートロック用Wifiアクセスポイントを持っていない場合は追加で購入する必要があります。
セサミ自体をこれから買う場合はセットで買っておきましょう。
セサミスマートロック用Wifiアクセスポイントは2.4GHz帯にしか対応していない点には注意です。

アプリ

スマホアプリの管理画面から Cloud 機能を有効にしておきます。
スマートフォンアプリから 管理 > 設定を変更 > クラウド を ON にします。

API KEY の発行

CANDY HOUSE Dashboardにログインします。

API Settings で ADD を押すと API Key が発行されます。
後から確認出来なくなるので、しっかりとメモしておきましょう。

API を叩く

始めに

  • API エンドポイント: https://api.candyhouse.co/public
    全てのリクエストの URI はこのエンドポイントから始まります

  • API KEY
    先ほど取得した API KEY は全てのリクエストにおいてヘッダーに Authorization: YOUR_AUTH_TOKEN の形式で追加します

PowerShell Invoke-WebRequest の場合ここにレスポンスとして書いてあるものはプロパティ Content の中に格納されます。
結果の JSON を綺麗に成形したい場合は、 (command).Content | ConvertFrom-Json | ConvertTo-Json とすると成形されます。
例えば、以下のようになります。

(Invoke-WebRequest -Headers @{Authorization = YOUR_AUTH_TOKEN} -Uri https://api.candyhouse.co/public/sesames).Content | ConvertFrom-Json | ConvertTo-Json

セサミ一覧

GET /sesames
アカウントにリンクされている Sesame の情報が JSON 形式で返ってきます

リクエスト

  • curl

    curl -H "Authorization: YOUR_AUTH_TOKEN" \
      https://api.candyhouse.co/public/sesames
    
  • Powershell

    Invoke-WebRequest -Headers @{Authorization = YOUR_AUTH_TOKEN}`
     -Uri https://api.candyhouse.co/public/sesames
    

レスポンス

  [
    {
      "device_id": "00000000-0000-0000-0000-000000000000",
      "serial": "ABC1234567",
      "nickname": "Front door"
    },
    {
      "device_id": "00000000-0000-0000-0000-000000000001",
      "serial": "DEF7654321",
      "nickname": "Back door"
    }
  ]

セサミの状態

GET /sesame/{device_id}

GET /sesames からも分かるセサミそれぞれに割り当てられている device_id を使って、鍵がロックされているか否かを返します。

リクエスト

curl

curl -H "Authorization: YOUR_AUTH_TOKEN" \
  https://api.candyhouse.co/public/sesame/00000000-0000-0000-0000-000000000001

powershell

Invoke-WebRequest -Headers @{Authorization = YOUR_AUTH_TOKEN}`
 -Uri https://api.candyhouse.co/public/sesame/00000000-0000-0000-0000-000000000001

レスポンス

  {
    "locked": true,
    "battery": 100,
    "responsive": true
  }

セサミの操作

POST /sesame/{device_id}

Body に command プロパティを渡してそのコマンドの操作を、 URI で指定した device id のセサミに対して行います。

Body

command

lock , unlock , sync のいずれか
sync はサーバーの情報(lock or unlock)と鍵の状態の同期。頻繁に行うと、セサミのバッテリの持ちが悪くなる可能性がある。
lock , unlock が正常に動けば、現時点で shell から鍵の開け閉めが出来るようになります。

Result

task_id

実行結果を得るために使うID

リクエスト

curl

curl -H "Authorization: YOUR_AUTH_TOKEN" \
    -H "Content-Type: application/json" \
    -X POST -d '{"command":"lock"}' \
    https://api.candyhouse.co/public/sesame/00000000-0000-0000-0000-000000000001

PowerShell

Invoke-WebRequest -Headers @{Authorization = YOUR_AUTH_TOKEN; "Content-Type" = "application/json"} `
 -Method Post `
 -Body (ConvertTo-Json -InputObject @{command = "lock"}) `
 -Uri https://api.candyhouse.co/public/sesame/00000000-0000-0000-0000-000000000001

PowerShell の場合、 {hoge} は ScriptBlock になってしまい、 @{hoge = fuga} は Hashtable なので、
PowerShell で Body に JSON を持たせる場合、Hashtable を ConvertTo-Json に渡して変換する必要があります。

レスポンス

  {
    "task_id": "01234567-890a-bcde-f012-34567890abcd"
  }

操作結果の問い合わせ

GET /action-result?task_id={task_id}

リクエスト

curl

curl -H "Authorization: YOUR_AUTH_TOKEN" \
    https://api.candyhouse.co/public/action-result?task_id=01234567-890a-bcde-f012-34567890abcd

PowerShell

Invoke-WebRequest -Headers @{Authorization = YOUR_AUTH_TOKEN} `
 -Uri https://api.candyhouse.co/public/action-result?task_id=01234567-890a-bcde-f012-34567890abcd

レスポンス

  {
    "task_id": "01234567-890a-bcde-f012-34567890abcd",
    "status": "terminated",
    "successful": true
  }