SORACOMのコマンドラインツールを使ってみた

ひと通り触ってみました。

※私の勘違いやツールのバグなどについては随時修正します。


# 1. インストール

## 検証環境
- Amazon Linux 2015.09
- ruby 2.0.0p647 (2015-08-18) [x86_64-linux]

## インストール

```bash:コマンド
sudo yum -y install ruby-devel
```

gemをインストール

```bash:コマンド
gem install soracom
```

## コマンドが利用できることを確認

SORACOM beamは`soracom group`で設定可能です。

```bash:コマンド
soracom
```

```bash:結果
Commands:
  soracom auth                     # test authentication
  soracom complete                 # command list for shell completion
  soracom event_handler <command>  # Event Handler related operations
  soracom group <command>          # Group related operations
  soracom help [COMMAND]           # Describe available commands or one speci...
  soracom sim <command>            # Subscriber related operations(alias)
  soracom stats <command>          # Stats related operations
  soracom subscriber <command>     # Subscriber related operations
  soracom support                  # open support site
  soracom version                  # print version
```

## コマンドの補間が出来るようにする

```bash:コマンド
EVAL='eval "$(soracom complete)"'
echo ${EVAL} >> ~/.bashrc
source ~/.bashrc
```


# 2. 認証情報の設定

## 認証情報を設定

```bash:コマンド
export SORACOM_EMAIL='soracom@example.com'
export SORACOM_PASSWORD='********************'
```

## 認証情報が設定されていることを確認

```bash:コマンド
soracom auth
```

```bash:結果
testing authentication...
authentication succeeded.
apiKey: ********-****-****-****-************
operatorId: OP**********
```

# 3. バージョン確認

```bash:コマンド
soracom version
```

```bash:結果
Soracom API tool v1.0.2
```

# 4. サポートサイトへのURLを出力

サポートサイトへのURLが出力されます。
（SORACOMさんはzendesk使ってるんですねー。）
（URLは省略しています。）

```bash:コマンド
soracom support
```

```bash:結果
open following URL in your browser.
https://soracom.zendesk.com/********/*********
```
（実際はもっと長い）

# 5. グループの管理

## グループの作成

```bash:コマンド
soracom group create
```

```json:結果
{
  "operatorId": "OP**********",
  "groupId": "********-****-****-****-************",
  "createdAt": 1443866271291,
  "lastModifiedAt": 1443866271291,
  "configuration": {
  },
  "tags": {
  },
  "createdTime": 1443866271291,
  "lastModifiedTime": 1443866271291
}
```
グループ名を設定しないと、ユーザコンソールでSIMをグループに所属させることができません。
（なぜ作成時に必須としてないのかな？）
コマンドラインツールを使用すれば、名前が設定されていないグループにSIMを所属させることができます。


## グループ名を設定

```bash:コマンド
soracom group update_tags --group-id=********-****-****-****-************ --tags='[{"tagName":"name","tagValue":"hogehoge"}]'
```

```json:結果
{
  "operatorId": "OP**********",
  "groupId": "********-****-****-****-************",
  "createdAt": 1443866271291,
  "lastModifiedAt": 1443867218115,
  "configuration": {
  },
  "tags": {
    "name": "hogehoge"
  },
  "createdTime": 1443866271291,
  "lastModifiedTime": 1443867218115
}
```

## グループの一覧を表示

```bash:コマンド
soracom group list
```

```json:結果
[
  {
    "operatorId": "OP**********",
    "groupId": "********-****-****-****-************",
    "createdAt": 1443792381541,
    "lastModifiedAt": 1443792381541,
    "configuration": {
    },
    "tags": {
      "name": "********"
    },
    "createdTime": 1443792381541,
    "lastModifiedTime": 1443792381541
  }
]
```


# 6. SIMの設定

設定するSIMの指定はIMSIで行う。

SIMの登録は、`soracom sim register --imsi=*************** --registration-secret=*****`で可能

解約も可能ですが、SIMが利用できなくなるのでここでは行いません。

## SIMの一覧を表示

```bash:コマンド
soracom sim list
```

```json:結果
[
  {
    "imsi": "***************",
    "msisdn": "81**********",
    "ipAddress": null,
    "apn": "soracom.io",
    "type": "s1.minimum",
    "groupId": "********-****-****-****-************",
    "createdAt": 1443792383749,
    "lastModifiedAt": 1443793730633,
    "expiredAt": null,
    "terminationEnabled": false,
    "status": "inactive",
    "tags": {
      "name": "Nobuhiro Nakayama"
    },
    "sessionStatus": null,
    "speedClass": "s1.minimum",
    "moduleType": "mini",
    "plan": 0,
    "expiryTime": null,
    "operatorId": "OP**********",
    "createdTime": 1443792383749,
    "lastModifiedTime": 1443793730633
  }
]
```

## アクティベート

```bash:コマンド
soracom subscriber activate --imsi=***************
```

```json:結果
[
  {
    "imsi": "***************",
    "msisdn": "81**********",
    "ipAddress": null,
    "apn": "soracom.io",
    "type": "s1.minimum",
    "groupId": "********-****-****-****-************",
    "createdAt": 1443792383749,
    "lastModifiedAt": 1443802419168,
    "expiredAt": null,
    "terminationEnabled": false,
    "status": "active",
    "tags": {
      "name": "Nobuhiro Nakayama"
    },
    "sessionStatus": null,
    "speedClass": "s1.minimum",
    "moduleType": "mini",
    "plan": 0,
    "expiryTime": null,
    "operatorId": "OP**********",
    "createdTime": 1443792383749,
    "lastModifiedTime": 1443802419168
  }
]
```

## 無効化

```bash:コマンド
soracom subscriber deactivate --imsi=***************
```

```json:結果
[
  {
    "imsi": "***************",
    "msisdn": "81**********",
    "ipAddress": null,
    "apn": "soracom.io",
    "type": "s1.minimum",
    "groupId": "********-****-****-****-************",
    "createdAt": 1443792383749,
    "lastModifiedAt": 1443802758241,
    "expiredAt": null,
    "terminationEnabled": false,
    "status": "inactive",
    "tags": {
      "name": "Nobuhiro Nakayama"
    },
    "sessionStatus": null,
    "speedClass": "s1.minimum",
    "moduleType": "mini",
    "plan": 0,
    "expiryTime": null,
    "operatorId": "OP**********",
    "createdTime": 1443792383749,
    "lastModifiedTime": 1443802758241
  }
]
```

## 有効期限を設定
（時刻はエポックミリ秒で表記）

```bash:コマンド
soracom sim set_expiry_time --expiry-time=1447945200000 --imsi=***************
```

```json:結果
[
  {
    "imsi": "***************",
    "msisdn": "81**********",
    "ipAddress": null,
    "apn": "soracom.io",
    "type": "s1.minimum",
    "groupId": "********-****-****-****-************",
    "createdAt": 1443792383749,
    "lastModifiedAt": 1443805447867,
    "expiredAt": 1447945200000,
    "terminationEnabled": false,
    "status": "inactive",
    "tags": {
      "name": "Nobuhiro Nakayama"
    },
    "sessionStatus": null,
    "speedClass": "s1.minimum",
    "moduleType": "mini",
    "plan": 0,
    "expiryTime": 1447945200000,
    "operatorId": "OP**********",
    "createdTime": 1443792383749,
    "lastModifiedTime": 1443805447867
  }
]
```

## 帯域を変更

```bash:コマンド
soracom sim update_speed_class --imsi=*************** --speed-class=s1.minimum
```

```json:結果
[
  {
    "imsi": "***************",
    "msisdn": "81**********",
    "ipAddress": null,
    "apn": "soracom.io",
    "type": "s1.minimum",
    "groupId": "********-****-****-****-************",
    "createdAt": 1443792383749,
    "lastModifiedAt": 1443804583320,
    "expiredAt": null,
    "terminationEnabled": false,
    "status": "inactive",
    "tags": {
      "name": "Nobuhiro Nakayama"
    },
    "sessionStatus": null,
    "speedClass": "s1.minimum",
    "moduleType": "mini",
    "plan": 0,
    "expiryTime": null,
    "operatorId": "OP**********",
    "createdTime": 1443792383749,
    "lastModifiedTime": 1443804583320
  }
]
```

## タグの追加／タグの更新

```bash:コマンド
soracom subscriber update_tags --imsi=*************** --tags=hogehoge:fugafuga
```

```json:結果
[
  {
    "imsi": "***************",
    "msisdn": "81**********",
    "ipAddress": null,
    "apn": "soracom.io",
    "type": "s1.minimum",
    "groupId": null,
    "createdAt": 1443792383749,
    "lastModifiedAt": 1443806667123,
    "expiredAt": null,
    "terminationEnabled": false,
    "status": "inactive",
    "tags": {
      "name": "Nobuhiro Nakayama",
      "hogehoge": "fugafuga"
    },
    "sessionStatus": null,
    "speedClass": "s1.minimum",
    "moduleType": "mini",
    "plan": 0,
    "expiryTime": null,
    "operatorId": "OP**********",
    "createdTime": 1443792383749,
    "lastModifiedTime": 1443806667123
  }
]
```

## タグの削除

```bash:コマンド
soracom subscriber delete_tag --imsi=*************** --tag-name=hogehoge
```

```json:結果
[
  {
    "imsi": "***************",
    "result": "success"
  }
]
```


## 所属グループへの参加／所属グループの変更

```bash:コマンド
soracom subscriber set_group --group-id=********-****-****-****-************ --imsi=***************
```

```json:結果
{
  "imsi": "***************",
  "msisdn": "81**********",
  "ipAddress": null,
  "apn": "soracom.io",
  "type": "s1.minimum",
  "groupId": "********-****-****-****-************",
  "createdAt": 1443792383749,
  "lastModifiedAt": 1443806430004,
  "expiredAt": null,
  "terminationEnabled": false,
  "status": "inactive",
  "tags": {
    "name": "Nobuhiro Nakayama"
  },
  "sessionStatus": null,
  "speedClass": "s1.minimum",
  "moduleType": "mini",
  "plan": 0,
  "expiryTime": null,
  "operatorId": "OP**********",
  "createdTime": 1443792383749,
  "lastModifiedTime": 1443806430004
}
```

## 所属グループの解除

```bash:コマンド
soracom subscriber unset_group --imsi=***************
```

```json:結果
{
  "imsi": "***************",
  "msisdn": "81**********",
  "ipAddress": null,
  "apn": "soracom.io",
  "type": "s1.minimum",
  "groupId": null,
  "createdAt": 1443792383749,
  "lastModifiedAt": 1443806445164,
  "expiredAt": null,
  "terminationEnabled": false,
  "status": "inactive",
  "tags": {
    "name": "Nobuhiro Nakayama"
  },
  "sessionStatus": null,
  "speedClass": "s1.minimum",
  "moduleType": "mini",
  "plan": 0,
  "expiryTime": null,
  "operatorId": "OP**********",
  "createdTime": 1443792383749,
  "lastModifiedTime": 1443806445164
}
```



# 7. データ使用量の確認

## データ通信の使用量を確認

（全く通信していない状態なので、後日結果例を追記予定）

```bash:コマンド
soracom stats get_air_usage --imsi=***************
```

```bash:コマンド
[

]
```


# 8. 監視

監視設定はアカウント共通・グループ共通・SIM個別など、適用範囲を調整可能です。
（コマンドでの作成方法がよく分からなかったので、後日修正）

"targetTag"や"targetGroupId"で適用先を制御するのがポイントっぽい？


## 監視設定を確認
Webのコンソールで設定を有効化したり無効化したりを繰り返すと、設定が

```bash:コマンド
soracom event_handler list
```

```json:結果
[
  {
    "handlerId": "********-****-****-****-************",
    "targetImsi": null,
    "targetOperatorId": "OP**********",
    "targetTag": null,
    "targetGroupId": null,
    "name": "Prefixed event handler",
    "description": null,
    "ruleConfig": {
      "type": "DailyTrafficRule",
      "properties": {
        "inactiveTimeoutDateConst": "BEGINNING_OF_NEXT_DAY",
        "limitTotalTrafficMegaByte": "5"
      }
    },
    "status": "active",
    "actionConfigList": [
      {
        "type": "SendMailToOperatorAction",
        "properties": {
          "executionDateTimeConst": "IMMEDIATELY",
          "message": "対象SIM ${imsi} \n\n利用状況を確認してください。",
          "title": "SIMの日次通信量が5MiBを超えています"
        }
      }
    ]
  },
  {
    "handlerId": "********-****-****-****-************",
    "targetImsi": null,
    "targetOperatorId": "OP**********",
    "targetTag": null,
    "targetGroupId": null,
    "name": "Prefixed event handler",
    "description": null,
    "ruleConfig": {
      "type": "DailyTrafficRule",
      "properties": {
        "inactiveTimeoutDateConst": "BEGINNING_OF_NEXT_DAY",
        "limitTotalTrafficMegaByte": "4"
      }
    },
    "status": "active",
    "actionConfigList": [
      {
        "type": "ChangeSpeedClassAction",
        "properties": {
          "speedClass": "s1.minimum",
          "executionDateTimeConst": "IMMEDIATELY"
        }
      },
      {
        "type": "ChangeSpeedClassAction",
        "properties": {
          "speedClass": "s1.standard",
          "executionDateTimeConst": "BEGINNING_OF_NEXT_DAY"
        }
      },
      {
        "type": "SendMailToOperatorAction",
        "properties": {
          "executionDateTimeConst": "IMMEDIATELY",
          "message": "対象SIM ${imsi} \n\nSIMの日次通信量が4MiBに到達したので通 信速度が制限されました",
          "title": "速度制限のお知らせ"
        }
      },
      {
        "type": "SendMailToOperatorAction",
        "properties": {
          "executionDateTimeConst": "BEGINNING_OF_NEXT_DAY",
          "message": "対象SIM ${imsi} \n\n速度制限期間が終わったので、速度が元に戻りました",
          "title": "速度制限解除のお知らせ"
        }
      }
    ]
  }
]
```

## 監視設定の削除

```bash:コマンド
soracom event_handler delete --handler-id=********-****-****-****-************
```

```json:結果
{
  "result": "success"
}
```

# 9. SORACOM beam

## 設定の確認
ユーザーコンソールから設定した情報を表示します。
（設定はテキトーですｗ）

```bash:コマンド
soracom group list --group-id=********-****-****-****-************
```

```json:結果
[
  {
    "operatorId": "OP**********",
    "groupId": "********-****-****-****-************",
    "createdAt": 1443866271291,
    "lastModifiedAt": 1443868296406,
    "configuration": {
      "SoracomBeam": {
        "http://beam.soracom.io:8888/": {
          "name": "facebook",
          "destination": "https://www.facebook.com/",
          "enabled": true,
          "addSubscriberHeader": false,
          "customHeaders": {
          },
          "addSignature": false
        }
      }
    },
    "tags": {
      "name": "hogehoge"
    },
    "createdTime": 1443866271291,
    "lastModifiedTime": 1443868296406
  }
]
```