メインコンテンツへスキップ

Cassia RESTful APIの概要

Cassia Bluetoothゲートウェイは、エンタープライズ利用向けに設計された世界初の長距離Bluetoothゲートウェイであり、あらゆるサイズと規模のシームレスなカバレッジを可能にします。 Bluetoothの範囲を最大300m（オープンスペース、視線）まで拡張し、Bluetoothデバイスに変更を加えることなく複数のBluetooth Low Energy（BLE）デバイスのリモートコントロールを可能にします。

 

Cassia RESTful APIは、サードパーティの開発者とデバイスメーカーが、お客様のクラウドサービスを使用してゲートウェイごとに複数のBLEデバイスを同時に接続および制御しながら、CassiaゲートウェイのBluetoothルーティングと拡張範囲機能を利用できるようにするために開発されました。さらに、Cassia RESTful APIは、プログラミング言語の柔軟性（C＃、Node.js、Java、およびその他の任意の言語）を提供するHTTP / HTTPSベースの通信プロトコルを使用して、アプリケーションとサーバーに直接統合するように設計されています。詳細については以下参考URLを参照ください。

 

参考URL：Cassia SDK Implementation Guide

https://github.com/CassiaNetworks/CassiaSDKGuide/wiki

 

Cassia RESTful APIは、次の機能を提供します。

  • BLEデバイスを接続して制御
  • スキャン、接続、ブロードキャストの3つのモードをサポート
  • BLEデバイスとの間でデータの書き込み/読み取り
  • BLEデバイスから通知/表示イベントとしてデータを読み取り

 

2種類の構成

Cassiaは、BLEデバイスとCassiaゲートウェイの相互作用を可能にする構成として、Cassia IoT Access Controller （以下AC)を使用した構成と、ACを使用せずゲートウェイと直接やりとりをする構成（ローカルゲートウェイ）の大きく分けて2種類に対応しています。又、ローカルゲートウェイの構成では、ゲートウェイにRESTfulAPIでアクセスするアプリケーションの配置場所として、外部のアプリケーションサーバなどに配置するの場合と、ゲートウェイ内部のContaierにアプリケーションを配置する場合の2種類から選択いただくことが可能です。

それぞれの構成におけるCassia RESTful APIの動作図については、以下の図を参照してください。

 

構成１－１：ローカルゲートウェイ構成（外部アプリケーションからアクセス）

mceclip0.png

図1．同一ネットワーク上に存在するアプリケーションとの通信

 

構成１－２：ローカルゲートウェイ構成（内部Containerアプリケーションからアクセス）

mceclip2.png

図2．Container内のアプリケーションとの通信

 

構成２：AC経由構成

mceclip1.png

図3．アクセスコントローラを介したアプリケーションとの通信

 

2種類のRESTfulAPI

Cassiaは、BLEデバイスとCassiaゲートウェイの相互作用を可能にする構成として、ACを使用した構成と、ACを使用せずゲートウェイと直接やりとりをする構成（ローカルゲートウェイ）に対応したRESTfulAPIを提供します。

 

注意：
・コンテナから RESTful API にアクセスする場合は、コンテナの静的アドレス（10.10.10.254）を使用します。
・ローカルゲートウェイに外部アプリケーションサーバなどからアクセスする場合、ゲートウェイのIPアドレスは
使用しているWifi APのDHCP機能で払い出されたアドレスを確認するか、ACに接続されている場合はダッシュボード
から確認してください。
参考URL:CassiaゲートウェイのIPアドレス確認方法について
https://cptechweb.teldevice.co.jp/hc/ja/articles/4404230673689
・Cassia ACを介したRESTfulAPIには、{your AC domain}の後に"/ api"が含まれています。
　ローカルゲートウェイのRESTfulAPIには必要ありません。
・Cassia ACを介したRESTfulAPIには、使用されているゲートウェイを識別するための"mac="が含まれています。
　ローカルゲートウェイのRESTfulAPIには必要ありません。
・ファームウェア1.3以降では、ゲートウェイモードが”Standalone Gateway”として構成されている場合、
　ローカルのRESTfulAPIが自動的にオンになります。
（既定は”AC Managed Gateway"）ゲートウェイ”AC Managed Mode”として設定されている場合、
　ローカルRESTful APIはデフォルトでオフになります
（お客様はACコンソールからローカルRESTful APIを有効にできます）。
　設定方法は以下手順をご覧ください。

１．Cassia IoT アクセスコントローラー（Cassia AC）を介したAPI

APIはACを介して使用することができます。（アーキテクチャ図　図3）

ACは、強力なIoTネットワーク管理ソリューションです。これは、企業がデータ収集、配置、およびセキュリティポリシー管理を行うためのRESTful APIを提供し、インターネットを介したCassiaBluetoothゲートウェイのリモート制御を可能にします。

以下APIはAC経由のみ利用できます。これらのAPIを除いて、ローカルゲートウェイとAC2種類のRESTful APIは同じであり、同じ結果が得られます。

ACを介してRESTful API通信を利用する場合、まずビジネスアプリケーションは、ACに対して（開発者の資格情報を使用して生成された）OAuth認証要求を開始します。認証が成功すると、RESTfulに基づいてACにHTTPクエリを送信します。次に、ACは、暗号化されたMQTTを介して対応するBluetoothゲートウェイにクエリを送信します。次に、ゲートウェイはBLEデバイスに対してクエリを実行し、その結果をCassia ACに返し、次にビジネスアプリケーションに返します。

 

２．ローカルゲートウェイ上のAPI

ゲートウェイと同一ネットワーク上に存在するアプリケーション（アーキテクチャ図　図1）や、ゲートウェイ内Container上のアプリケーション（アーキテクチャ図　図2）からAPIを利用したい場合に使用します。既定ではローカルゲートウェイ上のAPIは無効になっている為、以下手順を参考に設定を有効にしてください。

 

ローカルゲートウェイ上のAPIを有効にする手順：

１．ローカルWebコンソールから設定する場合

ローカルWebコンソールにログインしBasicメニュー→Gateway Modeを”Standalone Gateway”に設定

 

mceclip0.png

 

２．Cassia アクセスコントローラ（AC）を使用して設定する場合

アクセスコントローラログインいただき以下操作ください。

 

1）Gatewayメニュー選択

2）操作したいCassia Gatewayのラインをクリック

 

mceclip1.png

３）Configメニュー選択しLocal RESTful APIを“ON”に設定

４）“Save”ボタンをクリック

 

mceclip2.png

 

Server Sent Events (SSE)
SSEは、ブラウザーがHTTP接続を介してサーバーから自動更新を受信するテクノロジーです。 SSE APIは、W3CによってHTML5の一部として標準化されています。 SSEは、メッセージの更新または継続的なデータストリームをブラウザクライアントに送信するために使用されます。手動で終了する必要があります。そうしないと、エラーが発生するまで実行を続けます。

 

SSE仕様：https：//html.spec.whatwg.org/multipage/server-sent-events.html#the-eventsource-interface

 

APIは、ユーザーが接続がアクティブかどうかを確認するために、SSE接続で30秒ごとに"keep-alive"を送信します。

キープアライブロスト、ソケットエラー、ネットワークの問題など、接続が異常に終了した場合、ユーザーはCassia RESTfulAPIを呼び出してSSEを再接続する必要があります。

Nodejsライブラリの"eventsource"はSSEの再接続を自動的に処理します。他の言語の場合、再接続はユーザーアプリケーションによって処理される必要がある場合があります。

 

6つのRESTfulAPIがSSEを使用しています。

各SSE応答は、”data”始まります。デバッグ時に、SSEのURLをWebブラウザーに入力すると、WebブラウザーからのSSE出力が表示されます。

プログラムでは、通常のHTTPリクエストのようにインターフェースを呼び出すと、SSEリクエストはデータを返しません。これは、通常のHTTPリクエストは終了したときにのみ出力を返すためです。さらに、SSEを呼び出すときは、このスレッドを監視する必要があります。エラーまたは予期しないインシデントによって中断された場合は、再起動できます。

注意：
・SSE ストリームは、ゲートウェイあたり約 20～30 個に制限されています。
一度に多くの SSE ストリームを開くと、ゲートウェイシステムに十分なリソースがないため、
500 エラーが発生することがあります。SSE 接続を閉じる（ストリームを明示的に閉じる）ことを強く推奨します。
ライブラリには、ストリームを明示的に閉じるための .close() のような close 呼び出しが用意されていることが
あります。また、SSE ハンドラを終了した後に自動的にストリームを閉じる場合もあります。

 

注意：
・HTTPリクエストにCURLなどのツールを使用する場合、ツールはHTTPリクエストが終了したときにデータを返します。
ただし、SSE APIは終了せず、ストリームでデータを送信するため、ページがハングします。
次のスニペットを追加する必要があります（例としてスキャンを使用）。

 

PHP

if ($stream = fopen($url_for_scan, 'r')) {
  while(($line=fgets($stream))!== false){
    echo $line;
  }
}

 

[Update]

更新日：202405

関連記事