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

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

# 準備

## 環境

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

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

## API KEY の発行
[CANDY HOUSE Dashboard](https://my.candyhouse.co/)にログインします。
![コメント 2019-04-30 175718.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/100313/469ff197-3874-fda0-767c-dd83c18566d1.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

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

- Powershell

    ```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

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

powershell

```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

```shell
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

```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

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

PowerShell

```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
  }
```