Senselinkとの連携

バージョン

改訂日

改訂内容

v1.1.0

2020/7/16

初稿

v1.2.1

2020/11/10

登録者データの同期化の使用法についての紹介を追加

v2.1.0

2021/04/30

用語を修正

LINK API について

Link APIは、SenseLinkプラットフォームのクラウド機能をカプセル化するための一連のインターフェースメソッドです。インターフェースメソッドには、プラットフォームRESTfulインターフェースのカプセル化と、プラットフォームのMqttメッセージのプッシュメカニズムのカプセル化の、主に2つのタイプがあります。プラットフォームが提供するクラウド機能を、一般的なJavaメソッドを呼び出すのと同じように使用することができます。＊JCVのSenselinkプラットフォームについては、下記リンクをご参照ください：https://docs.japancv.co.jp/senselink/

Link APIの使用

Link APIは主に、HttpApiClientとMqttApiClientの2つのコアタイプを提供しており、それぞれのタイプで提供されるメソッドを使用することでSenseLinkプラットフォームとの直接的な通信が実現できます。その方法を以下に紹介します。

HttpApiClient：プラットフォームのRESTful APIのカプセル化用であり、通信にはhttpプロトコルを使用し、共に同期化メソッドであるためワーカースレッドで使用する必要があります
MqttApiClient：プラットフォームメッセージのプッシュメカニズムのカプセル化用であり、通信にはMqttプロトコルを使用し、長距離通信を確立してメッセージのTopicにサブスクライブすることで、プラットフォームメッセージのプッシュを受信します

インターフェースメソッドに関するRESTful APIとMqtt Topicの詳細な定義については、「API仕様書」をご参照ください。

Link APIの初期化

Link APIは、統一された初期化エントリーを提供します。サーバーのURL、リクエストの読み込みと書き込みのタイムアウト、インターフェースから返される言語タイプなどを設定する必要があります。具体的な使用方法は以下の通りです。

// 初期化   
LinkSDKHelper.getInstance().init(“https://link.japancv.co.jp/sl/”, this)
         .setConnectTimeout(10 * 1000)
         .setReadTimeout(30 * 1000)
         .setWriteTimeout(10 * 1000)
         .setLanguage(LinkSDKHelper.LanguageTypeEnum.ZH)  // サーバーから返される情報の言語を設定します
         .addInterceptor(new ResponseInterceptor())  // インターセプターを設定します
         .setDebug(true);

初期化後、具体的なメソッドを呼び出して特定のサービスを実行できます。

RESTful APIのカプセル化方法

各RESTful APIインターフェースは、対応するJavaのメソッド実行をカプセル化します。具体的なエンティティークラスは、リクエストで要求されたパラメーターの受渡値とリクエストの結果データの両方によってカプセル化されています。例えば、認識レコードをアップロードするためにv2/recordリクエストを実行する場合、以下のように記述します。

    // パラメーターエンティティクラス
    RecordParameter recordParameter = new RecordParameter();
    recordParameter.setUserId(2547);
    recordParameter.setMode(2);
    recordParameter.setSignTime((int) (System.currentTimeMillis() / 1000));
    recordParameter.setType(1);
    recordParameter.setInTime(0);
    recordParameter.setEntryMode(1);
    Bitmap bitmap = BitmapFactory.decodeStream(mAppContext.getAssets().open("test.jpg"));
    recordParameter.setUsername("testUserName");
    // 誤ったbase64 文字列をアップロードするとエラーが発生します
    recordParameter.setSignBgAvatar(Base64Utils.bitmapToBase64(bitmap));
    recordParameter.setSignAvatar(Base64Utils.bitmapToBase64(bitmap));
    recordParameter.setDocPhoto(Base64Utils.bitmapToBase64(bitmap));
    recordParameter.setIcNumber("235113");
    recordParameter.setIdNumber("460003199809086744");

    // 特定のリクエストを実行するためにカプセル化されたメソッドの呼び出します。結果はリクエスト結果の統合されたラッパークラスを指します。
    Result<RecordResult> recordResultResult = HttpApiClient.uploadRecord(recordParameter);
    if(recordResultResult.isSuccess()){
        // リクエスト結果データの取得と処理です。RecordResult は、リクエスト結果データのエンティティクラスを指します。
            RecordResult body = recordResultResult.getBody(RecordResult.class);
        // todo: 具体的な操作の実行。
  } else {
          // リクエストの例外です。詳細についてはAPIのドキュメントをご参照ください
  }
}

以下のように、実行のための比較的シンプルなパラメーターを使用して、APIインターフェースに複数のパラメーターを直接受け渡すことができます。

デバイスのログイン操作

// リクエストパラメーター
// 同期化メソッドの呼び出しです。ワークスレッドで実行する必要があります
Result<LoginResult> loginResult = HttpApiClient.login(
                                  "account", "password", "SPS", AppUtils.getAndroidId(ContextUtils.getContext()));

ユーザーIDに基づく詳細なユーザー情報の取得

int userId = 5;
Result result = HttpApiClient.getUserInfo(userId);

「RESTful APIインターフェースの定義」と「APIとメソッド間の通信」の詳細については、API仕様書をご参照ください。

Mqttのプッシュメカニズムのカプセル化のメソッド

各MqttメッセージのプッシュTopicは、対応するJavaメソッドをカプセル化します。Topicにサブスクライブされるメッセージは、次のようにコールバックを登録することで受信されます。

サーバーとのMqtt長距離接続を以下のようにして確立します。

MqttApiClient.connectMqtt(new IMqttActionListener() {

      @Override
      public void onSuccess(IMqttToken iMqttToken) {
        // 接続成功
      }

      @Override
      public void onFailure(IMqttToken iMqttToken, Throwable throwable) {
        // 接続失敗
      }

    }, new IConnectionLost() {

      @Override
      public void onConnectionLost(Throwable cause) {
               // 接続が切断されました
      }
});

デバイスの登録者グループ変更にサブスクライブします

    // 登録者グループ変更にサブスクライブします
    MqttApiClient.registerGroupChangeListener(new MessageCallback() {

       @Override
       public void success(MqttMessage msg) {

                 // json データがプッシュメッセージの本文です。
                  String json = new String(msg.getPayload());
              // バックグラウンドでデバイスを削除し、空の文字列を処理せずにプッシュします。
            if (TextUtils.isEmpty(json)) {
                    return;
            }

            // データを取得します。Group classはメッセージデータに対応するエンティティクラスです。
            Pair<List<Group>, Boolean> pushGroupList =
                                          DataConverter.convertJsonToGroupList(json);
            // 具体的な業務に従ってデータを処理します
         }

       @Override
       public void error(int code, String msg, Throwable throwable) {
                         // サブスクリプト例外／メッセージプッシュ例外
       }
    });

デバイスの登録者グループ変更のサブスクライブを解除します

    MqttApiClient.unRegisterGroupChangeListener();

「Mqtt Topic の定義」および「Topic のサブスクライブとメソッド間の通信」の詳細については、Thunder SDK API Documentをご参照ください。

主な使用プロセスについて

Link APIはSenselinkプラットフォームと簡単に通信する方法を提供しますが、一部の機能を使用する際には一定のプロセスステップに従わなければなりません。つまりRESTful APIインターフェースとMQTTトピックへのサブスクリプションの両方で、シーケンスに従う必要があります。以下、使用のシーケンスの観点から主要な機能の流れを中心に説明しています。

ログインと登録のステップ

SenseLinkプラットフォームの機能を利用するためには、ログインと登録操作が必要です。これにより、デバイスをプラットフォームに含めて一元管理することができます。通信プロセスの簡単な説明は以下の通りです。

主なステップの説明は以下の通りです。

（1）デバイスのログイン：最初にプラットフォームからパブリックキーを取得するためにrequestHttpApiClient.getRsa()インターフェースをリクエストし、パブリックキーを使用してクリアテキストのパスワードを暗号化してログイン操作を行うためにHttpApiClient.login()インターフェースをリクエストします。2つのステップはHttpApiClient.login()メソッドを使用することで完了します。このメソッドは、メソッドのパラメーターとしてアカウント番号、暗号化されたパスワード、デバイスのタイプとデバイスのDUIDのみを受け渡すだけで済みます。

トークン：全てのインターフェースのリクエストには、7日間有効なトークンを使用する必要があります。失効後は403エラーが返されますので、この場合は再度ログインして取得する必要があります。
newDeviceKey：trueの場合、現在のデバイスがプラットフォームの一元管理対象に含まれていないこと意味しますので、デバイス登録の操作を行う必要があります。

（2）デバイスの登録：登録を行うには、最初にHttpApiClient.register()インターフェースをリクエストし、登録が完了した後にデバイスと登録者グループを結合するためにHttpApiClient.bindDefaultGroup()をリクエストする必要があります（以降の登録者データの配信管理のため）。2つのメソッドはHttpApiClient.register()メソッドを適用することで完了し、デバイス名、デバイスの場所、アクセスコントロールの入口と出口の方向などのパラメーターを受け渡す必要があります。

device ldid：プラットフォーム上のデバイスの一意の識別コードであり、デバイスを区別するために使用されます。
companyId：デバイスに対応する企業IDであり、各企業には複数の登録者グループがあります。

オブジェクトモデルの同期化戦略

オブジェクトモデル（TSL）に関する機能は、SenseLink2.3.0以降からサポートしています。これらの機能を使用する前に、サーバーのバージョン番号を特定する必要があります。サーバーがこれらの機能をサポートしていれば、予期しない例外が発生すること無くオブジェクトモデルを同期化することができます。この操作は構成の同期化の前にセットする必要があり、フローチャートは以下の図の通りです。

（1）オブジェクトモデルに関する機能がサーバーによってサポートされているかどうかを判断するために、HttpApiClient.getServerVersion()を呼び出して、現在接続されているサーバーのバージョン番号を取得します。サーバーのバージョン番号が2.3.0以上であれば、これらの機能はサポートされていますので、次の操作に進むことができます。そうでない場合は（5）まで進んでください。

（2）ローカルオブジェクトモデルのMD5を計算し、入力パラメーターとしてHttpApiClient.checkTslExist()を呼び出して、フラグのゾーンビットを取得すると同時にクラウド上にローカルオブジェクトモデルが存在するかどうかをチェックします。flag==1の場合は、オブジェクトモデルがすでに存在していることを意味しますので、アップロードする必要はありません。そうでない場合はHttpApiClient.uploadTsl()を呼び出してオブジェクトモデルをアップロードします。

（3）HttpApiClient.checkTslLanguageExist(language)を呼び出します（zh：簡体字中国語、zh-tw：繁体字中国語、en：英語）。クラウド上に対応する言語パッケージが存在するかどうかをチェックし、クラウドの言語パッケージのゾーンビットとMD5を取得します。flag==1であり、かつクラウドの言語パッケージのMD5とローカルの言語パッケージのMD5が一致している場合は、言語パッケージがすでに存在しているということを意味しますので、アップロードする必要はありません。そうでない場合は、HttpApiClient.uploadTslLanguage()を呼び出して言語パッケージをアップロードします。

（4）言語パッケージが複数ある場合は、（3）のステップを繰り返します。

（5）構成の同期化に関する操作を行います。

デバイス構成の同期化戦略

デバイスの構成パラメーターは、2つの方法で設定することができます：UIインターフェースを介した設定と、SenseLinkクラウドを介した設定と発行です。通信の簡単な説明は以下の図の通りです。

（1）ユーザーが設定ページから構成を変更した後に、システムの設定モジュールが変更された構成パラメーターをバックグラウンドにアップロードし、最終的に構成の変更を送信します。

（2）バックグラウンドで構成が変更される際に、MQTTを介して構成変更のプッシュを送信します。通知を受信するとシステムの設定モジュールはHTTPを介して最新のサーバー構成を取得してデバイスの構成パラメーターを更新し、最終的に構成の変更を送信します。

（3）デバイス構成がバックグラウンドでリセットされると、MQTTを介してデフォルト構成の復元のプッシュを送信します。通知を受信するとシステム設定モジュールは全ての構成をリセットし、構成のリセットをバックグラウンドにアップロードして最終的に構成の変更を送信します。

登録者データの同期化戦略

登録者データの同期化とは企業の対応する登録者データをデバイス側がプラットフォーム側から取得することを意味し、データには主に登録者の基本情報と認証に必要な顔写真ライブラリが含まれます。データの同期化の通信プロセスの簡単な説明は次の通りです。

（1）デバイスのログインが完了し、Mqtt Brokerとの長距離のMqtt通信が確立された後に、「デバイスの登録者グループ変更Topic」へアクティブにサブスクライブする必要があります。サブスクライブの完了後、ただちにメッセージのプッシュを受信し、デバイスに属する全ての登録者グループの情報を取得することができます（キー項目は登録者グループのid）。Topicへのサブスクライブの解除は、データ受信後に行うことができます。

（2）（1）で全ての登録者グループのidが取得できたら、続けて「単一登録者グループ内の、全登録者データTopic」にサブスクライブし、サブスクライブが完了したら当該登録者グループの全ての登録者情報を取得することができます（キー項目はuser_idとimage_url）。Topicへのサブスクライブの解除は全グループの登録者情報の受信後に行うことができます。

（3）（2）で取得した user_idとimage_urlによって、RESTFulインターフェースを介して詳細な登録者情報とアバターを取得することができます。全ての登録者データを取得するには、このステップを繰り返す必要があります。

（4）登録者データの最初の取得後に、「単一の登録者グループ内の登録データ変更のTopic」にサブスクライブする必要があります。サブスクライブの完了後、ただちに登録者のインクリメントリストと変更タイプが返されますので、変更タイプに応じてデータを処理する必要があります。

前へ開発マニュアル次へオブジェクトモデル（TSL）説明

最終更新 2 年前