BioStar2 API を利用して、ユーザー情報を更新する場合は、認証端末が正しく動作するために、

正しい理解をし、注意して実施する必要があります。


ここでは、どのような原因で、どのようなことが発生し得るかを説明します。


発生し得る問題を理解せず、むやみなAPI開発を行い、多数の問い合わせ、ご指摘をされることはご遠慮ください。

正しくBioStar2のAPIの特性を理解し、適正なAPIの利用をお願い致します。



どのような問題が起こり得るか？

　

　　・APIで処理したはずが、認証できない。正しく動作しない。

　　・ユーザーの更新が終わらない。　時間がかかる。

　　・同じユーザーが同じ端末で、何度も ”ユーザー更新” されている。




なぜ、このようなことが起こるのか？


　　端末に対してユーザー情報を更新するために、多少の処理時間がかかりますが、この時間を待てずに、

　　連続でユーザー情報の処理を行うことで、処理の可能領域を越え、データの破損が発生してしまうためです。


　　つまり、処理できる範囲のペースで処理をさせる必要があります。




データ破損が起きるのなら、
BioStar2側で、なぜ APIの処理受付を制限しないのか？


　　APIを連続で実行したら、認証機で正しく認証できなくなるくらいならば、APIの受付自体で制限を設け、

　　認証できなくなるような 連続したAPIを受け付けなくするべきではないか？　という考えもあります。


　　しかし、BioStar2では、APIの受付に制限を設けていません。

　　この理由は、制限を設けることで、BioStar2のWEBブラウザからのUI操作ができなくなることを防ぐためです。


　　APIのプログラムによる処理も、WEBブラウザからの UIの操作も、どちらもAPIで処理されます。

　　BioStar2サーバーは、プログラムからの処理なのか、WEBブラウザからの処理なのか？

　　どちらから処理されているかを把握することはできません。


　　このため、APIの受付に制限を設けてしまうと、WEBブラウザ側も操作ができなくなってしまいます。


　　BioStar2を WEBブラウザから操作することは、基本的な利用方法であり、APIの知識を持たない方の可能性が

　　高いです。

　　そして、BioStar2の利用を考えると、大多数がこの利用方法を占めます。

　　APIを使われる方は、APIの知識や、IT関連の知識も有しており、ご自身で工夫できる開発力を持たれています。


　　このため、BioStar2のUIで操作する場合は、視覚的に端末との同期状態が見えるようにしており、

　　また、WEBブラウザからの操作のため、多くのユーザー更新を、処理可能領域を溢れるほど行うことはできません。

　　処理中という理由で、他の処理に制限を掛けてしまい、他のオペレーター操作ができなくなることは

　　望ましくありません。

　　WEBブラウザからの操作可能量は、処理可能領域の中で複数の処理を同時に受付し、処理できるようにしています。


　　BioStar2は、このように BioStar2をWEBブラウザから操作する一般の利用者の利便性を優先して設計しています。 

　　

　　この理由で、APIの受付に制限は設けていません。

　　

　　APIを利用されるような 開発知識を有されている方は、正しい動作をさせるため、

　　利用時にこの特性を理解し、ご自身で工夫することで、処理可能領域を越えないように

　　APIを利用する必要があります。





API利用開発時の工夫

　

　　ここでは、APIを利用した開発を行う上で、これらの起き得る問題を回避するための工夫についてご紹介します。

　　

　　うまく利用し、起き得る問題を起こさないように回避するための参考としてください。



工夫 １


 [ ユーザー自動同期モードの切り替え ]


 BioStar2の初期値では、PC(BioStar2)側で変更した情報が、適用するとすぐに反映されるように、自動同期の設定になっています。

WEBブラウザで操作する場合は、この方法がわかりやすく、推奨としています。


しかし、APIプログラムにより、連続でユーザー情報を更新する場合は、自動同期のまま複数のユーザー情報を更新すると

更新の内容によって（例えば全員のアクセス権限を変更するような処理の場合）は、


　　ユーザー１情報更新　→　全端末へ全員を同期 →

　　　ユーザー２情報更新　→　全端末へ全員を同期 → 

　　　　ユーザー３情報更新　→　全端末へ全員を同期 →

　　　　　・・・　


となり、1人更新するたびに、全員を全端末に転送しなおす。ということも起こりえます。


このため、APIプログラムにより、ユーザー情報を変更する場合は、以下のようにします。


　処理の開始前に、ユーザー自動同期の設定を ”利用しない” に変更

　　→　一ユーザー更新処理が完了した後に、ユーザー自動同期の設定を 元の状態に戻す

　　　→　端末と同期する


これにより、全員の変更処理が完了した後で、全員を1回端末と同期するようにしてください。



※　この部分の設定を、APIを使って変更してから処理します。

　　”利用しない” 以外の設定のまま、APIのユーザー更新処理を連続で行うと、APIの連続処理の途中で、

　　何度も端末と同期してしまいます。　API処理が終わってから、最後に1回、端末と同期するようにしましょう。






工夫 ２


 [ 最新ソフトウェア および 最新端末ファームウェアの利用 ]


弊社としても、可能な限り便利に使える方法を検討・改善しています。

最新のソフトウェアおよび端末ファームウェアにすることで、改善される場合もあります。


例えば、BioStar2 v2.9.0 以降（および、対象ファームウェア）では、ユーザーの部分更新に対応し、

ユーザーの情報を変更したら、何でも同期しなおし対象にするわけではなく、本当に更新が必要な内容が変更された

場合だけ、端末に再転送するような判断基準に改善しました。


また、 BioStar2 v2.9.7 以降（および、対象ファームウェア）では、 ビジュアルフェイスの実画像を端末に送らず、

テンプレート（実画像以外：認証に必要なデータ）だけを端末に転送し、同性能でデータ量を減らし、

転送時間を早くする機能オプションを選択できるよう工夫を行っています。


このように、BioStar2や、端末機のファームウェアバージョンをアップすることで、改善される部分をうまく利用してください。






工夫 ３


 [ 同期完了状態を把握する ]


発生し得る問題は、前回の同期が完了していない段階で、次の同期 → 次の同期 → ・・・ と、処理を重ねていくことが

原因で発生します。

このため、前の同期処理が完了したら、次のAPI処理を行うように工夫することで、問題を避けることができます。


しかし、APIでは、前の同期処理が完了したか？を直接、確認することができません。


ひと手間必要ですが、WEB Socketを利用して、端末の同期状態を確認することが可能です。


WEB Socketを利用すると、リアルタイムモニタリングを確認することができます。

当該端末に対して、ユーザー同期が動作している場合は、1秒間に 10～20人程度分の "ユーザー更新成功" のログが

連続出力されます。


WEB Socketを監視し、ユーザー更新成功のログの流れが、数秒間以上 止まった時が、同期処理が完了した時。と

判断できます。


これを監視し、次の同期処理を行うようにすることで、処理領域を超過することなく、正しいAPI処理を行えます。






工夫 ４


 [ PC スペックに余裕を持つ ]


問題は、APIによる繰り返し処理によって発生することがほとんどです。

このため、少しでも早くデータ処理が行われた方が、処理が破綻する可能性が低くなります。


BioStar2のヘルプには、PCの最低要求スペックが記載されていますが、あくまでも最低要求Specであり、

API開発により多量に処理されることを想定したスペックではありません。


このため、このような場合は、利用するサーバーPCのリソースにも余裕を持たせものを選定してください。







工夫 ５


 [ 他の製品も検討 ]


BioStar2としての直接的な工夫ではありませんが、多くのユーザーの多くのアクセス権限を頻繁に変更するような場合、

BioStar2を利用する方法以外も考えられます。


条件が合えばということにはなりますが、アクセス権限変更を外部システムにより実施する、CLUe の利用もご検討ください。