SORACOM LTE-M Button for Enterprise をCLIで設定してみる

カテゴリー SAブログ
カテゴリーデバイス
カテゴリープラットフォーム

こんにちは。ソリューションアーキテクトの内田（ニックネーム：jet）です。

以下のブログで SORACOM API（以下、API）/ SORACOM CLI（以下、CLI）の紹介と基礎的な操作について紹介しました。

このブログではCLI を使って「SORACOM LTE-M Button for Enterprise」（以下、ボタン）を設定してみようと思います。

例えば、ひとつのボタンで設定によって送信されるメールの内容や宛先を変更したい場合や、すでに利用中のボタン設定と同様の設定をコピーしたい場合などに、API / CLI を使うことで自動化やコードによる再現性のある設定ができます。

今回はデバイスのスマート設定機能を使って設定されたボタンの設定を確認し、確認した設定をコピーして、新しい設定で利用できるようにしていきます。通常はSORACOMユーザーコンソールで設定することで、意識せずに設定している内容を意識することで、プラットフォームへの理解も深まると思います。

事前確認

今回はすでに設定済みのボタンを元に、新たに別の設定を作り設定を切り替えてみます。
また、これらの作業をすべてCLIを使って行っていきます。

SORACOM LTE-M Button for Enterprise

初期設定済みのボタンが必要となります。
初期設定済みとはSORACOM ユーザーコンソールの「ガジェット管理＞ LTE-M Button for Enterprise/Plus ＞デバイス設定変更」で表示される「可視化」「簡易位置測位機能」「メール送信」のすべての機能を有効にしている状態を想定しています。
設定の方法や詳細はユーザードキュメントを参照してください。

SORACOM CLI

すべての確認や設定をCLIで行うため、CLIの設定が完了している必要があります。
設定の方法や詳細はユーザードキュメントを参照してください。

CLIコマンドサンプルを記載していますが、動作確認は以下の環境で行なっています。
CLI：SORACOM API client v0.13.0
OS：macOS 13.0

現状確認

設定済みのボタンを使って、設定情報の確認をしてみます。

SIMの確認

まず、SIMの一覧からボタンで利用されているSIMを探してみます。
一覧からボタンとして登録されている物だけをリストアップして内容を確認してみます。

CLIコマンドサンプル

TAG_NAME=soracom.gadgets
TAG_VALUE=LTE-M-Button

soracom subscribers list --tag-name ${TAG_NAME} --tag-value ${TAG_VALUE}

SIMに名前をつけている場合は名前を含めるとさらに対象が絞り込めます

TAG_NAME=soracom.gadgets
TAG_VALUE=LTE-M-Button
TAG_NAME_2=name
TAG_VALUE_2=jet_lte-m_button

soracom subscribers list --tag-name ${TAG_NAME} --tag-value ${TAG_VALUE} --tag-name ${TAG_NAME_2} --tag-value ${TAG_VALUE_2}

CLIコマンド実行結果サンプル（一部抜粋）

[
    {
            "apn": "soracom.io",
            "createdAt": 1646755221164,
            "createdTime": 1646755221164,
            "expiredAt": null,
            "expiryAction": null,
            "expiryTime": null,
            "groupId": "f60*****-****-****-****-*********efa",
            "iccid": "*******************",
            "imeiLock": null,
            "imsi": "440*********195",
// ..... 一部省略
           "subscription": "plan-KM1",
            "tags": {
                   "DSN": "*************195",
                    "name": "jet_lte-m_button",
                    "soracom.gadgets": "LTE-M-Button"
            },
            "terminationEnabled": false,
            "type": "t1.standard"
    }
]

利用しているAPI

実行結果の中から、imsi、groupId、tags の値を確認してみます。
IMSI はサブスクリプションに紐づく識別子となり、最後にCLIのコマンド実行時に利用します。
グループIDは、グループに紐づく識別子となり、IMSIと同様に今後CLIのコマンド実行時に利用します。
タグは、付加情報を保存できる領域になり、今回はこのタグにある情報を確認して追加や更新をしていきます。ボタンの場合には製造番号（DSN）や名前（name）が設定されていることが確認できます。

グループの確認

続けて、グループの確認をしてみます。
SIMの確認の際に取得したグループIDを使用します。

CLIコマンドサンプル

TAG_NAME=soracom.gadgets
TAG_VALUE=LTE-M-Button
TAG_NAME_2=name
TAG_VALUE_2=jet_lte-m_button

GROUP_ID=`soracom subscribers list --tag-name ${TAG_NAME} --tag-value ${TAG_VALUE} --tag-name ${TAG_NAME_2} --tag-value ${TAG_VALUE_2} | jq -r '.[] | .groupId'`

soracom groups get --group-id ${GROUP_ID}

CLIコマンド実行結果サンプル

{
        "configuration": {
                "SoracomAir": {
                        "binaryParserEnabled": true,
                        "binaryParserFormat": "@button",
                        "locationEnabled": true
                },
                "SoracomFunk": {
                        "contentType": "json",
                        "destination": {
                                "provider": "aws",
                                "resourceUrl": "arn:aws:lambda:ap-northeast-1:************:function:funk-button-email:prod",
                                "service": "lambda"
                        },
                        "enabled": true
                },
                "SoracomHarvest": {
                        "enabled": true
                },
                "UnifiedEndpoint": {
                        "response": {
                                "failure": {
                                        "skipStatusCode": false
                                },
                                "format": "SoracomHarvest",
                                "success": {
                                        "skipStatusCode": false
                                }
                        }
                }
        },
        "createdAt": 1663576511204,
        "createdTime": 1663576511204,
        "groupId": "f60*****-****-****-****-*********efa",
        "lastModifiedAt": 1663649472726,
        "lastModifiedTime": 1663649472726,
        "operatorId": "OP*******196",
        "tags": {
                "mailAddress": "a_button@example.com",
                "mailBody": "[A] ボタン {{subscriber.tags.name}} が {{event.clickTypeName}} クリックされました\n\n      - 電池残量: {{event.batteryLevelPercent}} %\n",
                "mailSubject": "[A] ボタン {{subscriber.tags.name}} がクリックされました",
                "name": "jet_test_group_15751",
                "soracom.gadgets": "LTE-M-Button"
        }
}

利用しているAPI

実行結果を確認すると、SORACOM Air、SORACOM Funk、SORACOM Harvest、Unified Endpoint の設定情報とタグに設定された内容を確認できます。
グループに設定されたこれらの情報をCLIを使って再現できれば、ユーザーコンソールで操作したものと同様の設定となるはずなので、実際に検証してみます。

設定作業

CLIを使って順に設定を行なっていきます。

1. グループを作成する

まずはグループを作成します。
グループはIDで管理されているため名前を指定しなくても作成できますが、今回は確認しやすくするために名前を指定して作成しています。

CLIコマンドサンプル

GROUP_NAME=jet_test_group_$RANDOM

GROUP_ID=`soracom groups create --body "{\"tags\":{\"name\":\"${GROUP_NAME}\"}}" | jq -r .groupId`

soracom groups get --group-id ${GROUP_ID}

CLIコマンド実行結果サンプル

{
    "configuration": {},
    "createdAt": 1664345521195,
    "createdTime": 1664345521195,
    "groupId": "bfb*****-****-****-****-*********6c4",
    "lastModifiedAt": 1664345521195,
    "lastModifiedTime": 1664345521195,
    "operatorId": "OP*******196",
    "tags": {
            "name": "jet_test_group_22577"
    }
}

利用しているAPI

2. グループに設定を追加する

続いては、作成したグループにグループ設定として利用するSORACOMの各サービスの設定を追加していきます。
サービスの設定はJSON形式でファイルに記載したものをCLIの引数として指定しています。
設定の方法や詳細はユーザードキュメントを参照してください。

SORACOM Air

SORACOM Air for セルラー設定を追加していきます。
追加するのは、簡易位置測位機能とバイナリパーサーの設定となります。

サービス設定ファイルサンプル（air_config.json）

[
  {
    "key": "binaryParserEnabled",
    "value": true
  },
  {
    "key": "binaryParserFormat",
    "value": "@button"
  },
  {
    "key": "locationEnabled",
    "value": true
  }
]

CLIコマンドサンプル

NAMESPACE=SoracomAir
CONFIG_FILE=air_config.json

soracom groups put-config --group-id ${GROUP_ID} --namespace ${NAMESPACE} --body @${CONFIG_FILE}

CLIコマンド実行結果サンプル

{
    "configuration": {
            "SoracomAir": {
                    "binaryParserEnabled": true,
                    "binaryParserFormat": "@button",
                    "locationEnabled": true
            }
    },
    "createdAt": 1664345521195,
    "createdTime": 1664345521195,
    "groupId": "bfb*****-****-****-****-*********6c4",
    "lastModifiedAt": 1664350348867,
    "lastModifiedTime": 1664350348867,
    "operatorId": "OP*******196",
    "tags": {
            "name": "jet_test_group_22577"
    }
}

SORACOM Funk

SORACOM Funk 設定を追加していきます。
Funk を有効化します。

サービス設定ファイルサンプル（funk_config.json）

[
    {
        "key": "contentType",
        "value": "json"
    },
    {
        "key": "enabled",
        "value": true
    },
    {
        "key": "destination",
        "value": {
            "provider": "aws",
            "resourceUrl": "arn:aws:lambda:ap-northeast-1:************:function:funk-button-email:prod",
            "service": "lambda"
        }
    }
]

CLIコマンドサンプル

NAMESPACE=SoracomFunk
CONFIG_FILE=funk_config.json

soracom groups put-config --group-id ${GROUP_ID} --namespace ${NAMESPACE} --body @${CONFIG_FILE}

CLIコマンド実行結果サンプル

{
    "configuration": {
            "SoracomAir": {
                    "binaryParserEnabled": true,
                    "binaryParserFormat": "@button",
                    "locationEnabled": true
            },
            "SoracomFunk": {
                    "contentType": "json",
                    "destination": {
                            "provider": "aws",
                            "resourceUrl": "arn:aws:lambda:ap-northeast-1:************:function:funk-button-email:prod",
                            "service": "lambda"
                    },
                    "enabled": true
            }
    },
    "createdAt": 1664345521195,
    "createdTime": 1664345521195,
    "groupId": "bfb*****-****-****-****-*********6c4",
    "lastModifiedAt": 1664351838823,
    "lastModifiedTime": 1664351838823,
    "operatorId": "OP*******196",
    "tags": {
            "name": "jet_test_group_22577"
    }
}

SORACOM Harvest

SORACOM Harvest Data 設定を追加していきます。
Harvest Data を有効化します。

サービス設定ファイルサンプル（harvest_config.json）

[
  {
    "key": "enabled",
    "value": true
  }
]

CLIコマンドサンプル

NAMESPACE=SoracomHarvest
CONFIG_FILE=harvest_config.json

soracom groups put-config --group-id ${GROUP_ID} --namespace ${NAMESPACE} --body @${CONFIG_FILE}

CLIコマンド実行結果サンプル

{
    "configuration": {
            "SoracomAir": {
                    "binaryParserEnabled": true,
                    "binaryParserFormat": "@button",
                    "locationEnabled": true
            },
            "SoracomFunk": {
                    "contentType": "json",
                    "destination": {
                            "provider": "aws",
                            "resourceUrl": "arn:aws:lambda:ap-northeast-1:************:function:funk-button-email:prod",
                            "service": "lambda"
                    },
                    "enabled": true
            },
            "SoracomHarvest": {
                    "enabled": true
            }
    },
    "createdAt": 1664345521195,
    "createdTime": 1664345521195,
    "groupId": "bfb*****-****-****-****-*********6c4",
    "lastModifiedAt": 1664350905989,
    "lastModifiedTime": 1664350905989,
    "operatorId": "OP*******196",
    "tags": {
            "name": "jet_test_group_22577"
    }
}

Unified Endpoint

Unified Endpoint の設定を追加していきます。
レスポンスフォーマットの設定を追加します。

サービス設定ファイルサンプル（unified_config.json）

[
    {
        "key": "response",
        "value": {
            "failure": {
                "skipStatusCode": false
            },
            "format": "SoracomHarvest",
            "success": {
                "skipStatusCode": false
            }
        }
    }
]

CLIコマンドサンプル

NAMESPACE=UnifiedEndpoint
CONFIG_FILE=unified_config.json

soracom groups put-config --group-id ${GROUP_ID} --namespace ${NAMESPACE} --body @${CONFIG_FILE}

CLIコマンド実行結果サンプル

{
    "configuration": {
            "SoracomAir": {
                    "binaryParserEnabled": true,
                    "binaryParserFormat": "@button",
                    "locationEnabled": true
            },
            "SoracomFunk": {
                    "contentType": "json",
                    "destination": {
                            "provider": "aws",
                            "resourceUrl": "arn:aws:lambda:ap-northeast-1:************:function:funk-button-email:prod",
                            "service": "lambda"
                    },
                    "enabled": true
            },
            "SoracomHarvest": {
                    "enabled": true
            },
            "UnifiedEndpoint": {
                    "response": {
                            "failure": {
                                    "skipStatusCode": false
                            },
                            "format": "SoracomHarvest",
                            "success": {
                                    "skipStatusCode": false
                            }
                    }
            }
    },
    "createdAt": 1664345521195,
    "createdTime": 1664345521195,
    "groupId": "bfb*****-****-****-****-*********6c4",
    "lastModifiedAt": 1664352177058,
    "lastModifiedTime": 1664352177058,
    "operatorId": "OP*******196",
    "tags": {
            "name": "jet_test_group_22577"
    }
}

利用しているAPI

3. グループにタグを設定する

続けてグループにタグを設定していきます。
タグにはメール送信の設定を追加します。
タグの設定はJSON形式でファイルに記載したものをCLIの引数として指定しています。

タグ設定ファイルサンプル（mail_tag.json）

[
    {
        "tagName": "mailAddress",
        "tagValue": "b_button@example.com"
    },
    {
        "tagName": "mailBody",
        "tagValue": "[B] ボタン {{subscriber.tags.name}} が {{event.clickTypeName}} クリックされました\n\n      - 電池残量: {{event.batteryLevelPercent}} %\n 
    },
    {
        "tagName": "mailSubject",
        "tagValue": "[B] ボタン {{subscriber.tags.name}} がクリックされました"
    },
    {
        "tagName": "soracom.gadgets",
        "tagValue": "LTE-M-Button"
    }
]

CLIコマンドサンプル

TAG_FILE=mail_tag.json

soracom groups put-tags --group-id ${GROUP_ID} --body @${TAG_FILE}

CLIコマンド実行結果サンプル

 {
    "configuration": {
            "SoracomAir": {
                    "binaryParserEnabled": true,
                    "binaryParserFormat": "@button",
                    "locationEnabled": true
            },
            "SoracomFunk": {
                    "contentType": "json",
                    "destination": {
                            "provider": "aws",
                            "resourceUrl": "arn:aws:lambda:ap-northeast-1:************:function:funk-button-email:prod",
                            "service": "lambda"
                    },
                    "enabled": true
            },
            "SoracomHarvest": {
                    "enabled": true
            },
            "UnifiedEndpoint": {
                    "response": {
                            "failure": {
                                    "skipStatusCode": false
                            },
                            "format": "SoracomHarvest",
                            "success": {
                                    "skipStatusCode": false
                            }
                    }
            }
    },
    "createdAt": 1664345521195,
    "createdTime": 1664345521195,
    "groupId": "bfb*****-****-****-****-*********6c4",
    "lastModifiedAt": 1664358436483,
    "lastModifiedTime": 1664358436483,
    "operatorId": "OP*******196",
    "tags": {
            "mailAddress": "2j94coafd@mozmail.com",
            "mailBody": "ボタン {{subscriber.tags.name}} が {{event.clickTypeName}} クリックされました\n\n      - 電池残量: {{event.batteryLevelPercent}} %\n      - 緯度,経度: {{context.location.lat}},{{context.location.lon}} (簡易位置測位機能で表示)",
            "mailSubject": "[B]ボタン {{subscriber.tags.name}} がクリックされました",
            "name": "jet_test_group_22577",
            "soracom.gadgets": "LTE-M-Button"
    }
}

このCLIコマンド実行結果が、現状確認で確認したグループ設定と同じ内容になっていることが確認できると思います。

利用しているAPI

4. グループを切り替える

最後にボタンのSIMが所属するグループを切り替えます。
これまで設定してきたグループに切り替えることで、設定した内容で動作するようになります。

CLIコマンドサンプル

TAG_NAME=soracom.gadgets
TAG_VALUE=LTE-M-Button

TAG_NAME_2=name
TAG_VALUE_2=jet_lte-m_button

IMSI=`soracom subscribers list --tag-name ${TAG_NAME} --tag-value ${TAG_VALUE} --tag-name ${TAG_NAME_2} --tag-value ${TAG_VALUE_2}  | jq -r '.[] | .imsi'`

soracom subscribers set-group --group-id ${GROUP_ID} --imsi ${IMSI}

CLIコマンド実行結果サンプル（一部抜粋）

{
    "apn": "soracom.io",
    "createdAt": 1646755221164,
    "createdTime": 1646755221164,
    "expiredAt": null,
    "expiryAction": null,
    "expiryTime": null,
    "groupId": "bfb*****-****-****-****-*********6c4",
    "iccid": "*******************",
    "imeiLock": null,
    "imsi": "440*********195",
// ..... 一部省略
   "subscription": "plan-KM1",
    "tags": {
            "DSN": "*************195",
            "name": "jet_lte-m_button",
            "soracom.gadgets": "LTE-M-Button"
    },
    "terminationEnabled": false,
    "type": "t1.standard"
}

利用しているAPI

5. ボタンの動作を確認する

すべての設定とSIMのグループ切り替えが終了したので、実際にボタンをクリックしてメールを受信してみます。

グループの切り替え前に受信したメールが以下で、

グループの切り替え後に受信したメールが以下になります。

タイトルや本文が [A] / [B] となっており異なっていることが確認できるかと思います。

まとめ

CLIを使ってボタン用のグループを新たに作って切り替えをしてみました。
今回は、現在の設定を確認し順次複製するような手順で行いました。
API / CLI で操作することで、どのように情報が設定されているかを知る手がかりになったかと思います。

実際にはグループの複製とグループの切り替え操作は、SORACOMユーザーコンソールで操作できますが、API / CLI で操作できるという選択肢を増やすことで、今後はユースケースに合わせて対応を検討していけるかと思います。

今回利用したボタン利用のユースケースとして、メールの送信先やメールの文面を切り替えたい場合が考えられます。しかし実際にボタンだけで利用する場合を考えると、利用中のボタンにどんなグループ設定がされているか、ボタンだけでは判断ができません。
用途によってメールの文面や送信先を切り替えたい場合には、ボタンを物理的に切り替えたい単位で持つ方がより簡単で確実な場合もありますので、ユースケースに合わせて対応を検討してください。

また、1つのボタンで複数の送信先へのメール送信や、SIM単位での送信先の変更は通常の設定で行えますので、設定の方法や詳細はユーザードキュメントを参照してください。

今回のようなグループ設定を切り替えで利用するケース以外でも、API / CLI でコントロールできる部分を知っていただくことでユースケースに合わせてより便利に使っていただければ嬉しいです。

― ソラコム内田（jet） @uchimanajet7

事前確認

SORACOM LTE-M Button for Enterprise

SORACOM CLI

現状確認

SIMの確認

CLIコマンド サンプル

CLIコマンド実行結果 サンプル（一部抜粋）

利用しているAPI

グループの確認

CLIコマンド サンプル

CLIコマンド実行結果 サンプル

利用しているAPI

設定作業

1. グループを作成する

CLIコマンド サンプル

CLIコマンド実行結果 サンプル

利用しているAPI

2. グループに設定を追加する

SORACOM Air

サービス設定ファイル サンプル（air_config.json）

CLIコマンド サンプル

CLIコマンド実行結果 サンプル

SORACOM Funk

サービス設定ファイル サンプル（funk_config.json）

CLIコマンド サンプル

CLIコマンド実行結果 サンプル

SORACOM Harvest

サービス設定ファイル サンプル（harvest_config.json）

CLIコマンド サンプル

CLIコマンド実行結果 サンプル

Unified Endpoint

サービス設定ファイル サンプル（unified_config.json）

CLIコマンド サンプル

CLIコマンド実行結果 サンプル

利用しているAPI

3. グループにタグを設定する

タグ設定ファイル サンプル（mail_tag.json）

CLIコマンド サンプル

CLIコマンド実行結果 サンプル

利用しているAPI

4. グループを切り替える

CLIコマンド サンプル

CLIコマンド実行結果 サンプル（一部抜粋）

利用しているAPI

5. ボタンの動作を確認する

まとめ

CLIコマンドサンプル

CLIコマンド実行結果サンプル（一部抜粋）

CLIコマンドサンプル

CLIコマンド実行結果サンプル

CLIコマンドサンプル

CLIコマンド実行結果サンプル

サービス設定ファイルサンプル（air_config.json）

CLIコマンドサンプル

CLIコマンド実行結果サンプル

サービス設定ファイルサンプル（funk_config.json）

CLIコマンドサンプル

CLIコマンド実行結果サンプル

サービス設定ファイルサンプル（harvest_config.json）

CLIコマンドサンプル

CLIコマンド実行結果サンプル

サービス設定ファイルサンプル（unified_config.json）

CLIコマンドサンプル

CLIコマンド実行結果サンプル

タグ設定ファイルサンプル（mail_tag.json）

CLIコマンドサンプル

CLIコマンド実行結果サンプル

CLIコマンドサンプル

CLIコマンド実行結果サンプル（一部抜粋）