Edited at

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


参考

https://docs.candyhouse.co/#sesame-api-tutorial


準備


環境

スマートロックであるSESAMEとWifiアクセスポイントの設定を済ませましょう。

参考: WiFiアクセスポイントを設定する

セサミスマートロック用Wifiアクセスポイントを持っていない場合は追加で購入する必要があります。

セサミ自体をこれから買う場合はセットで買っておきましょう。

セサミスマートロック用Wifiアクセスポイントは2.4GHz帯にしか対応していない点には注意です。


アプリ

スマホアプリの管理画面から Cloud 機能を有効にしておきます。

スマートフォンアプリから 管理 > 設定を変更 > クラウド を ON にします。


API KEY の発行

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

コメント 2019-04-30 175718.png

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
}