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するイベントのパラメーター
パラメーター名 | 型 | 必須 | 説明 |
messageId | string | Yes | イベントの固有の識別子 |
eventType | int | Yes | 30000:認証レコード 30100:デバイスアラート |
sendTime | long | Yes | イベント発生時刻(デバイス時間) |
data | object | Yes | イベントの対象 |
認証レコードデータの属性 :
パラメーター名 | 型 | 説明 |
id | int | レコード ID |
userId | int | 認証されたユーザーの ID |
name | string | 認証されたユーザーの名前 |
type | int | ユーザーの識別子タイプ |
avatar | string | 認証用顔写真 |
direction | int | デバイスのアクセス方向 |
verifyScore | float | 認証スコア |
receptionUserId | int | 認証されたユーザーの応対者の ID |
receptionUserName | string | 認証されたユーザーの応対者の名前 |
groups | list<group> | 認証されたユーザーのグループ情報 |
deviceName | string | デバイス名 |
sn | string | この認証レコードのデバイス LDID 番号をアップロードします |
signDate | string | 認証レコードの日付 |
signTime | timestamp | 認証時間(秒) |
signAvatar | string | 認証時写真(サムネイル) |
signBgAvatar | string | 認証時写真(大) |
mobile | string | 認証されたユーザーの携帯電話番号 |
icNumber | string | 認証されたユーザーのIC カード番号 |
idNumber | string | 認証されたユーザーの ID 番号(利用できません) |
jobNumber | string | 認証されたユーザーの従業員ID |
remark | string | 特記事項 |
entryMode | int | 認証モード 1:顔認証 2:QR コード 3:カード 4:顔認証とカード 5:ID カード 6:顔認証と ID カード |
signTimeZone | string | 認証レコードのタイムゾーン |
docPhoto | string | ID 写真 |
latitude | double | 緯度 |
longitude | double | 経度 |
address | string | 住所 |
location | string | デバイスの設置場所 |
abnormalType | int | 認証レコードの異常のタイプ 0:なし 10001:IDカード不一致 10002:認証カード不一致 10003:認証コード不一致 20001:ビジターが有効期限外 20002:アクセス期限内ではない 30001:無効な ID カード 30002:無効な IC カード 30003:無効な QR コード 40001:異常な体温 50001:マスク着用なし |
userIcNumber | ||
userIdNumber | (利用できません) | |
bodyTemperature | float | 体温 |
mask | int | マスク着用識別子 0:不明 1:着用なし 2:着用あり |
group フィールドの説明
パラメーター名 | 型 | 説明 |
id | long | グループID |
name | string | グループ名 |
type | int | グループタイプ 1:従業員グループ 2:ビジターグループ 5:拒否リストグループ |
デバイスのアラートレコードのデータ属性 :
パラメーター名 | 型 | 説明 |
id | long | アラートレコードのID |
traceId | string | アラートのシリアル番号。デバイスによって生成されるアラート固有の識別番号です。 |
code | int | アラートのタイプ 10001:デバイスの盗難アラート 10002:ドア・ゲート強制突破アラート 10003:ドアセンサータイムアウト 10004:パスワードクラッキング 10005 :(サポートされないアラートです。現在利用できません) 10006:サーモグラフィカメラ接続異常 20001:カメラの汚れ 20002:Non-Living アタック(非生体による認証) 20003:消防アラート 30001:デバイスオフラインアラート 40001:特徴量抽出エラー |
alarmTime | string | アラート時間 |
level | int | アラートレベル。1:アラート、2:異常 |
deviceId | long | デバイスの ID |
deviceSn | string | デバイスの LDID |
deviceLocation | string | デバイスの設置場所 |
deviceName | string | デバイス名 |
resloveOption | int | アラートの解除オプション 0:解除不要 1:デバイスエンドでの解除のみをサポート 2:リモート解除のみをサポート 3:デバイスエンドまたはリモートでの解除 0:解除不要 10004:パスワードクラッキング 20002:Non-Living アタック(非生体による認証) 30001:デバイスオフラインアラート 1:デバイスエンドでの解除のみをサポート 10003:ドアセンサータイムアウト 20001:カメラの汚れ 10005 :(サポートされないアラートです。現在利用できません) 10006:サーモグラフィカメラ接続異常 3:デバイスエンドまたはリモートでの解除 10001:デバイスの盗難アラート 10002:ドア・ゲート強制突破アラート 20003:消防アラート |
alarmPhoto | string | アラート写真 |
description | string | アラートの説明 |
releaseTime | string | アラートの解除時間 |
status | int | アラートのステータス 1:アラート作動中 2:解除中 3:解除済み |
通常のレスポンス
レスポンスのフィールド
パラメーター名 | 型 | 必須 | 説明 |
code | int | Yes | リターンコード。200 は成功を示し、その他のコードは失敗を示します |
message | string | Yes | リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します |
desc | string | No | リターンの説明 |
data | object | No | データ |
2.11.7 サブスクリプション更新API (/api/v3/event/updateSub)
概要
イベントのサブスクリプションを追加または更新します。
過去のバージョンを引き続きご利用いただくこともできます。詳細な手順については、過去のバージョンのマニュアルをご参照ください。
リクエストアドレスの例
https://HOST:PORT/api/v3/event/updateSub
リクエスト方法
POST application/json
リクエストパラメーター
パラメーター名 | 型 | 必須 | 説明 |
event_type_ids | list<int> | Yes | イベントタイプの ID 30000:認証レコード 30100:アラートPush |
event_dest | string | Yes | イベントをサブスクライブする外部システムのサーバーアドレスを指定します。restful コールバックを利用し、http および https をサポートしています。 スタイルは、 http://ip:port/eventRcv または https://ip:port/eventRcv で、 最大 1,024 文字です。 外部システムのサーバーアドレスは指定された仕様に基づいて申請したパーティーから提供されます。外部システムのインターフェースの認証は必要ありません 空の値で登録しないでください |
認証パラメーター
パラメーター名 | 型 | 必須 | 説明 |
app_key | string | Yes | Appキー |
sign | string | Yes | シグネチャ。1.3.1 シグネチャ(sign)の計算の項を参照してください |
timestamp | string | Yes | タイムスタンプ |
通常のレスポンス
レスポンスのフィールド
パラメーター名 | 型 | 説明 |
code | int | リターンコード。200 は成功を示し、その他のコードは失敗を示します |
message | string | リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します |
desc | string | リターンの説明 |
data | object | データ |
エラーレスポンスのフィールド
code | メッセージ | 説明 |
60001 | openapi status error | OpenAPI 機能のステータスが利用可能であることを確認してください(「利用中」または「変更のレビュー待ち」) |
2.11.8 サブスクリプション停止API (/api/v3/event/stopSub)
概要
イベントのサブスクリプションを停止します。
リクエストアドレスの例
https://HOST:PORT/api/v3/event/stopSub
リクエスト方法
GET
認証パラメーター
パラメーター名 | 型 | 必須 | 説明 |
app_key | string | Yes | Appキー |
sign | string | Yes | シグネチャ。1.3.1 シグネチャ(sign)の計算の項を参照してください |
timestamp | string | Yes | タイムスタンプ |
通常のレスポンス
レスポンスのフィールド
パラメーター名 | 型 | 説明 |
code | int | リターンコード。200 は成功を示し、その他のコードは失敗を示します |
message | string | リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します |
desc | string | リターンの説明 |
data | object | データ |
エラーレスポンスのフィールド
code | メッセージ | 説明 |
60001 | openapi status error | OpenAPI 機能のステータスが利用可能であることを確認してください(「利用中」または「変更のレビュー待ち」) |
60002 | not config event sub | サブスクリプションサービスが構成されていません |
2.11.9 サブスクリプション詳細表示API (/api/v3/event/viewSub)
概要
サブスクリプションの詳細を表示します。
リクエストアドレスの例
https://HOST:PORT/api/v3/event/viewSub
リクエスト方法
GET
認証パラメーター
パラメーター名 | 型 | 必須 | 説明 |
app_key | string | Yes | Appキー |
sign | string | Yes | シグネチャ。1.3.1 シグネチャ(sign)の計算の項を参照してください |
timestamp | string | Yes | タイムスタンプ |
通常のレスポンス
レスポンスのフィールド
パラメーター名 | 型 | 説明 |
code | int | リターンコード。200 は成功を示し、その他のコードは失敗を示します |
message | string | リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します |
desc | string | リターンの説明 |
data | object | データ |
dataフィールドの説明
パラメーター名 | 型 | 説明 |
event_type_ids | list<int> | イベントタイプの ID 30000:認証レコード 30100:アラートPush |
event_dest | string | イベントをサブスクライブする外部システムのサーバーアドレス |
sub_status | int | サブスクリプションサービスのステータス 0:構成されていません 1:正常 2:異常(最後のPushステータスに基づく) |
エラーレスポンスのフィールド
コード | メッセージ | 説明 |
60001 | openapi status error | OpenAPI 機能のステータスが利用可能であることを確認してください(「利用中」または「変更のレビュー待ち」) |
60002 | not config event sub | サブスクリプションサービスが構成されていません |
2.11.10 イベントPushログの表示 (/api/v3/event/viewLog)
概要
イベントのPushログを表示します。
サブスクリプションサービスが起動されなくても、該当するAPIを使って前に生成されたログを取得できます。
リクエストアドレスの例
https://HOST:PORT/api/v3/event/viewLog
リクエスト方法
GET
認証パラメーター
パラメーター名 | 型 | 必須 | 説明 |
app_key | string | Yes | Appキー |
sign | string | Yes | シグネチャ。1.3.1 シグネチャ(sign)の計算の項を参照してください |
timestamp | string | Yes | タイムスタンプ |
通常のレスポンス
レスポンスのフィールド
パラメーター名 | 型 | 説明 |
code | int | リターンコード。200 は成功を示し、その他のコードは失敗を示します |
message | string | リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します |
desc | string | リターンの説明 |
data | object | リターンデータです。イベントサブスクリプションの詳細です |
dataフィールドの説明
パラメーター名 | 型 | 説明 |
push_time | string | Push時間 |
status | int | リターンステータス 200:成功 404:サーバー応答不可 500 : 内部例外 |
event_type_id | int | イベントタイプの ID 30000:認証レコード 30100:アラートPush |
event_message | string | Pushメッセージ本体 |
エラーレスポンスのフィールド
コード | メッセージ | 説明 |
60001 | openapi status error | OpenAPI 機能のステータスが利用可能であることを確認してください(「利用中」または「変更のレビュー待ち」) |
60002 | not config event sub | サブスクリプションサービスが構成されていません |
2.11.11 テストイベントの送信 (/api/v3/event/sendTest)
概要
テストイベントをPush送信します。
リクエストアドレスの例
https://HOST:PORT/api/v3/event/sendTest
リクエスト方法
GET
認証パラメーター
パラメーター名 | 型 | 必須 | 説明 |
app_key | string | Yes | Appキー |
sign | string | Yes | シグネチャ。1.3.1 シグネチャ(sign)の計算の項を参照してください |
timestamp | string | Yes | タイムスタンプ |
通常のレスポンス
レスポンスのフィールド
パラメーター名 | 型 | 説明 |
code | int | リターンコード。200 は成功を示し、その他のコードは失敗を示します |
message | string | リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します |
desc | string | リターンの説明 |
data | object | リターンデータ |
エラーレスポンスのフィールド
コード | メッセージ | 説明 |
60001 | openapi status error | OpenAPI 機能のステータスが利用可能であることを確認してください (「利用中」または「変更のレビュー待ち」) |
60002 | not config event sub | サブスクリプションサービスが構成されていません |
最終更新