はじめに: イベントハンドラーの仕組み | イベントハンドラー

イベントハンドラーでは、監視対象、ルール、アクションの 3 つの要素をひとまとめに設定して「イベント」と呼びます。

たとえば、SIM グループ "sample group" に所属している IoT SIM のデータ通信量が月に 1 GiB (1024 MiB) を超えたら、その IoT SIM を休止状態 (通信できない状態) にする、というイベントを作成する場合は、監視対象、ルール、アクションを、以下のように設定します。

項目	設定例
監視対象	SIM グループ "sample group" に所属している IoT SIM の…
ルール	データ通信量が月に 1 GiB (1024 MiB) を超えたら…
アクション	監視対象の IoT SIM を休止状態 (通信できない状態) にする。

監視対象

状態を監視し、アクションを実行する対象を指定します。

監視対象	説明
サブスクライバー	監視対象の IoT SIM の IMSI を指定します。
グループ (*1)	監視対象のグループを指定します。グループに所属するすべての IoT SIM が監視されます。
IoT SIM (*1)	監視対象の IoT SIM の SIM ID を指定します。
オペレーター (*1)	監視対象のオペレーターを指定します。オペレーターが保有するすべての IoT SIM が監視されます。

(*1) 監視対象に「グループ」「オペレーター」を選択した場合でも、ルール (条件) を満たしたかどうかの判定およびアクションの実行は、IoT SIM ごとに行われます。

セカンダリサブスクライバーだけを監視することはできません

追加のサブスクリプションを契約している場合、監視対象としてセカンダリサブスクライバーの IMSI は指定できません。プライマリサブスクライバーの IMSI を指定してください。

セカンダリサブスクライバーを監視する場合は、監視対象として IoT SIM を指定します。この場合、プライマリサブスクライバーも監視対象になります。

同一の監視対象に複数のイベントを設定できます

ある IoT SIM が複数のイベントのルールを満たした場合、すべてのアクションが実行されます。

監視対象ごとに設定できるイベント数の上限があります。

監視対象	説明
サブスクライバー	同一の IMSI を監視対象に指定したイベント数は、最大 10 件です。
グループ	同一のグループを監視対象に指定したイベント数は、最大 10 件です。
IoT SIM	同一の SIM ID を監視対象に指定したイベント数は、最大 10 件です。
オペレーター	同一のオペレーターを監視対象に指定したイベント数は、最大 10 件です。

たとえば、オペレーターを監視対象に指定したイベントを 10 件設定し、さらに IMSI を指定したイベントを 10 件設定できます。

ルール

アクションを実行するきっかけになるルール (条件) を設定します。たとえば「データ通信量が月に 1 GiB (1024 MiB) を超えたら…」というようなルールを設定できます。

設定可能なルールは、ルールタイプ一覧を参照してください。

ルールを評価するタイミングは保証されません

ルールを評価するタイミングには、さまざまな要因でタイムラグが発生することがあります。

再評価を行うタイミング

データ通信量をルール (条件) にする場合は、ルールを満たしたあとに、同一の監視対象に対して、次に同じルールの評価を再開するタイミングを指定します。

たとえば、「データ通信量が月に 1 GiB (1024 MiB) を超えたら…」というルールの場合は、その月にルールを満たしたあとは同じルールを再評価する必要はありません。このようなときに「翌月初」を指定すると、翌月の初めからルールの評価が再開されます。

SORACOM ユーザーコンソールの [再評価を行うタイミング] で指定する値	SORACOM CLI / SORACOM API で `inactiveTimeoutDateConst` に指定する値	説明
すぐに再評価	`IMMEDIATELY`	評価を停止せずに、継続します。
翌月初	`BEGINNING_OF_NEXT_MONTH`	評価を停止し、翌月の 1 日 0:00 (*1) に評価を再開します。
翌日開始時	`BEGINNING_OF_NEXT_DAY`	評価を停止し、翌日の 0:00 (*1) に評価を再開します。
1 日後	`AFTER_ONE_DAY`	評価を停止し、1 日後 (24 時間後) に評価を再開します。
再評価しない	`NEVER`	評価を再開しません。

(*1) 評価の再開は、UTC (協定世界時) を基準に行われます。たとえば「翌日開始時」を指定した場合は、日本時間ではなく UTC で日付が変わったときに評価が再開されます。

ルールを再評価するときのオフセット (分)

ルール (条件) を評価する時間を、「再評価を行うタイミング」で設定したタイミングからずらすことができます。単位は分です。0～525600 (365 日) の整数を指定します。

例:

再評価を行うタイミング	オフセット (分)	説明
すぐに再評価	`10`	ルールを満たした 10 分後に再評価を始めます。
翌月初	`1440`	ルールを満たした翌月初の 1 日後 (1440 分後) に再評価を始めます。

ルールの「オフセット (分)」では UTC と日本時間の時差を考慮しないでください

予期せぬ課金を避けるためにイベントを作成する場合は、ルールの「オフセット (分)」では UTC と日本時間の時差を考慮しないでください。

イベントハンドラーと課金単位は、時刻の基準として UTC を利用しています。つまり「1 日」の境界は、どちらも UTC の 0:00 (日本時間の 9:00) です。「オフセット (分)」に UTC と日本時間の時差を設定すると、予期せぬ課金が発生する可能性があります。

たとえば、日本時間の 0:00 からルールを再評価する場合は、「オフセット (分)」に 900 (15 時間) を指定します。ただしこの場合、日本時間 11/1 20:00 に条件を満たすと、ルールが再評価されるのは、翌々日の日本時間 11/3 0:00 です。

UTC	日本時間	説明
11/1 (当日) 11:00	11/1 (当日) 20:00	この時刻にルールを満たして、監視対象の IoT SIM を休止状態 (通信できない状態) にしたとします。
11/2 (翌日) 0:00	11/2 (翌日) 9:00	翌日開始日の基準時刻です。この時刻から、翌日の課金が始まりますが、ルールは評価されないため、データ通信量が多くなっても IoT SIM は休止状態になりません。
11/2 (翌日) 15:00	11/3 (翌々日) 0:00	ルールが再評価される基準時刻です。この時刻以降にルールを満たした場合は、再び監視対象の IoT SIM が休止状態になります。

再評価を行うタイミングまで再実行しない

監視対象で「グループ」「IoT SIM」「オペレーター」を選択した場合は、通常は、複数のサブスクライバーが監視対象になります。この場合、監視対象に含まれるサブスクライバーの 1 つがルール (条件) を満たしたときに、そのサブスクライバーに対して 1 回目のアクションが実行されます。

「再評価を行うタイミングまで再実行しない」は、あるサブスクライバーに対してアクションが実行されたあとで、(同一のイベントの監視対象に含まれる) 別のサブスクライバーに対して同じルールをいつ評価するかを指定するオプションです。

SORACOM ユーザーコンソールの [再評価を行うタイミングまで再実行しない] で指定する値	SORACOM CLI / SORACOM API で `runOnceAmongTarget` に指定する値	別のサブスクライバーに対して同じルールを評価するタイミング
オン	`true`	ルールを満たしたサブスクライバーが再評価を行うタイミングで評価を行います。
オフ	`false`	すぐに評価を行います。

設定例

「再評価を行うタイミングまで再実行しない」のオンとオフの違いを理解するために、以下の設定を例に動作を説明します。

項目	説明
監視対象	オペレーター
ルール	オペレーターにひもづく全 IoT SIM の月次データ通信量合計が 100 MiB を超えたら実行
再評価を行うタイミング	翌月初
アクション	メールを送信する

上記の設定のとき、「再評価を行うタイミングまで再実行しない」の設定によって、以下のように動作が変わります。

「再評価を行うタイミングまで再実行しない」の設定	説明
オン	オペレーターにひもづく IoT SIM の月次データ通信量合計が 100 MiB を超えると、1 回だけメールを送信します。再評価を行うタイミング (翌月初) まではメールは送信されません。
オフ	オペレーターにひもづく IoT SIM の月次データ通信量合計が 100 MiB を超えると、オペレーターにひもづく任意の IoT SIM がデータ通信した際に IoT SIM ごとにメールが送信されます。たとえば、IoT SIM が 10 件ひもづいていた場合は、最大 10 回メールが送信されます。

アクション

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

設定可能なアクションは、アクションタイプ一覧を参照してください。

アクションが実行されるタイミングは保証されません

アクションが実行されるタイミングには、さまざまな要因でタイムラグが発生することがあります。

1 つのイベントに最大 5 件のアクションを設定できます

1 件目のアクションですぐにメールを送信し、2 件目のアクションで翌月初に別のメールを送信する、といった設定ができます。なお、月あたりのデータ通信量を制限するでは、3 つのアクションを設定する例を説明しています。あわせて参照してください。
「実行するタイミングが同一のアクション」を複数登録した場合の実行順序は、登録した順序とは関係ありません。アクションのオフセット (分) を設定して実行順序を調節してください。

ルールを満たしたときにアクションの内容は確定します

実行されるアクションは、ルールを満たしたときに設定されていたアクションです。ルールを満たしてからアクションが実行される前にイベントハンドラーの設定を変更した場合でも、変更前の設定に従ってアクションが実行されます。

イベントハンドラーの設定変更は、以下のようなケースが考えられます。

イベントハンドラーの監視対象 (イベントを実行する対象) から外れた。たとえば、グループが変更されたり、グループが解除されたりした。
イベントハンドラーのアクションを変更した。

実行するタイミング

ルールを満たしたときを基準に、アクションを実行するタイミングを指定します。

SORACOM ユーザーコンソールの [実行するタイミング] で指定する値	SORACOM CLI / SORACOM API で `executionDateTimeConst` に指定する値	説明
すぐに実行	`IMMEDIATELY`	すぐに実行します。
翌月初	`BEGINNING_OF_NEXT_MONTH`	翌月の 1 日 0:00 (*1) に実行します。
翌日開始時	`BEGINNING_OF_NEXT_DAY`	翌日の 0:00 (*1) に実行します。
1 日後	`AFTER_ONE_DAY`	1 日後 (24 時間後) に実行します。
実行しない	`NEVER`	実行しません。

(*1) アクションの実行は、UTC (協定世界時) を基準に行われます。たとえば「翌日開始時」を指定した場合は、日本時間ではなく UTC で日付が変わったときに実行されます。

アクションのオフセット (分)

アクションを実行する時間を、「実行するタイミング」で設定したタイミングからずらすことができます。単位は分です。0～525600 (365 日) の整数を指定します。

例:

実行するタイミング	オフセット (分)	説明
すぐに実行	`10`	ルールを満たした 10 分後に実行します。
翌月初	`1440`	ルールを満たした翌月初の 1 日後 (1440 分後) に実行します。

UTC と日本時間の時差を考慮してオフセット (分) を設定してください

イベントハンドラーと課金単位は、時刻の基準として UTC を利用しています。つまり「1 日」の境界は、どちらも UTC の 0:00 (日本時間の 9:00) です。

たとえば、日本時間の 8:00 にアクションを実行する場合は、「オフセット (分)」に 1380 (23 時間) を指定します。ただしこの設定の場合、日本時間 11/1 20:00 に条件を満たすと、アクションが実行されるのは、翌々日の日本時間 11/3 8:00 です。

UTC	日本時間	説明
11/1 (当日) 11:00	11/1 (当日) 20:00	この時刻にルールを満たしたとします。
11/2 (翌日) 0:00	11/2 (翌日) 9:00	翌日開始日の基準時刻です。
11/2 (翌日) 23:00	11/3 (翌々日) 8:00	アクションが実行されます。

Soracom

Users

イベントハンドラーの仕組み