2.11 イベントサブスクリプション API
2.11.1 概要
外部システムはSenseLinkのサブスクリプションサービスを利用することで、SenseLinkのイベントをサブスクライブすることができます。SenseLinkはデバイスの認証とアラート(以下、「イベント」)をPOSTリクエスト(以下、「Push」)することができます。
2.11.2 利用の開始
イベントをサブスクライブする外部システムのAPIエンドポイントは、SenseLinkのWeb UIのナビゲーションメニュー [システム管理]→[Open Platform] 内の サブスクリプションサービスステータス欄、もしくは本マニュアル内のAPIで設定および更新することができます。
サブスクリプションサービス設定画面が表示されます。
イベント処理サーバーアドレスの欄に、連携する外部システムのサーバーアドレスを入力してください。http、httpsをサポートしています。https://またはhttps://から入力してください。
サブスクリプションイベントタイプ欄では、サブスクライブするイベントのタイプを選んでください。デバイスで認証が行われた際に認証レコードをPushで受け取るには認証レコードを、デバイスアラートが発生した場合にPushで受け取るにはデバイスアラートを選択してください。両方を選択することも可能です。
サブスクリプションを更新した際に、再保存時に認証レコードタイプ/デバイスアラートタイプが「未選定」の状態になる場合があります。その場合は、再設定してください。
設定が完了したら、保存ボタンをクリックしてください。Open Platform画面に戻ります。 サブスクリプションサービスステータスがNormalと表示されていれば、イベントがサブスクライブされています。
2.11.3 サブスクリプションサービスの設定の変更と停止
サブスクリプションサービスの設定を変更するにはサブスクリプションサービス欄の詳細ボタンをクリックしてください。
サブスクリプションサービスを停止するにはサブスクリプション停止ボタンをクリックしてください。サービスが停止され、外部システムにイベントがPushされなくなります。
サブスクリプションサービスの設定を修正するには、サブスクリプション更新ボタンをクリックしてください。設定内容を変更できます。変更内容を入力後、保存してください。
2.11.4 イベントの再Push
イベントのPush後、外部システムは100秒以内にレスポンスを返却するか、リターンコード200を返却する必要があります。
レスポンスが100秒以内に返却されない場合、またはリターンコードが200以外の場合はエラーとみなされ、SenseLinkはそのイベントを再Pushしません。その後SenseLinkは外部システムのサブスクリプションステータスを「異常」に変更し、エラーログとして保存されます。ただし、その後発生した新しいイベントのPushには影響はありません。
なお、レスポンスが100秒以内に返却された、かつリターンコードが200になった場合、サブスクリプションステータスは「正常」に戻ります。
2.11.5 イベントPushログ
Open Platform画面のサブスクリプションサービスステータス欄の詳細をクリックし、サブスクリプションサービスの設定画面にあるログボタンをクリックすると、最新のイベントPushの結果(以下、「ログ」)を確認することができます。
ログは最大100件まで保存され、100を越えると古いものから順に削除されます。各ログの詳細ボタンをクリックすると認証レコードページまたはデバイスアラートページに遷移し、イベントの詳細を確認することができます。 イベントタイプまたはステータスで、ログを検索することができます。リセットボタンをクリックすると検索による絞り込みがリセットされ、すべてのログが表示されます。
テストイベント送信ボタンをクリックすると、テストイベントを連携中の外部システムにPush することができます。 認証レコードとデバイスアラートが選択されている場合、または認証レコードのみが選択されている場合は認証レコードのテストイベントが送信されます。 デバイスアラートのみが選択されている場合、デバイスアラートのテストイベントが送信されます。
2.11.6 イベントPushのプロトコル
リクエスト方法
POST application/json
イベントPushの例
認証レコード :
デバイスアラート :
Pushするイベントのパラメーター
認証レコードデータの属性 :
group フィールドの説明
デバイスのアラートレコードのデータ属性 :
通常のレスポンス
レスポンスのフィールド
2.11.7 サブスクリプション更新API (/api/v3/event/updateSub)
概要
イベントのサブスクリプションを追加または更新します。
過去のバージョンを引き続きご利用いただくこともできます。詳細な手順については、過去のバージョンのマニュアルをご参照ください。
リクエストアドレスの例
https://HOST:PORT/api/v3/event/updateSub
リクエスト方法
POST application/json
リクエストパラメーター
認証パラメーター
通常のレスポンス
レスポンスのフィールド
エラーレスポンスのフィールド
2.11.8 サブスクリプション停止API (/api/v3/event/stopSub)
概要
イベントのサブスクリプションを停止します。
リクエストアドレスの例
https://HOST:PORT/api/v3/event/stopSub
リクエスト方法
GET
認証パラメーター
通常のレスポンス
レスポンスのフィールド
エラーレスポンスのフィールド
2.11.9 サブスクリプション詳細表示API (/api/v3/event/viewSub)
概要
サブスクリプションの詳細を表示します。
リクエストアドレスの例
https://HOST:PORT/api/v3/event/viewSub
リクエスト方法
GET
認証パラメーター
通常のレスポンス
レスポンスのフィールド
dataフィールドの説明
エラーレスポンスのフィールド
2.11.10 イベントPushログの表示 (/api/v3/event/viewLog)
概要
イベントのPushログを表示します。
サブスクリプションサービスが起動されなくても、該当するAPIを使って前に生成されたログを取得できます。
リクエストアドレスの例
https://HOST:PORT/api/v3/event/viewLog
リクエスト方法
GET
認証パラメーター
通常のレスポンス
レスポンスのフィールド
dataフィールドの説明
エラーレスポンスのフィールド
2.11.11 テストイベントの送信 (/api/v3/event/sendTest)
概要
テストイベントをPush送信します。
リクエストアドレスの例
https://HOST:PORT/api/v3/event/sendTest
リクエスト方法
GET
認証パラメーター
通常のレスポンス
レスポンスのフィールド
エラーレスポンスのフィールド
最終更新