SORACOM Users

API によるイベントハンドラーの設定

当ガイドでは、APIを使用したイベントハンドラーの設定方法を説明します。 当ガイドの内容は以下のとおりです。

設定方法

イベントハンドラはAPIで設定を行います。具体的には/event_handlers に対するPOST(Create Event Handler)で設定をします。 soracom-cliで作成する場合には、soracom event-handlers create --body @{JSONファイルのパス} となります。

JSONの構造は以下のとおりです。target, ruleConfig, actionConfigList[]がイベントハンドラの設定に必要な要素です。各要素についてはこの後の項目で詳しく解説します。

{
  "handlerId": "ハンドラーのID 更新時に使用",

  //targetImsi,targetOperatorId,targetGroupのいずれかをセットします
  "targetImsi": "IMSI番号",
  "targetGroupId": "グループID",
  "targetSimId": "SIM ID",
  "targetOperatorId": "OperatorId",

  "name": "表示名",
  "description": "ハンドラーの詳細",
  "ruleConfig": {
    "type": "ルールのタイプ",
    "properties": { "key": "value" }
  },
  "actionConfigList": [
    {
      "type": "アクションのタイプ",
      "properties": { "key": "value" }
    }
  ]
}

具体的には、例えばユーザーコンソールの監視設定から「データ通信量が月間1GBを超えたら通信速度を制限する」という設定を投入し、soracom-cliの soracom event-handlers list コマンドで確認すると以下のような設定が入っていることが確認できます。

{
  "handlerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "targetImsi": null,
  "targetGroupId": null,
  "targetSimId": null,
  "targetOperatorId": "OP0000000000",
  "name": "Prefixed event handler",
  "description": null,
  "ruleConfig": {
    "type": "MonthlyTrafficRule",
    "properties": {
      "inactiveTimeoutDateConst": "BEGINNING_OF_NEXT_MONTH",
      "limitTotalTrafficMegaByte": "1000"
    }
  },
  "status": "active",
  "actionConfigList": [
    {
      "type": "ChangeSpeedClassAction",
      "properties": {
        "speedClass": "s1.minimum",
        "executionDateTimeConst": "IMMEDIATELY"
      }
    },
    {
      "type": "ChangeSpeedClassAction",
      "properties": {
        "speedClass": "s1.standard",
        "executionDateTimeConst": "BEGINNING_OF_NEXT_MONTH"
      }
    },
    {
      "type": "SendMailToOperatorAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "message": "対象SIM ${imsi} \n\nSIMの月次通信量が1000MiBに到達したので通信速度が制限されました",
        "title": "速度制限のお知らせ"
      }
    },
    {
      "type": "SendMailToOperatorAction",
      "properties": {
        "executionDateTimeConst": "BEGINNING_OF_NEXT_MONTH",
        "message": "対象SIM ${imsi} \n\n速度制限期間が終わったので、速度が元に戻りました",
        "title": "速度制限解除のお知らせ"
      }
    }
  ]
}

各パラメータについて、これ以降で説明します。


target

イベントハンドラーの実行対象を設定するための項目です。以下のいずれかを指定してください。

SIM IDについてはこちらをご確認ください。

複数のルール(例えばIMSI単位とOperatorId全体)が同時に条件を満たした場合、デフォルトでは両方のアクションが実行されます。 ただしSIM詳細の監視タブより、グループや全体のSIMに対してのアクションを無効にする事が可能です。

ruleConfig

actionConfigList[]で指定されたアクションを実行するかどうかを判定するルールを設定する項目です。 例えば「月の通信量がXX MiBを越したらアクションを実行」というようなルールを設定することで、指定のアクションを実行できます。

{
  "ruleConfig": {
    "type": "ルールのタイプ",
    "properties": { "key": "value" }
  }
}

どのルールを使用するかは、type属性で指定します。また各ルールには、共通パラメータとしてinactiveTimeoutDateConstを設定できます。これは、ルール適用時に、このルールを再評価させない期間の指定となります。 例えばその月でXX MiB使ったらアクションを実行する場合は、BEGINNING_OF_NEXT_MONTH を指定しておくと、一度ルールにマッチしたあとは翌月まではルールを評価対象から外すことができます。

type

type 説明
SubscriberDailyTrafficRule サブスクライバの日のデータ通信量が一定を超えたらアクションを実行するルール
SubscriberMonthlyTrafficRule サブスクライバの月のデータ通信量が一定を超えたらアクションを実行するルール
SubscriberCumulativeTrafficRule サブスクライバの利用開始からの累積データ通信量が一定を超えたらアクションを実行するルール
SubscriberStatusAttributeRule サブスクライバのステータスが変更されたらアクションを実行するルール
SubscriberSpeedClassAttributeRule サブスクライバの速度クラスが変更されたらアクションを実行するルール
SubscriberFirstTrafficRule 当ルールを設定後、サブスクライバの通信量が初めて記録されたら実行するルール
SubscriberExpiredRule サブスクライバの有効期限が切れた時にアクションを実行するルール
SimDailyTotalTrafficRule SIM(SIM ID)の日のデータ通信量が一定を超えたらアクションを実行するルール
SimMonthlyTotalTrafficRule SIM(SIM ID)の月のデータ通信量が一定を超えたらアクションを実行するルール
SimCumulativeTotalTrafficRule SIM(SIM ID)の利用開始からの累積データ通信量が一定を超えたらアクションを実行するルール
SimStatusAttributeRule SIM(SIM ID)のステータスが変更されたらアクションを実行するルール
SimSpeedClassAttributeRule SIM(SIM ID)の速度クラスが変更されたらアクションを実行するルール
SimExpiredRule SIM(SIM ID)の有効期限が切れた時にアクションを実行するルール
SimSubscriptionStatusRule サブスクリプションの追加を行った場合にOTAの状況によってアクションを実行するルール
DailyTotalTrafficRule Operatorにひもづく全SIMの日のデータ通信量合計が一定を超えたらアクションを実行するルール
MonthlyTotalTrafficRule Operatorにひもづく全SIMの月のデータ通信量合計が一定を超えたらアクションを実行するルール

各 type で共通した properties

properties 説明
inactiveTimeoutDateConst どのルールでも設定を行う必須プロパティ。ルールが実行された後、再度評価されるタイミングの指定。
inactiveTimeoutOffsetMinutes 任意のプロパティ。inactiveTimeoutDateConst で設定した時間との差分を指定します(単位:分)。inactiveTimeoutDateConst から指定時間(分)の経過後に再評価を実行します。

inactiveTimeoutDateConstが取りうる値は以下のとおりです。

説明
IMMEDIATELY すぐに再実行
BEGINNING_OF_NEXT_MONTH 翌月初
BEGINNING_OF_NEXT_DAY 翌日開始時
AFTER_ONE_DAY 1日後
NEVER  実行/再評価を行わない

ruleConfig の type に応じた properties の設定

type: SubscriberDailyTrafficRule

サブスクライバの日のデータ通信量が一定を超えたらアクションを実行するルール

properties 説明
limitTotalTrafficMegaByte このデータ量(MiB)を超えたらアクションを実行する

type: SubscriberMonthlyTrafficRule

サブスクライバの月のデータ通信量が一定を超えたらアクションを実行するルール

properties 説明
limitTotalTrafficMegaByte データ量(MiB)がこの量を超えたらアクションを実行する

type: SubscriberCumulativeTrafficRule

サブスクライバの利用開始からの累積データ通信量が一定を超えたらアクションを実行するルール

properties 説明
limitTotalTrafficMegaByte 累積データ量(MiB)がこの値を超えたらアクションを実行する

type: SubscriberStatusAttributeRule

サブスクライバのステータスが変更されたらアクションを実行するルール

properties 説明
targetStatus SIM がこのステータスになった場合にアクションを実行する。例えばtargetStatusを「inactive」に設定しておくと、SIMがinactiveになった時に指定のアクションを実行できます。

targetStatusが取りうる値は以下のとおりです。

targetStatusの値 説明
null(未設定) すべてのステータス
ready readyステータス
active activeステータス
inactive inactiveステータス
suspended suspendedステータス
terminated terminatedステータス

サポートされる変数(この変数は、Actionの中で設定すると実行時にその値を取得できます)

サポートされる変数 説明
${newStatus} 変更後のステータス
${oldStatus} 変更前のステータス

type: SubscriberSpeedClassAttributeRule

サブスクライバの速度クラスが変更されたらアクションを実行するルール

properties 説明
targetSpeedClass SIMがこの速度クラスになった場合にアクションを実行する。例えばtargetSpeedClassを「s1.minimum」に設定しておくと、SIMがs1.minimumの速度クラスになった時にアクションを実行できます。

targetSpeedClassが取りうる値は以下のとおりです。

targetStatusの値 説明
null(未設定) すべての速度クラス
s1.minimum 速度クラス s1.minimum
s1.slow 速度クラス s1.slow
s1.standard 速度クラス s1.standard
s1.fast 速度クラス s1.fast
s1.4xfast 速度クラス s1.4xfast

サポートされる変数(この変数は、Actionの中で設定すると実行時にその値を取得できます)

サポートされる変数 説明
${newSpeedClass} 変更後の速度クラス
${oldSpeedClass} 変更前の速度クラス

type: SubscriberExpiredRule

サブスクライバの有効期限が切れた時にアクションを実行するルール

サポートされる変数(この変数は、Actionの中で設定すると実行時にその値を取得できます)

サポートされる変数 説明
${newStatus} 有効期限が切れた後のステータス
${oldStatus} 有効期限が切れる前のステータス

type: SimDailyTotalTrafficRule

SIM(SIM ID)の日のデータ通信量が一定を超えたらアクションを実行するルール

properties 説明
limitTotalTrafficMegaByte このデータ量(MiB)を超えたらアクションを実行する

type: SimMonthlyTotalTrafficRule

SIM(SIM ID)の月のデータ通信量が一定を超えたらアクションを実行するルール

properties 説明
limitTotalTrafficMegaByte データ量(MiB)がこの量を超えたらアクションを実行する

type: SimCumulativeTotalTrafficRule

SIM(SIM ID)の利用開始からの累積データ通信量が一定を超えたらアクションを実行するルール

properties 説明
limitTotalTrafficMegaByte 累積データ量(MiB)がこの値を超えたらアクションを実行する

type: SimStatusAttributeRule

SIM(SIM ID)のステータスが変更されたらアクションを実行するルール

properties 説明
targetStatus SIM がこのステータスになった場合にアクションを実行する。例えばtargetStatusを「inactive」に設定しておくと、SIMがinactiveになった時に指定のアクションを実行できます。

targetStatusが取りうる値は以下のとおりです。

targetStatusの値 説明
null(未設定) すべてのステータス
ready readyステータス
active activeステータス
inactive inactiveステータス
suspended suspendedステータス
terminated terminatedステータス

サポートされる変数(この変数は、Actionの中で設定すると実行時にその値を取得できます)

サポートされる変数 説明
${newStatus} 変更後のステータス
${oldStatus} 変更前のステータス

type: SimSpeedClassAttributeRule

SIM(SIM ID)の速度クラスが変更されたらアクションを実行するルール

properties 説明
targetSpeedClass SIMがこの速度クラスになった場合にアクションを実行する。例えばtargetSpeedClassを「s1.minimum」に設定しておくと、SIMがs1.minimumの速度クラスになった時にアクションを実行できます。

targetSpeedClassが取りうる値は以下のとおりです。

targetStatusの値 説明
null(未設定) すべての速度クラス
s1.minimum 速度クラス s1.minimum
s1.slow 速度クラス s1.slow
s1.standard 速度クラス s1.standard
s1.fast 速度クラス s1.fast
s1.4xfast 速度クラス s1.4xfast

サポートされる変数(この変数は、Actionの中で設定すると実行時にその値を取得できます)

サポートされる変数 説明
${newSpeedClass} 変更後の速度クラス
${oldSpeedClass} 変更前の速度クラス

type: SimExpiredRule

SIM(SIM ID)の有効期限が切れた時にアクションを実行するルール

サポートされる変数(この変数は、Actionの中で設定すると実行時にその値を取得できます)

サポートされる変数 説明
${newStatus} 有効期限が切れた後のステータス
${oldStatus} 有効期限が切れる前のステータス

type: SimSubscriptionStatusRule

サブスクリプションの追加を行った場合にOTAの状況によってアクションを実行するルール

properties 説明
started サブスクリプションの追加を開始した場合にアクションを実行
finished サブスクリプションの追加が完了した場合にアクションを実行
failed サブスクリプションの追加が失敗した場合にアクションを実行
null 上記のいずれの場合もアクションを実行

サポートされる変数(この変数は、Actionの中で設定すると実行時にその値を取得できます)

サポートされる変数 説明
${imsi} ステータスによって入る値は異なります。
started:plan01s の IMSI
finished:追加されたサブスクリプションの IMSI
failed:plan01s の IMSI
${primaryImsi} plan01s の IMSI
${subscription} OTA で追加されたサブスクリプション
${otaStatus} サブスクリプション追加のステータス
started:サブスクリプションの追加を開始した状態
finished:サブスクリプションの追加が完了した状態
failed:サブスクリプションの追加が失敗した状態

type: DailyTotalTrafficRule

Operatorにひもづく全SIMの日のデータ通信量合計が一定を超えたらアクションを実行するルール

properties 説明
limitTotalTrafficMegaByte データ量(MiB)がこの量を超えたらアクションを実行する
このルールは、ターゲットとして「targetOperatorId」の場合のみ有効です。

type: MonthlyTotalTrafficRule

Operatorにひもづく全SIMの月のデータ通信量合計が一定を超えたらアクションを実行するルール

properties 説明
limitTotalTrafficMegaByte データ量(MiB)がこの量を超えたらアクションを実行する
このルールは、ターゲットとして「targetOperatorId」の場合のみ有効です。

actionConfigList[]

ruleConfigで指定されたルールが適用された場合に実行されるアクションを指定するための項目です。 例えば、ルールが適用されたタイミングで指定のアドレスにメールを送ったり、SIMの速度クラスを変更したりできます。

{
  "actionConfigList": [
    {
      "type": "アクションのタイプ",
      "properties": { "key": "value" }
    }
  ]
}

ルールと同様、type属性でどのアクションを使うかを指定できます。 また共通パラメータとしてexecutionDateTimeConstを設定できます。 executionDateTimeConstはそのアクションをいつ実行するかを指定するパラメータです。

type

type 説明
ChangeSpeedClassAction SIMのSpeedClassを変更するアクション
SendMailAction メールを送るアクション
SendMailToOperatorAction オペレーターの登録メールアドレスにメールを送るアクション
ActivationAction SIMの状態をActive(使用中)にするアクション
DeactivationAction SIMの状態をInactive(休止中)にするアクション
ExecuteWebRequestAction 指定のURLにリクエストをするアクション
InvokeAWSLambdaAction AWS Lambdaを呼び出すアクション

各 type で共通した properties

properties 説明
executionDateTimeConst すべてのアクションに共通の必須パラメータです。ルールの判定が有効になった際、どのタイミングでアクションを実行するかを指定します。
executionOffsetTime 任意のプロパティ。executionDateTimeConst で設定した時間との差分を指定します(単位:分)。executionDateTimeConst から指定時間(分)の経過後にアクションを実行します。

executionDateTimeConstが取りうる値は以下のとおりです。

説明
IMMEDIATELY すぐに実行
BEGINNING_OF_NEXT_MONTH 翌月初
BEGINNING_OF_NEXT_DAY 翌日開始時
AFTER_ONE_DAY 1日後
NEVER 実行しない

actionConfigList の type に応じた properties の設定

type: ChangeSpeedClassAction

SIMのSpeedClassを変更するアクション

properties 説明
speedClass “s1.slow”,“s1.standard"などの速度クラスを設定する

type: SendMailAction

メールを送るアクション

properties 説明
to 送付先メールアドレス
title メールタイトル
message メール本文

メールのタイトル、および本文には、以下の変数を利用することが可能です。また、これ以外にも、ルールでサポートされる変数を利用できます。

サポートされる変数 説明
${simId} 対象SIMのSIM ID
${imsi} 対象SIMのIMSI
${operatorId} 対象SIMを持つOperatorのID
${date} 送信日付(yyyy/m/d)
${year} 送信年 (yyyy)
${month} 送信月 (m)
${date} 送信日 (d)

type: SendMailToOperatorAction

Operatorにメールを送るアクション

properties 説明
title メールタイトル
message メール本文
メールのタイトル、および本文には、「メールを送るアクション」と同じ変数が利用できます。

type: ActivationAction

SIMの状態をActive(使用中)にするアクション

当 type に応じた properties の設定はありません。

type: DeactivationAction

SIMの状態をInactive(休止中)にするアクション

当 type に応じた properties の設定はありません。

type: ExecuteWebRequestAction

指定のURLにリクエストをするアクション

properties 説明
url 接続先URLとパラメーター
httpMethod GET,POST,PUT,DELETEのいずれか
contentType application/jsonなどのContentType
headers ヘッダーに設定する値(エスケープされたJSONオブジェクト(hash))(任意)
body リクエストボディにセットする文字列(任意) GET,DELETEの場合は設定できません

url,headersおよびbodyには、以下の変数を設定できます。またこれ以外にも、ルールでサポートされる変数を利用することが可能です。

サポートされる変数 説明
${simId} 対象SIMのSIM ID
${imsi} 対象SIMのIMSI
${operatorId} 対象SIMを持つOperatorのID
${date} 送信日付(yyyy/m/d)
${year} 送信年 (yyyy)
${month} 送信月 (m)
${date} 送信日 (d)

type: InvokeAWSLambdaAction

AWS Lambdaを呼び出すアクション

properties 説明
endpoint LambdaのエンドポイントURL
functionName Lambdaファンクション名 (バージョンやエイリアス指定も可)
accessKey アクセスキー
secretAccessKey シークレットアクセスキー
parameter1 パラメーター1(optional)
parameter2 パラメーター2(optional)
parameter3 パラメーター3(optional)
parameter4 パラメーター4(optional)
parameter5 パラメーター5(optional)

パラメーターには任意の文字列(最大100文字)、およびルールでサポートされる変数(${newSpeedClass}など)を設定できます

呼び出し先のLambdaファンクションには、以下のJSONが渡されます。

{
"imsi":"対象のimsi",
"parameter1":"上記のparameter1",
"parameter2":"上記のparameter2",
"parameter3":"上記のparameter3",
"parameter4":"上記のparameter4",
"parameter5":"上記のparameter5"
}

Lambdaファンクション実装例

exports.handler = function(event, context) {
  console.log('imsi =', event.imsi);
  console.log('value1 =', event.parameter1);
  context.succeed(event.imsi);
};
参考
  • イベントハンドラでは、グループをターゲットにした場合でも、ruleConfig で定義された条件を達成したかどうかの判定は SIM ごとに行われ、その都度 Lambda Function が起動されます。どの SIM での通信によって Lambda Function が呼び出されたのかは、Lambda に渡されるevent オブジェクトに含まれている IMSI から判別できます。
  • イベントハンドラの条件を達成したタイミングで SIM が所属するグループに該当する SIM 全体にアクションを行いたい場合には、イベントハンドラから Lambda Function に引き渡される JSON の parameter にグループIDを含めておき、Lambda Function 側で SORACOM API を実行して該当の SIM を取得するような実装を検討してください。

設定サンプル

※ 以下に掲載する構文はサンプルです。実際にお使いになる場合は、お客様自身でテストを実施ください。

SIMの速度変更時に、ExecuteWebRequestActionでSlackに通知するサンプル


{
  "targetOperatorId": "OPXXXXXXXXX",
  "name": "SpeedClass",
  "description": null,
  "ruleConfig": {
    "type": "SubscriberSpeedClassAttributeRule",
    "properties": {
      "inactiveTimeoutDateConst": "IMMEDIATELY"
    }
  },
  "status": "active",
  "actionConfigList": [
    {
      "type": "ExecuteWebRequestAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "url": "https://hooks.slack.com/services/XXXX(SlackのWebHook URL)",
        "httpMethod": "POST",
        "contentType":"application/json; charset=utf-8",
        "body":"{\"text\":\"${imsi} speed class changed. from ${oldSpeedClass} to ${newSpeedClass}\"}"
      }
    }
  ]
}


ChangeSpeedClassAction, SendMailActionを利用し、1日100M利用で1日後まで速度制限しメール通知するサンプル

{
  "targetImsi": "111333444555566",
  "name": "100MiBリミット",
  "description": "1日100MiB利用で、1日後まで速度制限",
  "ruleConfig": {
    "properties": {
      "inactiveTimeoutDateConst": "AFTER_ONE_DAY",
      "limitTotalTrafficMegaByte": 100
    },
    "type": "DailyTrafficRule"
  },
  "actionConfigList": [
    {
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "speedClass": "s1.slow"
      },
      "type": "ChangeSpeedClassAction"
    },
    {
      "properties": {
        "executionDateTimeConst": "AFTER_ONE_DAY",
        "speedClass": "s1.fast"
      },
      "type": "ChangeSpeedClassAction"
    },
    {
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "message": "1日のデータ通信量が100MiBに到達したので速度制限を行います",
        "title": "ソラコムからのお知らせ",
        "to": "notify@exmaple.com"
      },
      "type": "SendMailAction"
    } ,
    {
      "properties": {
        "executionDateTimeConst": "AFTER_ONE_DAY",
        "message": "速度制限を解除します",
        "title": "ソラコムからのお知らせ",
        "to": "notify@exmaple.com"
      },
      "type": "SendMailAction"
    }
  ]
}

InvokeAWSLambdaActionを利用し、累積3GB利用時にAWS Lambda呼び出しするサンプル

累積でのイベントのため、1度のみの評価を行うNEVERをinactiveTimeoutDateConstに設定します。

{
  "targetOperatorId": "OPXXXXXXXXX",
  "name": "3GBリミット",
  "description": "累積3GB利用時",
  "ruleConfig": {
    "properties": {
      "inactiveTimeoutDateConst": "NEVER",
      "limitTotalTrafficMegaByte": 3000
    },
    "type": "CumulativeTrafficRule"
  },
  "actionConfigList": [
    {
      "properties": {
        "secretAccessKey": "XXXXXXXXXXXXXX",
        "endpoint": "https://lambda.ap-northeast-1.amazonaws.com",
        "accessKey": "XXXXXXXXXXXXXX",
        "functionName": "Lambdaのfunction名",
        "executionDateTimeConst": "IMMEDIATELY",
        "parameter3": "param3",
        "parameter2": "param2",
        "parameter1": "param1"
      },
      "type": "InvokeAWSLambdaAction"
    }
  ]
}

InvokeAWSLambdaActionを利用し、速度クラス変更時にAWS Lambdaで履歴を保存するサンプル

速度クラス変更のルールで利用できる変数(${newSpeedClass},${oldSpeedClass})を使用します。 指定したAWS Lambdaに変更前後の速度クラスがパラメーターとして渡されるため、LambdaのプログラムでDBなどに履歴保存します。

{
  "targetOperatorId": "OPXXXXXXXXX",
  "name": "SpeedClass変更",
  "description": "SpeedClass変更時に実行",
  "ruleConfig": {
    "properties": {
      "inactiveTimeoutDateConst": "IMMEDIATELY",
      "targetSpeedClass":null
    },
    "type": "SubscriberSpeedClassAttributeRule"
  },
  "actionConfigList": [
    {
      "properties": {
        "secretAccessKey": "XXXXXXXXXXXXXX",
        "endpoint": "https://lambda.ap-northeast-1.amazonaws.com",
        "accessKey": "XXXXXXXXXXXXXX",
        "functionName": "Lambdaのfunction名",
        "executionDateTimeConst": "IMMEDIATELY",
        "parameter1": "${oldSpeedClass}",
        "parameter2": "${newSpeedClass}"
      },
      "type": "InvokeAWSLambdaAction"
    }
  ]
}

参考

pagetop