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で設定および更新することができます。

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

イベント処理サーバーアドレスの欄に、連携する外部システムのサーバーアドレスを入力してください。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の例

認証レコード :

{
    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するイベントのパラメーター

認証レコードデータの属性 :

group フィールドの説明

デバイスのアラートレコードのデータ属性 :

通常のレスポンス

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

レスポンスのフィールド

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

概要

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

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

リクエストアドレスの例

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

リクエスト方法

POST application/json

リクエストパラメーター

認証パラメーター

通常のレスポンス

{
    "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
    }
}

レスポンスのフィールド

dataフィールドの説明

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

2.11.8 サブスクリプション停止API (/api/v3/event/stopSub)

概要

イベントのサブスクリプションを停止します。

リクエストアドレスの例

https://HOST:PORT/api/v3/event/stopSub

リクエスト方法

GET

認証パラメーター

通常のレスポンス

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

レスポンスのフィールド

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

2.11.9 サブスクリプション詳細表示API (/api/v4/event/viewSub)

概要

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

リクエストアドレスの例

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

リクエスト方法

GET

認証パラメーター

通常のレスポンス

{
    "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
    }
}

レスポンスのフィールド

dataフィールドの説明

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

2.11.10 イベントPushログの表示 (/api/v3/event/viewLog)

概要

イベントのPushログを表示します。

サブスクリプションサービスが起動されなくても、該当するAPIを使って前に生成されたログを取得できます。

リクエストアドレスの例

https://HOST:PORT/api/v3/event/viewLog

リクエスト方法

GET

認証パラメーター

通常のレスポンス

{
 "code": 200,
 "message": "success",
 "desc": "",
 "data": {
 "pushTime": "2019-10-11 00:00:00",
 "status": 200,
 "eventTypeId": 30000,
 "eventMessage": {}
 }
}

レスポンスのフィールド

dataフィールドの説明

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

2.11.11 テストイベントの送信 (/api/v3/event/sendTest)

概要

テストイベントをPush送信します。

リクエストアドレスの例

https://HOST:PORT/api/v3/event/sendTest

リクエスト方法

GET

認証パラメーター

通常のレスポンス

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

レスポンスのフィールド

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

前へ2.10 部署の API 次へ3 Push通知

最終更新 2 年前