SORACOM Developers

Documents

イベントハンドラー機能詳細

はじめに

イベントハンドラー機能は、特定のSIM・特定のグループ・特定のタグ・全SIMに対してデータ転送容量の閾値を元に、メールでの通知・速度クラスの変更・AWS Lambdaファンクションの実行をする事ができる機能です。

例えば、SORACOM Airの「監視」機能は、内部的にはイベントハンドラー機能を利用して実現されています。なお、コンソールの「監視」設定よりも複雑な処理を行いたい場合には、イベントハンドラーのAPIを使用して設定を行ってください。


設定方法

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

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

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

  //targetImsi,targetOperatorId,targetTag,targetGroupのいずれかをセットします
  "targetImsi": "IMSI番号",
  "targetOperatorId": "OperatorId",
  "targetTag": { "タグ名":"値" },
  "targetGroupId": "グループID",

  "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,
  "targetOperatorId": "OP0000000000",
  "targetTag": null,
  "targetGroupId": null,
  "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

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

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

SIM詳細監視設定


ruleConfig

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

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

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

type
DailyTrafficRule
SIMの日のデータ通信量が一定を超えたらアクションを実行するルール
MonthlyTrafficRule
SIMの月のデータ通信量が一定を超えたらアクションを実行するルール
CumulativeTrafficRule
SIMの利用開始からの累積データ通信量が一定を超えたらアクションを実行するルール
DailyTotalTrafficRule
Operatorにひもづく全SIMの日のデータ通信量合計が一定を超えたらアクションを実行するルール
MonthlyTotalTrafficRule
Operatorにひもづく全SIMの月のデータ通信量合計が一定を超えたらアクションを実行するルール
SubscriberStatusAttributeRule
SIMのステータスが変更されたらアクションを実行するルール
SubscriberSpeedClassAttributeRule
SIMの速度クラスが変更されたらアクションを実行するルール
SubscriberExpiredRule
SIMの有効期限が切れた時にアクションを実行するルール
properties
inactiveTimeoutDateConst
どのルールでも設定を行う必須プロパティ。ルールが実行された後、再度評価されるタイミングの指定。
inactiveTimeoutDateConstが取りうる値は以下のとおりです。
IMMEDIATELY
すぐに再実行
BEGINNING_OF_NEXT_MONTH
翌月初
BEGINNING_OF_NEXT_DAY
翌日開始時
AFTER_ONE_DAY
1日後
NEVER
実行/再評価を行わない

ルール一覧

SIMの日のデータ通信量が一定を超えたらアクションを実行するルール
type
DailyTrafficRule
limitTotalTrafficMegaByte
このデータ量(MiB)を超えたらアクションを実行する
SIMの月のデータ通信量が一定を超えたらアクションを実行するルール
type
MonthlyTrafficRule
limitTotalTrafficMegaByte
データ量(MiB)がこの量を超えたらアクションを実行する
SIMの利用開始からの累積データ通信量が一定を超えたらアクションを実行するルール
type
CumulativeTrafficRule
limitTotalTrafficMegaByte
累積データ量(MiB)がこの値を超えたらアクションを実行する
Operatorにひもづく全SIMの日のデータ通信量合計が一定を超えたらアクションを実行するルール
type
DailyTotalTrafficRule
limitTotalTrafficMegaByte
データ量(MiB)がこの量を超えたらアクションを実行する
このルールは、ターゲットとして「targetOperatorId」もしくは「targetTag」のみ有効です。
Operatorにひもづく全SIMの月のデータ通信量合計が一定を超えたらアクションを実行するルール
type
MonthlyTotalTrafficRule
limitTotalTrafficMegaByte
データ量(MiB)がこの量を超えたらアクションを実行する
このルールは、ターゲットとして「targetOperatorId」もしくは「targetTag」のみ有効です。
SIMのステータスが変更されたらアクションを実行するルール
type
SubscriberStatusAttributeRule
targetStatus
Subscriberがこのステータスになった場合にアクションを実行する。例えばtargetStatusを「inactive」に設定しておくと、SIMがinactiveになった時に指定のアクションを実行できます。
targetStatusが取りうる値は以下のとおりです。
null(未設定)
すべてのステータス
ready
readyステータス
active
activeステータス
inactive
inactiveステータス
suspended
suspendedステータス
terminated
terminatedステータス
サポートされる変数(この変数は、Actionの中で設定すると実行時にその値を取得できます)
${newStatus}
変更後のステータス
${oldStatus}
変更前のステータス
SIMの速度クラスが変更されたらアクションを実行するルール
type
SubscriberSpeedClassAttributeRule
targetSpeedClass
Subscriberがこの速度クラスになった場合にアクションを実行する。例えばtargetSpeedClassを「s1.minimum」に設定しておくと、SIMがs1.minimumの速度クラスになった時にアクションを実行できます。
targetSpeedClassが取りうる値は以下のとおりです。
null(未設定)
すべての速度クラス
s1.minimum
速度クラス s1.minimum
s1.slow
速度クラス s1.slow
s1.standard
速度クラス s1.standard
s1.fast
速度クラス s1.fast
SIMの有効期限が切れた時にアクションを実行するルール
type
SubscriberExpiredRule
 サポートされる変数(この変数は、Actionの中で設定すると実行時にその値を取得できます)
${newStatus}
有効期限が切れた後のステータス
${oldStatus}
有効期限が切れる前のステータス

actionConfigList[]

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

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

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

type
ChangeSpeedClassAction
SIMのSpeedClassを変更するアクション
SendMailAction
メールを送るアクション
SendMailToOperatorAction
オペレーターの登録メールアドレスにメールを送るアクション
ActivationAction
SIMの状態をActive(使用中)にするアクション
DeactivationAction
SIMの状態をInactive(休止中)にするアクション
ExecuteWebRequestAction
指定のURLにリクエストをするアクション
InvokeAWSLambdaAction
AWS Lambdaを呼び出すアクション
properties
executionDateTimeConst
すべてのアクションに共通の必須パラメータです。ルールの判定が有効になった際、どのタイミングでアクションを実行するかを指定します。
executionDateTimeConstが取りうる値は以下のとおりです。
IMMEDIATELY
すぐに再実行
BEGINNING_OF_NEXT_MONTH
翌月初
BEGINNING_OF_NEXT_DAY
翌日開始時
AFTER_ONE_DAY
1日後
NEVER
実行/再評価を行わない

アクション毎に固有のパラメータは、下記のとおりです。

アクション一覧

現在、以下のアクションを利用できます。

SIMのSpeedClassを変更するアクション
type
ChangeSpeedClassAction
speedClass
“s1.slow”,“s1.standard"などの速度クラスを設定する
メールを送るアクション
type
SendMailAction
to
送付先メールアドレス
title
メールタイトル
message
メール本文
メールのタイトル、および本文には、以下の変数を利用することが可能です。
${imsi}
対象SIMのIMSI
${operatorId}
対象SIMを持つOperatorのID
${date}
送信日付(yyyy/m/d)
${year}
送信年 (yyyy)
${month}
送信月 (m)
${date}
送信日 (d)
またこれ以外にも、ルールでサポートされる変数を利用することができます。
Operatorにメールを送るアクション
type
SendMailToOperatorAction
title
メールタイトル
message
メール本文
メールのタイトル、および本文には、「メールを送るアクション」と同じ変数が利用できます。
SIMの状態をActive(使用中)にするアクション
type
ActivationAction
SIMの状態をInactive(休止中)にするアクション
type
DeactivationAction
指定のURLにリクエストをするアクション
type
ExecuteWebRequestAction
url
接続先URLとパラメーター
httpMethod
GET,POST,PUT,DELETEのいずれか
contentType
application/jsonなどのContentType
headers
ヘッダーに設定する値(hash)(任意)
body
リクエストボディにセットする文字列(任意) GET,DELETEの場合は設定できません
メールのタイトル、および本文には、「メールを送るアクション」と同じ変数が利用できます。
url,headersおよびbodyには、以下の変数を設定できます
${imsi}
対象SIMのIMSI
${operatorId}
対象SIMを持つOperatorのID
${date}
送信日付(yyyy/m/d)
${year}
送信年 (yyyy)
${month}
送信月 (m)
${date}
送信日 (d)
またこれ以外にも、ルールでサポートされる変数を利用することが可能です。
AWS Lambdaを呼び出すアクション
type
InvokeAWSLambdaAction
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を取得するような実装を検討してください。

設定サンプル

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

Subscriberの速度変更時に、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