SORACOM CLI 利用ガイド

SORACOM では SORACOM API をコマンドラインから簡単に呼び出せるツールとして SORACOM CLI を提供しています。このガイドでは SORACOM CLI のインストール方法や基本的な使い方を解説します。

インストール方法

macOS または Linux で Homebrew をお使いの場合

以下のコマンドよりインストールできます。

brew tap soracom/soracom-cli
brew install soracom-cli

それ以外の場合

Releases のページ からターゲットの環境に合ったパッケージファイルをダウンロードして展開し、実行形式ファイルを PATH の通ったディレクトリに配置します。

(例 :) Linux OS の場合

以下のコマンドよりインストールできます。

wget https://github.com/soracom/soracom-cli/releases/download/v0.5.2/soracom_0.5.2_linux_amd64.tar.gz
tar xvf ./soracom_0.5.2_linux_amd64.tar.gz
cp ./soracom_0.5.2_linux_amd64/soracom /usr/local/bin/. 

(例 :) Windows OS の場合

1. https://github.com/soracom/soracom-cli/releases/ へアクセスし、soracom_[バージョン]_windows_amd64.zip をクリック、ダウンロードしてください。
2. ダウンロードした zip ファイルを解凍してください。
3. exe ファイルを PATH の通っているディレクトリ (%SystemRoot%\system32 など) に配置してください。
4. コマンドプロンプトから soracom コマンドが利用できます。

基本的な使い方 - 認証

まずはコンソールでログインするのと同様に認証します。
soracom configure を実行すると、以下のように選択肢が示されます。なお下記の実行例のように LANG などの環境変数を日本語にしておけば、以下の soracom configure コマンドのメッセージも日本語化されます。

$ LANG=ja soracom configure
--- SORACOM CLI セットアップ ---
/home/mick/.soracom ディレクトリがなければ作成し、そこにファイル 'default.json' を作成します。

カバレッジタイプを選択してください。

1. Global
2. Japan

選択してください (1-2) > 

上記では、plan01s などグローバルカバレッジをご利用であれば 1 を、plan-D など日本カバレッジをご利用であれば 2 を入力して Enter を押します。

認証方法を選択してください。

1. AuthKeyId と AuthKey を入力する（推奨）
2. オペレーターのメールアドレスとパスワードを入力する
3. SAM ユーザーの認証情報を入力する（オペレーターID、ユーザー名、パスワード）

選択してください (1-3) > 

上記では認証方式を選びます。推奨は AuthKeyId と AuthKey を用いる 1 です。希望する番号を入力して Enter を押します。
SAM ユーザーを作成して AuthKeyId と AuthKey を発行する方法はSORACOM Access Management を使用して操作権限を管理する をご参照ください。

authKeyId: (authKeyId を入力します)
authKey: (authKey を入力します)
プロファイル default はすでに存在しています。上書きしますか？ (Y/n) Y

1 を選択して AuthKeyId と AuthKey を入力した後、過去にログインしたことがあれば設定を上書きしてよいか確認されます。上書きして良ければ Y を入力して Enter を押します。

以上で認証は完了です。上記コマンドにより認証情報がプロファイルとして保存されます。保存される場所は macOS, Linux 環境であれば ${HOME}/.soracom/default.json に、Windows であれば %HOMEPATH%\.soracom\default.json です。以後 SORACOM CLI を利用するときはこのプロファイルを用いて毎回自動的に認証が行われます。

基本的な使い方 - command を使って SIM 一覧を取得する

SORACOM CLI は soracom [command] [flag] といった形式で使用します。
command は subscriber, vpg など呼び出したい SORACOM API の詳細で、flag は --imsi --limit など呼び出す際の条件を指定します。
たとえば soracom subscribers list と入力して SIM 一覧を表示しましょう。(下の表示例では一部情報をマスクしています)

$ soracom subscribers list
[
        {
                "apn": "soracom.io",
                "imsi": "44010xxxxxxxxxx",
                (中略)
                "speedClass": "s1.minimum"
        },
        {
                "apn": "soracom.io",
                "imsi": "44010yyyyyyyyyy",
                (中略)
                "speedClass": "s1.standard"
        },
... (以下略)
]

基本的な使い方 - flag を使って速度クラスを変更する

command によって flag は必須のものと任意のものとがあります。たとえば subscribers list には必須の flag はありませんが、subscribers update-speed-class の場合は IMSI や速度クラスの指定が --imsi "IMSI" --speed-class "速度クラス" の flag で必須になります。
subscribers list で確認できた IMSI を flag に指定して、soracom subscribers update-speed-class --imsi "IMSI" --speed-class "速度クラス" で速度クラスを変更してみましょう。(下の表示例では一部情報をマスクしています)

$ soracom subscribers update-speed-class --imsi "44010xxxxxxxxxx" --speed-class "s1.fast"
{
        "apn": "soracom.io",
        "imsi": "44010xxxxxxxxxx",
        "ipAddress": "10.zzz.zzz.zzz",
        "moduleType": "nano",
        (中略)
        "speedClass": "s1.fast"
}

なお必須の引数を指定しなかった場合、以下のようにその旨が指摘されます。

$ soracom subscribers update-speed-class
Error: required flag(s) "imsi", "speed-class" not set
Usage:
  soracom subscribers update-speed-class [flags]

基本的な使い方 - ヘルプの見方

soracom --help または soracom -h と実行するとヘルプが表示されます。
soracom subscribers --help と実行すると soracom subscribers 配下で実行できる command 一覧が確認でき、
soracom subscribers update-speed-class --help と実行すると soracom subscribers update-speed-class に指定できる flag の一覧が確認できます。
SORACOM ではユーザーコンソールでできることはほぼすべて API ででき、その API は SORACOM CLI から呼び出せます。ぜひいろいろな CLI を試してみてください。

$ soracom subscribers update-speed-class --help
Changes the speed class of the specified subscriber.

Usage:
  soracom subscribers update-speed-class [flags]

Flags:
      --body string          JSON string or @filename for API request body.
  -h, --help                 help for update-speed-class
      --imsi string          IMSI of the target subscriber.
      --speed-class string

Global Flags:
      --api-key string         Specify API key otherwise soracom-cli performs authentication on behalf of you
      --api-token string       Specify API token otherwise soracom-cli performs authentication on behalf of you
      --coverage-type string   Specify coverage type, 'g' for Global, 'jp' for Japan
      --profile string         Specify profile name

アップデート方法

homebrew によりアップデートする場合

以下のコマンドよりアップデートできます。

brew upgrade soracom-cli

それ以外の場合

Releases のページ からターゲットの環境に合ったパッケージファイルをダウンロードして展開し、既存の実行形式ファイルと置き換えます。

アンインストール方法

homebrew によりアンインストールする場合

以下のコマンドよりアンインストールできます。

brew uninstall soracom-cli

$HOME/.soracom ディレクトリには SORACOM に接続するための認証情報が残っています。こちらについても不要であれば削除します。

それ以外の場合

実行形式ファイルを削除してください。 $HOME/.soracom (Windows の場合 %homepath%\.soracom) ディレクトリには SORACOM に接続するための認証情報が残っています。こちらについても不要であれば削除します。

応用的な使い方 - 認証の頻度を減らす

subscribers list や subscribers update-speed-class といったコマンドは実行のたびにプロファイルに記載された認証情報をもとに API key, API token を発行しています。 1 つのスクリプトで複数の SORACOM CLI コマンドを使用する場合などは soracom auth コマンドで発行した API key, API token を使いまわすことで毎回の発行を省略できます。 jq が使える Linux などの環境であれば以下のようなコマンドで API key, API token の利用・発行ができます。 SAM ユーザーを作成して AuthKeyId と AuthKey を発行する方法はSORACOM Access Management を使用して操作権限を管理する をご参照ください。

auth_info=$(soracom auth --auth-key-id [AuthKeyId] --auth-key [AuthKey])
api_key=$(echo ${auth_info} | jq -r '.apiKey')
api_token=$(echo ${auth_info} | jq -r '.token')
soracom subscribers list --api-key ${api_key} --api-token ${api_token}

応用的な使い方 - AWS Lambda の Layer を利用する

AWS Lambda から SORACOM CLI を利用する場合、soracom-cli Layer を利用できます。 AWS Lambda のレイヤーについては AWS 公式ドキュメントをご参照ください。 soracom-cli Layer の ARN を指定するだけでどの Lambda からでも SORACOM CLI をすぐに使うことができるようになります。

Layer の ARN は arn:aws:lambda:ap-northeast-1:717257875195:layer:soracom-cli-xxx:1 です。以下の点に注意してください。

• soracom-cli-xxx には SORACOM CLI のバージョン番号を含めます。バージョン 0.5.2 の場合は soracom-cli-052 となります。 最新バージョンに対応していますので、その時点の最新版を確認して記載します。
• ap-northeast-1 の部分は、お使いのリージョンに合わせて変更してください。 ap-east-1 以外の全リージョンに展開済みですので任意のリージョンから Layer を利用できます。

リファレンス

SORACOM CLI のソースコードや最新パッケージ、使い方の詳細は GitHub のリポジトリに公開されています。引数補完やプロキシ経由での使い方なども記載されていますのでご参照ください。

また、直接 API を利用することも可能です。SORACOM API 利用ガイドをご参照ください。