Soracom

Users

ドキュメント
Home ドキュメント イベントハンドラー はじめに

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

イベントハンドラーでは、監視対象、ルール、アクションの 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:0011/1 (当日) 20:00この時刻にルールを満たして、監視対象の IoT SIM を休止状態 (通信できない状態) にしたとします。
11/2 (翌日) 0:0011/2 (翌日) 9:00翌日開始日の基準時刻です。この時刻から、翌日の課金が始まりますが、ルールは評価されないため、データ通信量が多くなっても IoT SIM は休止状態になりません。
11/2 (翌日) 15:0011/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_DAY1 日後 (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:0011/1 (当日) 20:00この時刻にルールを満たしたとします。
11/2 (翌日) 0:0011/2 (翌日) 9:00翌日開始日の基準時刻です。
11/2 (翌日) 23:0011/3 (翌々日) 8:00アクションが実行されます。
© 2015-2023 SORACOM
最終更新日: 2023-08-29
Getting Started : 月あたりのデータ通信量を制限する
会社概要 プレスルーム お問い合わせ プライバシー 商標 特定商取引法 契約約款
Facebook Twitter Speaker Deck YouTube Blog