2.11 イベントサブスクリプション API

2.11.1 概要

外部システムはSenseLinkのサブスクリプションサービスを利用することで、SenseLinkのイベントをサブスクライブすることができます。SenseLinkはデバイスの認証とアラート（以下、「イベント」）をPOSTリクエスト（以下、「Push」）することができます。

サブスクリプションサービスの概要

2.11.2 利用の開始

SenseLink Cloudをご利用の場合、当節で記載される手順・設定の他にJCVサポート窓口へ以下の情報を申請してください。申請およびJCVサポート窓口の処理が完了するまで、イベントサブスクリプション機能は利用できません。

• イベントを処理するAPIエンドポイント（アプリケーションのURL）

• 上記エンドポイントのIPアドレス

サブスクリプション申請時に提出する情報は以下のものです

• 固定IPアドレスとポート番号（必須）

• URL（サブスクリプションを受け取るクライアント側URL）（必須）

  ※注：クライアント側URLとの通信に際し、BASIC認証などの認証技術は対応しておりません。

• アカウントID （必須）

• テナントID（オプション）

イベントをサブスクライブする外部システムのAPIエンドポイントは、SenseLinkのWeb UIのナビゲーションメニュー [システム管理]→[Open Platform] 内の サブスクリプションサービスステータス欄、もしくは本マニュアル内のAPIで設定および更新することができます。

SenseLink Cloudのイベントサブスクリプションサービスステータス欄

Enterprise、Enterprise Proのイベントサブスクリプションサービスステータス欄

サブスクリプションサービス設定画面が表示されます。

イベントサブスクリプション設定画面

Enterprise、Enterprise Proのサブスクリプションサービス設定画面

イベント処理サーバーアドレスの欄に、連携する外部システムのサーバーアドレスを入力してください。http、httpsをサポートしています。https://またはhttps://から入力してください。

サブスクリプションイベントタイプ欄では、サブスクライブするイベントのタイプを選んでください。デバイスで認証が行われた際に認証レコードをPushで受け取るには認証レコードを、デバイスアラートが発生した場合にPushで受け取るにはデバイスアラートを選択してください。両方を選択することも可能です。

サブスクリプションを更新した際に、再保存時に認証レコードタイプ/デバイスアラートタイプが「未選定」の状態になる場合があります。その場合は、再設定してください。

設定が完了したら、保存ボタンをクリックしてください。Open Platform画面に戻ります。 サブスクリプションサービスステータスがNormalと表示されていれば、イベントがサブスクライブされています。

2.11.3 サブスクリプションサービスの設定の変更と停止

サブスクリプションサービスの設定を変更するにはサブスクリプションサービス欄の詳細ボタンをクリックしてください。

サブスクリプションサービスを停止するにはサブスクリプション停止ボタンをクリックしてください。サービスが停止され、外部システムにイベントがPushされなくなります。

サブスクリプションサービスの設定を修正するには、サブスクリプション更新ボタンをクリックしてください。設定内容を変更できます。変更内容を入力後、保存してください。

イベントサブスクリプション設定画面

Enterprise、Enterprise Proのサブスクリプションサービス変更画面

2.11.4 イベントの再Push

イベントのPush後、外部システムは100秒以内にレスポンスを返却するか、リターンコード200を返却する必要があります。

レスポンスが100秒以内に返却されない場合、またはリターンコードが200以外の場合はエラーとみなされ、SenseLinkはそのイベントを再Pushしません。その後SenseLinkは外部システムのサブスクリプションステータスを「異常」に変更し、エラーログとして保存されます。ただし、その後発生した新しいイベントのPushには影響はありません。

なお、レスポンスが100秒以内に返却された、かつリターンコードが200になった場合、サブスクリプションステータスは「正常」に戻ります。

2.11.5 イベントPushログ

Open Platform画面のサブスクリプションサービスステータス欄の詳細をクリックし、サブスクリプションサービスの設定画面にあるログボタンをクリックすると、最新のイベントPushの結果（以下、「ログ」）を確認することができます。

SenseLink Cloudのサブスクリプションサービスのログボタン

Enterprise、Enterprise Proのサブスクリプションサービスのログボタン

ログは最大100件まで保存され、100を越えると古いものから順に削除されます。各ログの詳細ボタンをクリックすると認証レコードページまたはデバイスアラートページに遷移し、イベントの詳細を確認することができます。 イベントタイプまたはステータスで、ログを検索することができます。リセットボタンをクリックすると検索による絞り込みがリセットされ、すべてのログが表示されます。

ログ

テストイベント送信ボタンをクリックすると、テストイベントを連携中の外部システムにPush することができます。 認証レコードとデバイスアラートが選択されている場合、または認証レコードのみが選択されている場合は認証レコードのテストイベントが送信されます。 デバイスアラートのみが選択されている場合、デバイスアラートのテストイベントが送信されます。

2.11.6 イベントPushのプロトコル

リクエスト方法

POST application/json

イベントPushの例

認証レコード :

{
    messageId: '75835750-6dd9-4eed-a929-ba1b4c062405',
    eventType: 30000,
    sendTime: 1583726626015,
    data: { 
        id: 120260,
        userId: 30707,
        name: '次郎',
        type: 1,
        avatar: '5e65c020f54fd90001fe4a33',
        direction: 0,
        verifyScore: 0,
        receptionUserId: 0,
        receptionUserName: '',
        groups: [ { id: 1, name: 'Default group', type: 1 } ],
        deviceName: 'SenseTest',
        sn: 'SPS-e33b1811dbd9189c5eeedffd557fd779',
        signDate: '2020-03-09',
        signTime: 1583726625,
        signAvatar: '5e65c021f54fd90001fe4a37',
        signBgAvatar: '5e65c021f54fd90001fe4a38',
        companyId: 1,
        mobile: '18014398265',
        icNumber: '',
        idNumber: '',
        jobNumber: '3867452109',
        remark: 'welcome',
        entryMode: 1,
        signTimeZone: '+08:00',
        docPhoto: '',
        latitude: 0,
        longitude: 0,
        address: '',
        location: 'SZ-40F',
        abnormalType: 40001,
        userIcNumber: '4751283096',
        userIdNumber: '1g2qW2hz5OwbudHe5gekKbZtmUt0Xwfy',
        bodyTemperature: 38,
        mask: 1
    }
}

デバイスアラート :

{
    messageId: '5ee92a0e-7c6b-416c-8843-54a154a3a409',
    eventType: 30100,
    sendTime: 1583726801752,
    data:
        {
            id: 35569,
            traceId: '1583726800000',
            code: 10001,
            alarmTime: '2020-03-09 12:06:40',
            level: 1,
            deviceId: 204,
            deviceSn: 'SPS-e33b1811dbd9189c5eeedffd557fd779',
            deviceLocation: 'SZ-40F',
            deviceName: 'SenseTest',
            resloveOption: 3,
            alarmPhoto: '5e65c0d1f54fd90001fe4a39',
            companyId: 1,
            description: 'Device removal',
            releaseTime: '',
            status: 3
        }
}

Pushするイベントのパラメーター

パラメーター名	型	必須	説明
messageId	string	Yes	イベントの固有の識別子
eventType	string	Yes	30000：認証レコード、30100：デバイスアラート
sendTime	string	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	認証時写真（大）
companyId	long	企業ID
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	アラート写真
companyID	long	企業ID
description	string	アラートの説明
releaseTime	string	アラートの解除時間
status	int	アラートのステータス。1：アラート作動中、2：解除中、3：解除済み

通常のレスポンス

{
 "code": 200,
 "message": "success",
 "desc": "",
 "data": {}
}

レスポンスのフィールド

パラメーター名	型	必須	説明
code	int	Yes	リターンコード。200 は成功を示し、その他のコードは失敗を示します
message	string	Yes	リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します
desc	string	No	リターンの説明
data	object	No	データ

2.11.7 サブスクリプション更新API (/api/v4/event/updateSub)

概要

イベントのサブスクリプションを追加または更新します。

過去のバージョンを引き続きご利用いただくこともできます。詳細な手順については、過去のバージョンのマニュアルをご参照ください。

リクエストアドレスの例

https://HOST:PORT/api/v4/event/updateSub

リクエスト方法

POST application/json

リクエストパラメーター

パラメーター名	型	必須	説明
recognition_records_types	list<int>	Yes	認証レコードの異常のタイプ。0 - 正常な認証レコード、10001：IDカード不一致、10002：認証カード不一致、10003：認証コード不一致、20001：ビジターが有効期限外、20002：アクセス期限内ではない、30001：無効な ID カード、30002：無効な IC カード、30003：無効な QR コード、40001：異常な体温、50001：マスク着用なし
device_alarm_types	list<int>	Yes	アラートのタイプ。10001：デバイスの盗難アラート、10002：ドア・ゲート強制突破アラート、10003：ドアセンサータイムアウト、10004：パスワードクラッキング、10005：（サポートされないアラートです。現在利用できません）、10006：サーモグラフィカメラ接続異常、20001：カメラの汚れ、20002：Non-Living アタック（非生体による認証）、20003：消防アラート、30001：デバイスオフラインアラート、40001：特徴量抽出エラー
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":200,
    "message":"OK",
    "data":{
        "recognition_records_types":[
            0,
            10001,
            10002
        ],
        "device_alarm_types":[
            20003,
            30001,
            40001
        ],
        "event_dest":"https://ip:port/eventRcv",
        "sub_status":1
    }
}

レスポンスのフィールド

パラメーター名	型	説明
code	int	リターンコード。200 は成功を示し、その他のコードは失敗を示します
message	string	リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します
desc	string	リターンの説明
data	object	データ

dataフィールドの説明

パラメーター名	型	説明
recognition_records_types	list<int>	認識レコードタイプの配列
device_alarm_types	list<int>	デバイスアラートの配列
event_dest	string	イベントをサブスクライブする外部システムのサーバーアドレス
sub_status	int	サブスクリプションサービスのステータスです。0：構成されていません、1：正常、2：異常（最後のPushステータスに基づく）

エラーレスポンスのフィールド

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": 200,
 "message": "success",
 "desc": "",
 "data": {}
}

レスポンスのフィールド

パラメーター名	型	説明
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/v4/event/viewSub)

概要

サブスクリプションの詳細を表示します。

リクエストアドレスの例

https://HOST:PORT/api/v4/event/viewSub

リクエスト方法

GET

認証パラメーター

パラメーター名	型	必須	説明
app_key	string	Yes	Appキー
sign	string	Yes	シグネチャ。1.3.1 シグネチャ（sign）の計算の項を参照してください。
timestamp	string	Yes	タイムスタンプ

通常のレスポンス

{
    "code": 200,
    "message": "success",
    "desc": "",
    "data": {
        "recognition_records_types": [
            50001,
            40001
        ],
        "device_alarm_types": [
            10001,
            10002
        ],
        "event_dest": "https://ip:port/eventRcv",
        "sub_status": 1
    }
}

レスポンスのフィールド

パラメーター名	型	説明
code	int	リターンコード。200 は成功を示し、その他のコードは失敗を示します
message	string	リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します
desc	string	リターンの説明
data	object	データ

dataフィールドの説明

パラメーター名	型	説明
recognition_records_types	list<int>	認証レコードの異常のタイプ。0 - 正常な認証レコード、10001：IDカード不一致、10002：認証カード不一致、10003：認証コード不一致、20001：ビジターが有効期限外、20002：アクセス期限内ではない、30001：無効な ID カード、30002：無効な IC カード、30003：無効な QR コード、40001：異常な体温、50001：マスク着用なし
device_alarm_types	list<int>	アラートのタイプ。10001：デバイスの盗難アラート、10002：ドア・ゲート強制突破アラート、10003：ドアセンサータイムアウト、10004：パスワードクラッキング、10005：（サポートされないアラートです。現在利用できません）、10006：サーモグラフィカメラ接続異常、20001：カメラの汚れ、20002：Non-Living アタック（非生体による認証）、20003：消防アラート、30001：デバイスオフラインアラート、40001：特徴量抽出エラー
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": 200,
 "message": "success",
 "desc": "",
 "data": {
 "pushTime": "2019-10-11 00:00:00",
 "status": 200,
 "eventTypeId": 30000,
 "eventMessage": {}
 }
}

レスポンスのフィールド

パラメーター名	型	説明
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": 200,
 "message": "success",
 "desc": "",
 "data": {}
}

レスポンスのフィールド

パラメーター名	型	説明
code	int	リターンコード。200 は成功を示し、その他のコードは失敗を示します
message	string	リターン情報です。インターフェース実行情報を記録します。success は成功の情報を示し、その他は失敗を示します
desc	string	リターンの説明
data	object	リターンデータ

エラーレスポンスのフィールド

コード	メッセージ	説明
60001	openapi status error	OpenAPI 機能のステータスが利用可能であることをご確認ください （「利用中」または「変更のレビュー待ち」）
60002	not config event sub	サブスクリプションサービスが構成されていません